浏览器模式 实验性

本页提供关于 Vitest API 中实验性浏览器模式功能的信息。该功能允许你在浏览器中本地运行测试，从而可以访问诸如 window 和 document 之类的浏览器全局变量。此功能目前仍在开发中，API 未来可能会发生变化。

浏览器兼容性

Vitest 使用 Vite dev server 运行你的测试，因此我们只支持在 esbuild.target 选项中指定的功能（默认为 esnext）。

默认情况下，Vite 针对支持原生 ES Modules、原生 ESM 动态导入 和 import.meta 的浏览器。此外，我们还利用 BroadcastChannel 在 iframe 之间进行通信：

• Chrome >=87
• Firefox >=78
• Safari >=15.4
• Edge >=88

动机

我们开发 Vitest 浏览器模式功能是为了帮助改进测试工作流程，并获得更准确和可靠的测试结果。这个实验性的测试 API 新增功能允许开发者在原生浏览器环境中运行测试。在本节中，我们将探讨此功能背后的动机及其对测试的好处。

不同的测试方式

测试 JavaScript 代码有多种方式。一些测试框架在 Node.js 中模拟浏览器环境，而另一些则在真实的浏览器中运行测试。例如，jsdom 是一个规范实现的示例，它通过与 Jest 或 Vitest 等测试运行器一起使用来模拟浏览器环境，而 WebdriverIO 或 Cypress 允许开发者在真实的浏览器中测试他们的应用程序，Playwright 则直接提供了浏览器引擎。

模拟环境的局限性

在诸如 jsdom 或 happy-dom 之类的模拟环境中测试 JavaScript 程序简化了测试设置，并提供了易于使用的 API，使其适用于许多项目并提高了对测试结果的信心。但是，至关重要的是要记住，这些工具仅模拟浏览器环境，而不是实际的浏览器，这可能导致模拟环境与真实环境之间存在差异。因此，可能会出现测试结果的假阳性或假阴性。

为了确保测试结果具有最高的可靠性，在真实的浏览器环境中进行测试至关重要。这就是我们在 Vitest 中开发浏览器模式功能的原因，该功能允许开发者在浏览器中原生运行测试，并获得更准确和可靠的测试结果。通过浏览器级别的测试，开发者可以更有信心地确保他们的应用程序在真实场景中按预期工作。

缺点

使用 Vitest 浏览器时，重要的是要考虑以下缺点：

早期开发阶段

Vitest 的浏览器模式功能仍处于开发的早期阶段。因此，它可能尚未完全优化，并且可能存在一些尚未解决的错误或问题。建议用户使用独立的浏览器测试运行器（如 WebdriverIO、Cypress 或 Playwright）来提升 Vitest 浏览器的使用体验。

更长的初始化时间

Vitest 浏览器需要在初始化过程中启动 provider 和浏览器，这可能需要一些时间，导致初始化时间更长。

配置

要在 Vitest 配置中激活浏览器模式，你可以使用 --browser 标志，或者在 Vitest 配置文件中将 browser.enabled 字段设置为 true。以下是使用 browser 字段的配置示例：

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      name: 'chrome', // browser name is required
    },
  },
});

浏览器选项类型：

Vitest 中 browser 选项的具体行为取决于 provider。如果你传递了 --browser 但未在配置文件中指定名称，Vitest 会运行失败。可用选项：

• webdriverio (默认) 支持以下浏览器：
  • firefox
  • chrome
  • edge
  • safari
• playwright 支持以下浏览器：
  • firefox
  • webkit
  • chromium

跨浏览器测试：

当你在 browser 选项中指定浏览器名称时，Vitest 将默认尝试使用 WebdriverIO 运行指定的浏览器，然后在其中运行测试。此功能使得在 CI 等环境中进行跨浏览器测试变得简单易用。如果你不想使用 WebdriverIO，你可以使用 browser.provider 选项配置自定义浏览器 provider。

要使用 CLI 指定浏览器，请使用 --browser 标志，后跟浏览器名称，如下所示：

npx vitest --browser=chrome

或者你可以使用点表示法向 CLI 提供浏览器选项：

npx vitest --browser.name=chrome --browser.headless

NOTE

将 Safari 浏览器选项与 WebdriverIO 结合使用时，需要通过在你的设备上运行 sudo safaridriver --enable 来激活 safaridriver。

此外，在运行测试时，Vitest 将尝试安装一些驱动程序，以与 safaridriver 兼容。

无头模式 (Headless)

无头模式 (Headless) 是浏览器模式的另一个可用选项。在 headless 模式下，浏览器在没有用户界面的后台运行，这使得它对于运行自动化测试非常有用。Vitest 中的 headless 选项可以设置为布尔值，以启用或禁用 headless 模式。

以下是启用 headless 模式的配置示例：

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

你也可以在 CLI 中使用 --browser.headless 标志设置 headless 模式，如下所示：

npx vitest --browser.name=chrome --browser.headless

在这种情况下，Vitest 将在 headless 模式下使用 Chrome 浏览器运行。

局限性

线程阻塞对话框

使用 Vitest 浏览器时，需要注意的是，不能直接使用 alert 或 confirm 等线程阻塞对话框。这是因为它们会阻塞网页，这意味着 Vitest 无法继续与页面通信，从而导致执行被阻塞。

在这种情况下，Vitest 会为这些 API 提供默认的 mocks（模拟），并设置默认返回值。这样可以确保，即使开发者不小心使用了同步弹窗 web API，执行也不会卡死。但仍建议用户对这些 web API 进行模拟，以获得更好的体验。阅读更多信息请参考 Mocking。