Playwright API Mock

A Playwright plugin for seamlessly recording and mocking API responses, accelerating your testing workflow.

🚀 Features

Automatic API recording into snapshot files.
Instant response mocking from saved snapshots for faster tests.
Flexible request matching (wildcards & regular expressions).
Configurable logging (silent, error, info levels).
Easy integration with Playwright's fixture system.

📦 Installation

npm add -D playwright-api-mock

🛠️ Usage

✅ Automatically Record and Mock API Responses

Extend Playwright's page fixture to automatically record and mock API calls:

// fixtures.ts
import { test as base } from '@playwright/test';
import { ApiMockPlugin } from 'playwright-api-mock';

export const test = base.extend({
  page: async ({ page }, use) => {
    const apiMock = new ApiMockPlugin(page, {
      urlMatch: '**/api/**',
      apiSnapshotsPath: '__snapshots__/api.json',
      logLevel: 'info',
      mock: true,
    });
    await apiMock.record();
    await use(page);
  },
});

Then, simply use your extended fixture in tests:

import { test, expect } from './fixtures';

test('Fetch user data', async ({ page }) => {
  await page.goto('/users/123');
  const text = await page.locator('body').textContent();
  expect(text).toContain('User');
});

🔧 Create a Custom Fixture

Alternatively, create a standalone API mock fixture for flexible usage:

import { test as base } from '@playwright/test';
import { ApiMockPlugin } from 'playwright-api-mock';

export const test = base.extend({
  apiMock: async ({ page }, use) => {
    const plugin = new ApiMockPlugin(page);
    await use(plugin);
  },
});

Then use it explicitly in your tests:

import { test, expect } from './fixtures';

test.describe('User Page', () => {
  test.beforeEach(async ({ apiMock }) => {
    await apiMock.record({
      urlMatch: '**/api/user/**',
      apiSnapshotsPath: '__snapshots__/userApi.json',
      mock: true,
    });
  });

  test('Load user data', async ({ page }) => {
    await page.goto('/users/123');
    const text = await page.locator('body').textContent();
    expect(text).toContain('User');
  });
});

⚙️ Configuration

Customize your plugin by passing an options object:

Note: This plugin currently records and replays only JSON responses. Requests returning non-JSON content will pass through without being stored.

const apiMock = new ApiMockPlugin(page, {
  urlMatch: '**/api/**',
  apiSnapshotsPath: '__snapshots__/api.json',
  logLevel: 'info',
  mock: true,
  getStoredHeaders: (headers) => {
    // optionally filter or modify headers before storing
    return { 'content-type': headers['content-type'] };
  },
});

PluginConfig interface

Option	Type	Default	Description
`urlMatch`	`string \| RegExp`	`*/`	Request URLs to record/mock
`apiSnapshotsPath`	`string`	`api_snapshots.json`	Path to store/load snapshot files
`logLevel`	`'silent' \| 'error' \| 'info'`	`'info'`	Level of logging detail
`mock`	`boolean`	`true`	Use stored snapshots instead of real responses
`getStoredHeaders`	`(headers) => headers \| undefined`	`undefined`	Function to modify or filter headers before saving

📖 API Methods

`record(config?: Partial<PluginConfig>): Promise<void>`

Starts intercepting and recording API responses. Optionally override configuration per test or fixture.

🤝 How to Contribute

Fork and clone this repository.
Install dependencies with bun install and build the project:
```
bun run build
```

Explore the example Playwright project under test/demo/:

bun run demo:start # optional: run the backend server
bun run demo:test

Create feature branches for your changes and open a pull request.

📜 License

MIT License. See LICENSE for details.

Package detail