配置 Playwright

要使用 playwright 运行测试，你需要安装 @vitest/browser-playwright npm 包，并在配置中的 test.browser.provider 属性中指定其 playwright 导出：

vitest.config.js

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

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

你可以在顶层或实例内部调用 playwright 时配置 launchOptions、connectOptions 和 contextOptions：

vitest.config.js

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

export default defineConfig({
  test: {
    browser: {
      // 所有实例之间共享提供者选项
      provider: playwright({
        launchOptions: {
          slowMo: 50,
          channel: 'chrome-beta',
        },
        actionTimeout: 5_000,
      }),
      instances: [
        { browser: 'chromium' },
        {
          browser: 'firefox',
          // 仅为单个实例覆盖选项
          // 这不会将选项与父选项合并
          provider: playwright({
            launchOptions: {
              firefoxUserPrefs: {
                'browser.startup.homepage': 'https://example.com',
              },
            },
          })
        }
      ],
    },
  },
})

WARNING

与 Playwright 测试运行器不同，Vitest 打开一个_single_页面来运行同一文件中定义的所有测试。这意味着隔离仅限于单个测试文件，而不是每个测试。

launchOptions

这些选项直接传递给 playwright[browser].launch 命令。我们可以在 Playwright 文档 中阅读有关该命令和可用参数的更多信息。

WARNING

Vitest 将忽略 launch.headless 选项。请改用 test.browser.headless。

请注意，如果启用了 --inspect，Vitest 会将调试标志推送到 launch.args。

启用新版 Chromium 无头模式

Playwright 支持 Chromium 的 新版无头模式，该模式使用真实的 Chrome 浏览器而非专用的无头 shell。这能提供更真实可靠的测试执行，且无需安装单独的无头 Chromium 构建版本。

启用方式：在 launchOptions 中设置 channel 为 'chromium'：

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

这些选项直接传递给 playwright[browser].connect 命令。你可以在 Playwright 文档 中了解更多关于该命令和可用参数的信息。

通过 connectOptions.wsEndpoint 可连接现有 Playwright 服务器，而无需在本地启动浏览器。此功能适用于在 Docker、CI 或远程机器中运行浏览器场景。

WARNING

Vitest 会通过 x-playwright-launch-options 请求头将 launchOptions 转发至 Playwright 服务器。仅当远程 Playwright 服务器支持该请求头时此功能才生效，例如使用 playwright run-server CLI 时。

示例：在 Docker 中运行 Playwright 服务器

要在 Docker 容器中运行浏览器（参见 Playwright Docker 指南）：

使用 Docker Compose 启动 Playwright 服务器：

docker-compose.yml

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

docker compose up -d

然后配置 Vitest 连接到该服务器。exposeNetwork 选项允许容器化浏览器访问主机上的 Vitest 开发服务器：

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

Vitest 通过调用 browser.newContext() 为每个测试文件创建一个新的上下文。你可以通过指定 自定义参数 来配置此行为。

TIP

请注意，上下文是为每个 测试文件 创建的，而不是像 Playwright 测试运行器那样为每个 测试 创建。

WARNING

如果我们的服务器通过 HTTPS 提供服务，Vitest 始终将 ignoreHTTPSErrors 设置为 true，并将 serviceWorkers 设置为 'allow'，以支持通过 MSW 进行模块模拟。

建议使用 test.browser.viewport 而不是在此处指定它，因为在无头模式下运行测试时会丢失该设置。

actionTimeout

• 默认: 无超时

此值配置 Playwright 等待所有可访问性检查通过并 操作 实际完成的默认超时时间。

我们还可以为每个操作配置操作超时：

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

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

persistentContext 4.1.0+

• 类型: boolean | string
• 默认值: false

启用后，Vitest 将使用 Playwright 的 持久化上下文 替代常规浏览器上下文。这使得浏览器状态（如 cookies、localStorage、DevTools 设置等）能在测试运行间保留。

WARNING

该选项在并行运行测试时会被忽略（例如启用 fileParallelism 的无头模式场景），因为持久化上下文无法跨并行会话共享。

• 设为 true 时，用户数据存储在 ./node_modules/.cache/vitest-playwright-user-data
• 设为字符串时，该值将作为用户数据目录路径

vitest.config.js

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

export default defineConfig({
  test: {
    browser: {
      provider: playwright({
        persistentContext: true,
        // 或指定自定义目录：
        // persistentContext: './my-browser-data',
      }),
      instances: [{ browser: 'chromium' }],
    },
  },
})