浏览器配置

你可以通过更新 配置文件 中的 test.browser 字段来配置浏览器。以下是一个简单的配置示例：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [
        {
          browser: 'chromium',
          setupFile: './chromium-setup.js',
        },
      ],
    },
  },
});

请参阅 "配置参考" 以获取更多配置示例。

WARNING

本页列出的所有选项都位于配置的 test 属性内：

export default defineConfig({
  test: {
    browser: {},
  },
});

browser.enabled

• 类型: boolean
• 默认值: false
• CLI: --browser, --browser.enabled=false

默认情况下，在浏览器中运行所有测试。请注意，--browser 仅在你至少配置了一个 browser.instances 时才有效。

browser.instances

• 类型: BrowserConfig
• 默认值: [{ browser: name }]

定义多个浏览器配置。每个配置必须至少包含一个 browser 属性。此配置支持你所使用的提供者的特定配置：

• 配置 Playwright
• 配置 WebdriverIO

TIP

为了在使用内置提供者时获得更好的类型安全，你应该在你的 配置文件 中引用相应的类型（为你正在使用的提供者）：

/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

此外，你还可以指定大多数 项目选项（未带有 * 图标的）以及一些 browser 选项，例如 browser.testerHtmlPath。

WARNING

每个浏览器配置都继承自根配置的选项：

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // 将同时拥有 "root" 和 "browser" 两个 setup 文件
          setupFile: ['./browser-setup-file.js'],
          // 隐式地从根配置中获取 "testerHtmlPath"
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

在开发过程中，Vitest 仅支持一个 非无头 配置。你可以通过在配置中指定 headless: false，或者通过提供 --browser.headless=false 标志，或者通过使用 --project=chromium 标志过滤项目来限制有头模式的项目。

有关更多示例，请参阅 "多重设置" 指南。

可用 browser 选项列表：

• browser.headless
• browser.locators
• browser.viewport
• browser.testerHtmlPath
• browser.screenshotDirectory
• browser.screenshotFailures

默认情况下，Vitest 创建一个包含单个元素的数组，该元素使用 browser.name 属性作为 browser。请注意，此行为将在 Vitest 4 中移除。

Vitest 在底层将这些实例转换为独立的 测试项目，它们共享一个 Vite 服务器以获得更好的缓存性能。

browser.name 已废弃

• 类型: string
• CLI: --browser=safari

已废弃

此 API 已废弃，并将在 Vitest 4 中移除。请改用 browser.instances 选项。

在指定浏览器中运行所有测试。不同提供者中可能的选项：

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• 自定义: 任何传递给提供者的字符串

browser.headless

• 类型: boolean
• 默认值: process.env.CI
• CLI: --browser.headless, --browser.headless=false

以无头模式运行浏览器。如果你在 CI 环境中运行 Vitest，它将默认启用。

browser.isolate

• 类型: boolean
• 默认值: true
• CLI: --browser.isolate, --browser.isolate=false

每个测试都在单独的 iframe 中运行。

browser.testerHtmlPath

• 类型: string

HTML 入口文件的路径。可以是相对于项目根目录的路径。此文件将通过 transformIndexHtml 钩子处理。

browser.api

• 类型: number | { port?, strictPort?, host? }
• 默认值: 63315
• CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

配置 Vite 服务器的选项，该服务器用于在浏览器中提供代码。不影响 test.api 选项。默认情况下，Vitest 分配端口 63315 以避免与开发服务器冲突，允许你并行运行两者。

browser.provider

• 类型: 'webdriverio' | 'playwright' | 'preview' | string
• 默认值: 'preview'
• CLI: --browser.provider=playwright

运行浏览器测试时将使用的提供者路径。Vitest 提供三个内置提供者：preview（默认）、webdriverio 和 playwright。自定义提供者应使用 default 导出，并应符合以下接口：

export interface BrowserProvider {
  name: string;
  supportsParallelism: boolean;
  getSupportedBrowsers: () => readonly string[];
  beforeCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  afterCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  getCommandsContext: (sessionId: string) => Record<string, unknown>;
  openPage: (
    sessionId: string,
    url: string,
    beforeNavigate?: () => Promise<void>
  ) => Promise<void>;
  getCDPSession?: (sessionId: string) => Promise<CDPSession>;
  close: () => Awaitable<void>;
  initialize(
    ctx: TestProject,
    options: BrowserProviderInitializationOptions
  ): Awaitable<void>;
}

高级 API

自定义提供者 API 仍处于高度实验阶段，并且可能在补丁版本更新时发生变化。如果你只需要在浏览器中运行测试，请改用 browser.instances 选项。

browser.providerOptions 已废弃

• 类型: BrowserProviderOptions

已废弃

此 API 已废弃，并将在 Vitest 4 中移除。请改用 browser.instances 选项。

调用 provider.initialize 时将传递给提供者的选项。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
      },
    },
  },
});

TIP

为了在使用内置提供者时获得更好的类型安全，你应该在你的 配置文件 中引用相应的类型（为你正在使用的提供者）：

/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

browser.ui

• 类型: boolean
• 默认值: !isCI
• CLI: --browser.ui=false

Vitest UI 是否应注入到页面中。默认情况下，在开发过程中注入 UI iframe。

browser.viewport

• 类型: { width, height }
• 默认值: 414x896

默认 iframe 视口。

browser.locators

内置 浏览器定位器 的选项。

browser.locators.testIdAttribute

• 类型: string
• 默认值: data-testid

用于通过 getByTestId 定位器查找元素的 HTML 属性。

browser.screenshotDirectory

• 类型: string
• 默认值: 测试文件目录中的 __screenshots__

截图保存目录的路径，相对于 root。

browser.screenshotFailures

• 类型: boolean
• 默认值: !browser.ui

如果测试失败，Vitest 是否应截屏。

browser.orchestratorScripts

• 类型: BrowserScript[]
• 默认值: []

在测试 iframe 启动之前，应注入到协调器 HTML 文档中的自定义脚本。此 HTML 文档仅设置 iframe，并不实际导入你的代码。

脚本的 src 和 content 将通过 Vite 插件进行处理。脚本应符合以下接口：

export interface BrowserScript {
  /**
   * 如果提供了 "content" 且类型为 "module"，它将作为其标识符。
   *
   * 例如，如果你正在使用 TypeScript，你可以在此添加 `.ts` 扩展名。
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * 待注入的 JavaScript 内容。如果类型为 "module"，此字符串将通过 Vite 插件进行处理。
   *
   * 你可以使用 `id` 来向 Vite 提供文件扩展名的线索。
   */
  content?: string;
  /**
   * 脚本的路径。此值将由 Vite 解析，因此它可以是 Node 模块或文件路径。
   */
  src?: string;
  /**
   * 脚本是否应异步加载。
   */
  async?: boolean;
  /**
   * 脚本类型。
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

• 类型: BrowserScript[]
• 默认值: []

已废弃

此 API 已废弃，并将在 Vitest 4 中移除。请改用 browser.testerHtmlPath 字段。

在测试环境启动之前，应注入到测试器 HTML 文档中的自定义脚本。这对于注入 Vitest 浏览器实现所需的 polyfill 非常有用。在几乎所有情况下，建议使用 setupFiles 选项，而非此选项。

脚本的 src 和 content 将通过 Vite 插件进行处理。

browser.commands

• 类型: Record<string, BrowserCommand>
• 默认值: { readFile, writeFile, ... }

在浏览器测试期间可以从 @vitest/browser/commands 导入的自定义 命令。

browser.connectTimeout

• 类型: number
• 默认值: 60_000

连接到浏览器的超时时长（毫秒）。如果连接耗时超过此值，测试套件将失败。

INFO

这是浏览器与 Vitest 服务器建立 WebSocket 连接所需的时长。在正常情况下，不会触发此超时。