Configuring Playwright

To run tests using playwright, you need to install the @vitest/browser-playwright npm package and specify its playwright export in the test.browser.provider property of your config:

vitest.config.js

import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      provider: playwright(),
      instances: [{ browser: 'chromium' }]
    },
  },
})

You can configure the launchOptions, connectOptions and contextOptions when calling playwright at the top level or inside instances:

vitest.config.js

import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      // shared provider options between all instances
      provider: playwright({
        launchOptions: {
          slowMo: 50,
          channel: 'chrome-beta',
        },
        actionTimeout: 5_000,
      }),
      instances: [
        { browser: 'chromium' },
        {
          browser: 'firefox',
          // overriding options only for a single instance
          // this will NOT merge options with the parent one
          provider: playwright({
            launchOptions: {
              firefoxUserPrefs: {
                'browser.startup.homepage': 'https://example.com',
              },
            },
          })
        }
      ],
    },
  },
})

WARNING

Unlike Playwright Test, Vitest does not create a new browser context for every test or for every test file. Tests in the same file share browser state, and test files can also share browser storage (see contextOptions).

launchOptions

These options are directly passed down to playwright[browser].launch command. You can read more about the command and available arguments in the Playwright documentation.

WARNING

Vitest will ignore launch.headless option. Instead, use test.browser.headless.

Note that Vitest will push debugging flags to launch.args if --inspect is enabled.

Enabling new Chromium headless mode

Playwright supports a new headless mode for Chromium that uses the real Chrome browser instead of the dedicated headless shell. This provides more authentic, reliable test execution and removes the need to install a separate headless Chromium build.

To opt in, set channel to 'chromium' in launchOptions:

vitest.config.ts

import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      headless: true,
      provider: playwright({
        launchOptions: {
          channel: 'chromium',
        },
      }),
      instances: [{ browser: 'chromium' }],
    },
  },
})

connectOptions

These options are directly passed down to playwright[browser].connect command. You can read more about the command and available arguments in the Playwright documentation.

Use connectOptions.wsEndpoint to connect to an existing Playwright server instead of launching browsers locally. This is useful for running browsers in Docker, in CI, or on a remote machine.

WARNING

Vitest forwards launchOptions to Playwright server via the x-playwright-launch-options header. This works only if the remote Playwright server supports this header, for example when using the playwright run-server CLI.

Example: Running a Playwright Server in Docker

To run browsers in a Docker container (see Playwright Docker guide):

Start a Playwright server using Docker Compose:

docker-compose.yml

services:
  playwright:
    image: mcr.microsoft.com/playwright:v1.61.0-noble
    command: /bin/sh -c "npx -y playwright@1.61.0 run-server --port 6677 --host 0.0.0.0"
    init: true
    ipc: host
    user: pwuser
    ports:
      - '6677:6677'

docker compose up -d

Then configure Vitest to connect to it. The exposeNetwork option lets the containerized browser reach Vitest's dev server on the host:

vitest.config.ts

import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      provider: playwright({
        connectOptions: {
          wsEndpoint: 'ws://127.0.0.1:6677/',
          exposeNetwork: '<loopback>',
        },
      }),
      instances: [
        { browser: 'chromium' },
        { browser: 'firefox' },
        { browser: 'webkit' },
      ],
    },
  },
})

contextOptions

By default, Vitest creates a browser context by calling browser.newContext(). You can configure this behaviour by specifying custom arguments.

TIP

Vitest does not create a new context for every test file. Test files can reuse a context, so cookies, localStorage, and other browser storage that one test file sets can be visible in test files that run later.

WARNING

Vitest always sets ignoreHTTPSErrors to true, so that tests can run when your server uses an HTTPS certificate that the browser does not trust, such as a self-signed certificate.

It is also recommended to use test.browser.viewport instead of specifying it here as it will be lost when tests are running in headless mode.

actionTimeout

• Default: no timeout

This value configures the default timeout it takes for Playwright to wait until all accessibility checks pass and the action is actually done.

You can also configure the action timeout per-action:

import { page, userEvent } from 'vitest/browser'

await userEvent.click(page.getByRole('button'), {
  timeout: 1_000,
})

persistentContext 4.1.0+

• Type: boolean | string
• Default: false

When enabled, Vitest uses Playwright's persistent context instead of a regular browser context. This allows browser state (cookies, localStorage, DevTools settings, etc.) to persist between test runs.

WARNING

This option is ignored when running tests in parallel (e.g. when headless with fileParallelism enabled) since persistent context cannot be shared across parallel sessions.

• When set to true, the user data is stored in ./node_modules/.cache/vitest-playwright-user-data
• When set to a string, the value is used as the path to the user data directory

vitest.config.js

import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      provider: playwright({
        persistentContext: true,
        // or specify a custom directory:
        // persistentContext: './my-browser-data',
      }),
      instances: [{ browser: 'chromium' }],
    },
  },
})