MSW Playwright Binding

To use @msw/playwright, you should extend the Playwright test object with a network fixture. This is done using defineNetworkFixture.

Recommended setup pattern:

1. Define a handlers fixture containing your base MSW handlers.
2. Define a network fixture that uses defineNetworkFixture to wrap the Playwright context and handlers.
3. Call network.enable() before the test runs and network.disable() after it completes.
4. Set { auto: true } on the fixture so it is automatically initialized for every test.

// playwright.setup.ts
import { test as testBase } from '@playwright/test'
import { type AnyHandler } from 'msw'
import { defineNetworkFixture, type NetworkFixture } from '@msw/playwright'
import { handlers } from '../mocks/handlers.js'

interface Fixtures {
  handlers: Array<AnyHandler>
  network: NetworkFixture
}

const test = testBase.extend<Fixtures>({
  // Initial list of the network handlers.
  handlers: [handlers, { option: true }],

  // A fixture you use to control the network in your tests.
  network: [
    async ({ context, handlers }, use) => {
      const network = defineNetworkFixture({
        context,
        handlers,
      })

      await network.enable()
      await use(network)
      await network.disable()
    },
    { auto: true },
  ],
})

The playwright.config.ts file defines the execution environment for Playwright tests. Key configuration areas include:

• testDir: Specifies the directory where tests are located.
• projects: Defines different browser configurations (e.g., chromium) using Playwright devices.
• use: Global settings for all tests, such as baseURL, screenshot behavior, video retention, and launchOptions (e.g., enabling devtools).
• webServer: Automatically starts and manages the application server before running tests. It uses a command to start the app and a url to verify it is ready. The reuseExistingServer option allows using an already running server, which is useful in local development.
• forbidOnly: Prevents tests from running if .only is present in the code, typically enabled in CI environments to ensure full test suites run.
• fullyParallel: Enables running tests in parallel to improve speed.
• reporter: Sets the output format for test results (e.g., 'list').

import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
  use: {
    baseURL: 'http://localhost:5173',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    launchOptions: {
      devtools: !process.env.CI,
    },
  },
  forbidOnly: !!process.env.CI,
  fullyParallel: true,
  reporter: 'list',
  webServer: {
    command: 'npm run app:build && npm run app:start',
    url: 'http://localhost:5173',
    reuseExistingServer: !process.env.CI,
    stderr: 'pipe',
  },
})

Use defineNetworkFixture to create a network mocking instance for a Playwright BrowserContext. This fixture allows you to intercept HTTP and WebSocket requests using MSW handlers.

Options

• context: The Playwright BrowserContext to attach the fixture to.
• handlers: An array of MSW handlers (AnyHandler) to use for mocking.
• onUnhandledRequest: Strategy for handling requests that don't match any handler (e.g., 'bypass', 'error', 'warn').
• skipAssetRequests: (Boolean, default: true) If true, common asset requests (like .css, .js, .html) are skipped to improve performance. Set to false if you need to mock these assets.

import { defineNetworkFixture } from '@msw/playwright';
import { http, rest } from 'msw';

const networkFixture = defineNetworkFixture({
  context: browserContext,
  handlers: [
    http.get('/api/user', () => {
      return HttpResponse.json({ id: '1', name: 'John Doe' });
    }),
  ],
  skipAssetRequests: true,
});

// To start intercepting:
await networkFixture.enable();

// To stop intercepting:
await networkFixture.disable();