浏览器模式 实验性

此页面提供有关 Vitest API 中实验性浏览器模式功能的信息，该功能允许你在浏览器中本地运行测试，提供对 window 和 document 等浏览器全局变量的访问。此功能目前正在开发中，API 未来可能会更改。

浏览器兼容性

Vitest 使用 Vite 开发服务器 来运行您的测试，因此我们只支持 esbuild.target选项（默认为 esnext）中指定的功能。

默认情况下，Vite 的目标浏览器支持本地 ES Modules、原生 ESM dynamic import 和 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 浏览器在初始化过程中需要启动提供程序和浏览器，这可能需要一些时间。与其他测试模式相比，这可能导致更长的初始化时间。

配置

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

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      name: 'chrome', // 浏览器名称必填
    },
  },
})

浏览器选项类型

Vitest 中的浏览器选项取决于提供者。如果你传递 --browser 并且未在配置文件中指定其名称，Vitest 将失败。可用选项：

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

跨浏览器测试

当你在浏览器选项中指定浏览器名称时，Vitest 将默认尝试使用 WebdriverIO 运行指定的浏览器，然后在那里运行测试。此功能使跨浏览器测试易于在 CI 等环境中使用和配置。如果不想使用 WebdriverIO，可以使用 browser.provider 选项配置自定义浏览器提供程序。

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

npx vitest --browser=chrome

或者你可以使用点符号向 CLI 提供浏览器选项：

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

NOTE

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

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

无头模式

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

这是启用无头模式的示例配置：

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

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

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

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

限制

线程阻塞对话框

使用 Vitest 浏览器时，需要注意的是像 alert 或 confirm 这样的线程阻塞对话框不能在本地使用。这是因为它们阻塞了网页，这意味着 Vitest 无法继续与该页面通信，导致执行挂起。

在这种情况下，Vitest 为这些 API 提供默认模拟和默认返回值。这确保如果用户不小心使用了同步弹出式 Web API，执行不会挂起。但是，仍然建议用户模拟这些 Web API 以获得更好的体验。在 模拟 中阅读更多内容。