Skip to content

Vitest 5.1 发布了! ​

2026 年 11 月 2 日

Vitest 5.1 发布封面图

Vitest 下一个次版本已到来 ​

今天,我们很高兴地宣布 Vitest 5.1 发布!

快捷链接:

如果你还没有使用过 Vitest,建议先阅读快速入门和功能指南。

我们衷心感谢超过 840 位 Vitest Core 贡献者,以及帮助我们开发此版本的 Vitest 集成、工具和翻译的维护者与贡献者。欢迎你参与其中,帮助我们为整个生态改进 Vitest。详情请参阅贡献指南。

刚开始参与时,可以帮助分类处理 issue、审查 PR、根据开放的 issue 提交失败测试 PR,并在 Discussions 和 Vitest Land 的帮助论坛中帮助他人。如果你想和我们交流,欢迎加入 Discord 社区,并在 #contributing 频道打个招呼。

要获取 Vitest 生态和核心项目的最新消息,请关注我们的 Bluesky 或 Mastodon 账号。

要及时了解最新动态,请关注 VoidZero 博客并订阅邮件简报。

使用 --since-last-run 仅运行受影响的测试 ​

--changed 标志会将文件与 Git 参考提交进行比较。它需要 Git 仓库,而且更改一旦提交就不再属于“已更改”内容。新的实验性 --since-last-run 标志则会将文件与每个测试的上次运行情况进行比较:

sh
vitest run --since-last-run

首次使用此标志运行时,会运行所有测试,并记录每个测试加载过的文件,包括动态导入、模拟、设置文件和快照文件。之后的每次运行都会检查这些文件的修改时间,只运行自上次运行以来文件发生变化或已被删除的测试。上次运行失败的测试文件也会继续运行,直到通过。

每次运行都会更新记录,因此下一次运行只会选中期间编辑所影响的测试。此功能不依赖 Git,因此在全新的容器、临时工作树或非仓库目录中也能以相同方式工作。这很适合每次编辑后都会运行测试的 AI 编码代理:

AGENTS.md
md
- After a change, run `vitest run --since-last-run` to test only what the change affects.
- Before you finish, run `vitest run` once for the whole suite.

此标志基于 experimental.recordDependencies 和新的 mtime VCS 提供者实现。自定义 VCS 提供者现在也会收到一个 resolver,用于返回本次运行中测试文件依赖的所有文件。如何在 --changed 和 --since-last-run 之间选择,请参阅仅运行受影响的测试。

交互式快照审查 ​

监听模式下快照失败时,按 u 可以一次性更新全部快照。Vitest 5.1 新增了受 Insta 的 review 命令启发的交互式审查功能,让你在接受每个变更前先进行检查。按 i,Vitest 就会逐个显示失败的快照:

snapshot-review.ansi
Reviewing [1/3]:
Source: src/user-card.test.ts:7:25 (renders the full name)
Snapshot: renders the full name 1
────────────────────────────────────────────────────────────────────────────────
- Expected
+ Received
────────────┬───────────────────────────────────────────────────────────────────
    1     1 │  {
    2       │-   "name": "Ada",
          2 │+   "name": "Ada Lovelace",
    3     3 │    "role": "admin",
    4     4 │  }
────────────┴───────────────────────────────────────────────────────────────────

  a accept  keep the new snapshot
  r reject  retain the old snapshot

按 a 接受新快照,按 r 保留旧快照。查看完最后一个快照后,Vitest 会写入已接受的快照,并重新运行包含这些快照的测试文件。此功能支持内联快照、.snap 文件和文件快照,也支持浏览器模式中的 ARIA 快照。

Trace View 默认记录失败测试 ​

Trace View 在 Vitest 5.0 中以实验性功能推出,现在已稳定,并默认启用新的 'failure-only' 模式。在此模式下,Vitest 只会为失败的测试保留 trace。通过的测试会在浏览器中记录步骤,但不会生成 DOM 快照,也不会向服务器发送任何内容,因此此模式不会给通过的测试带来可测量的额外开销。

浏览器测试失败时,错误报告现在会在末尾附上导致失败的步骤:

错误报告
 FAIL src/sign-in.test.ts > signs in
Error: expect(element).toHaveTextContent()

Expected element to have text content:
  Welcome
Received:
  Sign in

 ❯ src/sign-in.test.ts:11:51
      9|   })
     10|   await page.getByRole('button', { name: 'Sign in' }).click()
     11|   await expect.element(page.getByRole('heading')).toHaveTextContent('Welcome')
       |                                                   ^
     12| })

Caused by: Error: Matcher did not succeed in time.

Trace:
  step               locator                                   start  duration  location
  fill form          -                                          +1ms      58ms  src/sign-in.test.ts:6:14
  ├── fill           getByLabel('Email')                        +2ms      31ms  src/sign-in.test.ts:7:40
  └── fill           getByLabel('Password')                    +34ms      24ms  src/sign-in.test.ts:8:43
  click              getByRole('button', { name: 'Sign in' })  +61ms      18ms  src/sign-in.test.ts:10:55
  toHaveTextContent  getByRole('heading')                      +80ms    1003ms  src/sign-in.test.ts:11:16

同一份 trace 还包含失败时的页面快照,可以在浏览器 UI、Vitest UI 和 HTML 报告器中查看。要记录每个测试,并为每个步骤保存快照,请将模式设为 'on':

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

export default defineConfig({
  test: {
    browser: {
      traceView: 'on', // 'failure-only' (default) | 'on' | 'off'
    },
  },
})

browser.traceView.enabled 已弃用,请改用 browser.traceView.mode。

trace 查看器也会在每个快照中捕获页面的无障碍树。查看器标题栏中的选择器可以在 DOM 和 Aria 视图之间切换。Aria 视图会以 ARIA 快照相同的格式显示 getByRole() 等定位器所匹配的角色和可访问名称。

Node 测试中的 Trace 时间线 ​

步骤时间线不只适用于浏览器模式。启用新的实验性 experimental.traceTimeline 选项后,Vitest 会记录每个测试中的 expect.poll、vi.waitFor 和 vi.waitUntil 步骤,并在测试失败时将其显示在错误信息下方。这样可以查看测试等待了什么以及每次等待花了多长时间,有助于排查等待服务器、队列或文件监听器时出现的不稳定测试。

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

export default defineConfig({
  test: {
    experimental: {
      traceTimeline: true,
    },
  },
})
错误报告
 FAIL src/search.test.ts > finds new user in search
AssertionError: expected [] to have a length of 1 but got +0

- Expected
+ Received

- 1
+ 0

 ❯ src/search.test.ts:8:50
      6|   await api.post('/users', { name: 'alice' })
      7|   await vi.waitUntil(() => db.users.findByName('alice'), { message: 'user saved' })
      8|   await expect.poll(() => search.query('alice')).toHaveLength(1)
       |                                                  ^
      9| })

Caused by: Error: Matcher did not succeed in time.

Trace:
  step                           start  duration  location
  vi.waitFor()                    +2ms     120ms  src/search.test.ts:5:12
  user saved (vi.waitUntil)     +171ms      42ms  src/search.test.ts:7:12
  expect.poll().toHaveLength()  +214ms    1001ms  src/search.test.ts:8:50

Vitest 只保留失败尝试的步骤,因此此选项几乎不会给通过的测试带来额外开销。

vi.waitFor 和 vi.waitUntil 现在也接受 message 选项,expect.poll 原本就支持此选项。Vitest 会将消息添加到错误信息开头,并用它作为时间线中的步骤名称,例如上方报告中的 user saved (vi.waitUntil):

ts
await vi.waitFor(() => server.ping(), { message: 'server started' })
// Error: server started: connect ECONNREFUSED

使用 --last-failed 重新运行失败项 ​

监听模式已经可以通过 f 键重新运行失败的测试。新的 --last-failed 标志可以在不同进程之间执行相同操作:它会从结果缓存中读取上次运行的失败信息,并且只运行这些测试。

sh
vitest run --last-failed

# combine with other filters
vitest run --last-failed -t login

Vitest 根据测试的完整名称进行选择,因此在文件中添加或移动其他测试不会改变选择结果。如果文件在测试之外失败,例如 beforeAll 钩子或收集期间失败,就会运行整个文件。自定义集成可以通过新的 TestSpecification.testNames 属性使用相同的过滤条件。

浏览器模式中的模块模拟更快 ​

在浏览器模式下模拟模块时,Vitest 之前会拦截页面的网络请求(通过 Playwright 的 page.route,或其他提供者使用的 Vite 插件),并提供模拟代码。页面中的每个请求都会产生拦截开销,测试文件导入的模块越多,开销就越大。

Vitest 5.1 改为通过导入映射提供模拟。测试文件调用 vi.mock 时,Vitest 会添加一条导入映射规则,将模块 URL 指向其模拟版本。浏览器会直接加载模拟模块,因此不会拦截请求,HTTP 缓存也能继续使用。

在一项公开基准测试中,每套测试包含 500 个测试文件、962 个模块和 1,883 个模拟(Chromium,9 个 worker,运行 3 次取中位数):

套件Vitest 5.0.3Vitest 5.1变化
无模拟31.7s26.6s−16%
有模拟56.4s27.2s−52%
混合44.0s27.1s−38%

新的 browser.importMapMocks 选项目前处于实验阶段。浏览器支持在同一文档中使用多个导入映射时会启用它(Chromium 133+、Safari 18.4+,以及使用 Playwright 提供者时的 Firefox 150+)。在其他浏览器中,以及禁用 isolate 时,Vitest 会像之前一样拦截请求。

导入映射无法更改页面已经导入的模块,因此如果模块在 vi.mock 注册它之前就已导入,Vitest 现在会报告错误,而不会悄悄使用原始模块。模拟工厂也只能提供原始模块声明的导出。如果这会导致测试失败,请将 browser.importMapMocks 设为 false,并告诉我们。

Pointer API ​

新的实验性 userEvent.pointer 方法可以执行一系列底层 pointer 操作。它使用 user-event 的 pointer 语法,因此可以分别按下、移动和释放 pointer,例如将元素拖到精确位置:

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

test('drags the card into the column', async () => {
  const card = page.getByRole('listitem', { name: 'Fix the login form' })
  const column = page.getByRole('list', { name: 'Done' })

  await userEvent.pointer([
    { target: card, keys: '[MouseLeft>]' },
    { target: column, coords: { x: 10, y: 10 }, keys: '[/MouseLeft]' },
  ])
})

为 node:timers 启用假计时器 ​

假计时器会替换全局的 setTimeout 等函数,但从 node:timers 或 node:timers/promises 导入这些函数的代码仍会使用真实计时器。启用新的 fakeNodeBuiltins 选项后,Vitest 也会模拟这些模块,包括命名导入和 require 调用:

ts
import { setTimeout as sleep } from 'node:timers/promises'
import { expect, test, vi } from 'vitest'

test('resolves after the delay', async () => {
  vi.useFakeTimers({ fakeNodeBuiltins: true })

  const resolved = vi.fn()
  sleep(1000).then(resolved)

  await vi.advanceTimersByTimeAsync(1000)
  expect(resolved).toHaveBeenCalled()
})

TIP

fakeNodeBuiltins 默认禁用。我们计划在下一个大版本中默认启用它。你可以现在就在配置中将 fakeTimers.fakeNodeBuiltins 设为 true,提前适配此变化。

vi.setSystemTime 现在也接受 Temporal.Instant 或 Temporal.ZonedDateTime。ZonedDateTime 会设置模拟时间,但不会改变环境的时区:

ts
vi.setSystemTime(Temporal.Instant.from('2026-11-02T09:00:00Z'))

在浏览器模式中,click 和 fill 等 locator 操作以及 expect.element 现在会在等待元素时推进假计时器,与 expect.poll 和 vi.waitFor 的行为相同。此前,如果元素只会在模拟的 setTimeout 后出现,操作就会超时。

每次尝试的结果 ​

配置 retry 或 repeats 后,测试可能会运行多次。此前,TestCase.result() 只会报告最终状态,并合并所有运行产生的错误。新的 TestCase.attempts() 方法会分别返回每次运行的状态、错误和时序,因此报告器可以找出仅在重试后才通过的测试:

flaky-reporter.ts
ts
import type { Reporter } from 'vitest/node'

export default {
  onTestCaseResult(testCase) {
    const attempts = testCase.attempts()

    if (testCase.result().state === 'passed' && attempts.length > 1) {
      console.warn(`${testCase.fullName} passed after ${attempts.length} attempts`)
    }
  },
} satisfies Reporter

默认报告器也会使用这些信息。测试在多次尝试中失败时,现在会打印一个包含各次尝试的标题,而不是每次尝试都重复打印相同标题:

 FAIL  basic.test.js > always fails (initial run, 1st retry, 2nd retry)
AssertionError: expected 1 to be 2 // Object.is equality

覆盖率改进 ​

HTML 覆盖率报告新增了符合 Vitest 风格的浅色和深色主题。报告会遵循操作系统的颜色偏好,主题选择器会记住你的选择。在 Vitest UI 中,报告会使用 UI 的主题。如需保留原始 Istanbul 风格,请在报告器选项中设置 theme: 'legacy':

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

export default defineConfig({
  test: {
    coverage: {
      reporter: [['html', { theme: 'legacy' }]], // 'light' | 'dark' | 'legacy'
    },
  },
})

istanbul 提供者现在快得多。@vitest/istanbuljs 包不再使用 Babel,而是通过 Rolldown 使用 Oxc 解析代码,并通过 magic-string 插入覆盖率计数器。这使插桩速度提升了 5 到 10 倍,内存占用也更低。例如,对 Vitest 仓库的 479 个源文件进行插桩,耗时从 3.7 秒降至 0.38 秒。插桩后的代码也不再包含输入源映射,发送给 worker 的代码量因此减少约 26%。

v8 提供者新增了 coverage.ignoreNode 选项,可以根据 AST 节点忽略代码。这适用于编译器或插件生成、无法添加忽略提示的代码,例如 React Compiler 为每个组件添加的缓存分支:

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

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      ignoreNode: (node, type) =>
        type === 'statement'
        && node.type === 'ExpressionStatement'
        && node.expression.type === 'CallExpression'
        && node.expression.callee.type === 'Identifier'
        && node.expression.callee.name === '__generatedHelper',
    },
  },
})

性能改进 ​

  • isolate: false 时复用 worker。 Worker 现在会缓存设置文件及其模拟项的解析结果,并且不再为每个测试文件请求一份已预热模块的新快照。在包含 800 个测试文件的基准测试中,解析缓存带来约 10% 的提升;当每个测试文件都导入较大的共享模块树时,预热模块改动带来的提升最高可达 18%。
  • toEqual 支持类型化数组。 Vitest 会在一次循环中比较类型化数组。两个 2 MiB 数组的 toEqual 比较耗时从约 1.5 秒降至 125 毫秒。
  • Firefox 中的 Trace View。 Vitest 现在只解析每个步骤中第一个可用的堆栈帧。在 'on' 模式下,包含 200 个 expect.element 调用的测试在 Firefox 中耗时从 5.7 秒降至 0.33 秒。
  • 高负载下的浏览器模式。 WebSocket 服务器现在会依次处理所有浏览器的消息,因此繁忙的浏览器不会再让其他浏览器的操作一直等到超时。

其他改动 ​

  • 浏览器模式的默认端口从 63315 改为 23315。Hyper-V、WSL2 或 Docker Desktop 运行时,Windows 可能会保留旧端口,导致 Vitest 无法启动。如果你的环境依赖旧端口,请设置 api.port。
  • api.port: 0 现在会让操作系统选择空闲端口。此功能需要 Vite 8.2.1 或更新版本。
  • 如果浏览器测试文件无法连接服务器,运行现在会报错,而不是无限等待。

完整变更列表请参阅 Vitest 5.1 更新日志。

致谢 ​

Vitest 5.1 凝聚了 Vitest 团队和贡献者投入的无数时间与心血。这一切离不开赞助 Vitest 的个人和公司。Vladimir 和 Hiroshi 在 VoidZero 全职开发 Vite 和 Vitest;Chromatic 为 Ari 推进 Vitest 开发提供了时间。Vitest 也通过 Cloudflare 基金赞助 Vitest 团队成员 Raul 的工作。感谢所有通过 GitHub Sponsors 和 Open Collective 支持我们的朋友。