第19章 Vitest UI 使用指南

Vitest UI

Vitest UI 是一个可视化界面，用于探索测试结果。你可以在测试运行时交互式地使用它，也可以将其作为静态 HTML 报告来查看已完成的运行记录。Vitest UI 是可选功能，因此你需要先安装它：

bash
npm i -D @vitest/ui

实时界面（Live UI）

实时界面与 Vitest 开发服务器并行运行，需要 watch 模式（默认已启用）。它保持与正在运行的 Vitest 进程的实时连接，因此在测试重新运行时，结果会即时更新。你还可以重新运行选中的测试、更新失败的快照，甚至直接从界面编辑测试文件。

传递 --ui 标志即可启动：

bash
vitest --ui

然后访问 http://localhost:51204/__vitest__/ 查看 Vitest UI。

提示
Vitest UI 的访问受到保护。如果直接访问 URL 显示错误，请使用终端中 Vitest 打印的 token 打开 URL，例如 http://localhost:51204/__vitest__/?token=...。

HTML 报告器（HTML Reporter）

HTML 报告器会将测试结果写入 Vitest UI 的静态版本。结果视图保持可导航，但报告是只读的，无法重新运行测试、更新快照或编辑测试文件。它适用于 run 模式、CI 和自动化工作流，方便后续查看结果。

你可以在命令行或 Vitest 配置中使用 html 报告器：

vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    reporters: ['html'],
  },
})

bash
vitest run --reporter=html

保留终端输出

配置 HTML 报告器会替换默认的终端报告器。若需保留终端输出，请包含 Vitest 的默认报告器：

vitest.config.ts
import { configDefaults, defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    reporters: ['html', ...configDefaults.reporters],
  },
})

本地预览

默认情况下，报告入口文件写入 .vitest/index.html。你可以通过 HTML 报告器的 outputDir 选项配置产物目录。

要预览默认输出，使用 vite preview 命令：

sh
npx vite preview --outDir .vitest

在浏览器中打开 Vite 打印的 URL。或者，VS Code 的集成浏览器可以直接打开 .vitest/index.html，无需预览服务器。

共享为单文件

设置 singleFile 可生成自包含的 HTML 报告：

vitest.config.ts
export default defineConfig({
  test: {
    reporters: [
      ['html', { singleFile: true }],
    ],
  },
})

启用 singleFile 后，Vitest 会将 UI 资源、元数据和测试附件内联到单个自包含的 index.html 中。这使得报告更容易共享、上传或作为单个产物下载，而无需保留整个输出目录。

由于所有内容均被内联，你可以直接使用 file:// 协议在浏览器中打开 <outputDir>/index.html，无需预览服务器。

警告
singleFile 有两个注意事项：

• 文件可能会变得非常大，因为所有内容都嵌入其中。打开速度可能较慢、内存占用高，或者超出产物查看器和静态托管平台的大小限制。
• Coverage HTML 报告目前尚未内联，仍作为单独文件存在。

如果测试套件包含大量或较大的附件，或需要在压缩包中包含 coverage，建议优先使用默认的多文件报告。

从 CI 查看报告

要从 CI（例如 GitHub Actions）中查看 HTML 报告，请上传输出目录作为产物：

yaml
- uses: actions/upload-artifact@v7
  id: upload-report
  with:
    name: vitest-report
    path: .vitest/

- name: Link HTML report
  run: echo "::notice title=Vitest HTML report::$REPORT_URL"
  env:
    REPORT_URL: https://viewer.vitest.dev/?url=${{ steps.upload-report.outputs.artifact-url }}

这会将报告链接添加为工作流运行的 notice 注释。点击它即可在浏览器中通过 Vitest Viewer 直接打开报告。你还可以手动下载并解压缩产物，然后像上面一样在本地运行 vite preview。

使用 singleFile: true 时，你可以将报告作为单个文件上传，并通过 archive: false 选项直接从 GitHub 产物中查看：

yaml
- uses: actions/upload-artifact@v7
  id: upload-report
  with:
    path: .vitest/index.html
    archive: false

- name: Link HTML report
  run: echo "::notice title=Vitest HTML report::$REPORT_URL"
  env:
    REPORT_URL: ${{ steps.upload-report.outputs.artifact-url }}

Coverage

Vitest UI 在实时界面和 HTML 报告中均显示 coverage 结果。有关设置和使用方法，请参阅 Vitest UI Coverage 文档。

Trace View

启用 browser.traceView 后，Vitest UI 会重放记录的浏览器交互。实时界面会在测试运行时流式传输 trace 条目，而 HTML 报告会保存记录的 trace 以便后续查看。

模块图（Module Graph）

模块图选项卡显示所选测试文件的模块依赖关系。

信息
这里提供的所有图片均以 Zammad 仓库为例。如果模块数量超过 50 个，模块图只显示前两层以减少视觉杂乱。你始终可以点击“显示完整图（Show Full Graph）”图标预览完整图。

警告
请注意，如果图过大，节点位置稳定可能需要一些时间。你始终可以通过点击“重置（Reset）”恢复入口模块图。要展开模块图，请右键点击或在按住 Shift 键的情况下点击感兴趣的节点。这会显示与该节点相关的所有节点。

默认情况下，Vitest 不显示来自 node_modules 的模块。通常这些模块会被外部化处理。你可以通过取消选中“隐藏 node_modules（Hide node_modules）”来启用显示。

模块信息（Module Info）

左键点击模块节点即可打开模块信息视图。

此视图分为两部分。上半部分显示完整的模块 ID 以及一些诊断信息。如果启用了 fsModuleCache，会显示“已缓存（cached）”或“未缓存（not cached）”徽章。右侧可以看到时间诊断：

• 自身时间（Self Time）：导入该模块所需的时间，不包括静态导入。
• 总时间（Total Time）：导入该模块所需的总时间，包括静态导入。注意，这不包括当前模块的转换（transform）时间。
• 转换（Transform）：转换该模块所需的时间。

如果通过点击导入项打开此视图，还会在起始位置看到一个“返回（Back）”按钮，点击可返回上一个模块。

下半部分取决于模块类型。如果模块是外部的（external），你只能看到该文件的源代码。无法进一步遍历模块图，也看不到导入静态导入所需的时间。

如果模块是内联的（inlined），你会看到另外三个窗口：

• Source：模块的原始源代码。
• Transformed：Vitest 使用 Vite 模块运行器执行的转换后代码。
• Source Map (v3)：Source map 映射信息。

“Source”窗口中的所有静态导入都会显示当前模块评估它们所需的总时间。如果该导入在模块图中已被评估，则会显示 0ms，因为此时它已被缓存。

如果模块加载时间超过危险阈值（默认：500ms），时间将以红色显示。如果超过警告阈值（默认：100ms），时间将以橙色显示。

你可以点击导入源跳转到该模块并进一步遍历图（例如下方显示的 ./support/assertions/index.ts）。

警告
请注意，仅类型导入（type-only imports）不会在运行时执行，因此不显示总持续时间，也无法打开。

如果其他插件在转换过程中注入了模块导入，这些导入将以灰色显示在模块起始位置（例如由 import.meta.glob 注入的模块）。它们也显示总时间，并允许进一步遍历。

提示
如果你正在基于 Vitest 开发自定义集成，可以使用 vitest.experimental_getSourceModuleDiagnostic 来获取此信息。

导入分解（Import Breakdown）

反馈
请通过 GitHub Discussion 对此功能留下反馈。

模块图选项卡还提供导入分解功能，列出加载耗时最长的模块（默认前 10 个），按总时间排序。

你可以点击模块查看模块信息。如果模块是外部的，它将显示黄色（与模块图中的颜色相同）。

分解列表展示模块的自身时间、总时间，以及相对于加载整个测试文件所需时间的百分比。

如果至少有一个文件的加载时间超过危险阈值（默认：500ms），“显示导入分解（Show Import Breakdown）”图标将变为红色；如果至少有一个文件超过警告阈值（默认：100ms），图标将变为橙色。

你可以使用 experimental.importDurations.limit 来控制显示的导入数量。