vitest-docs

Vitest 5

此技能涵蓋 https://vitest.dev/guide/ 文件中記載的 Vitest 5.x 版本。它包含了與習慣用法不同的部分：令人意外的預設值、陷阱、已棄用的 API 以及官方文件推薦的模式。每個參考檔案中的敘述都會附上其來源頁面。

如何瀏覽

1. 閱讀下方的快速規則。它們涵蓋了最常見的錯誤。
2. 從結尾的表格中，開啟與任務相符的一個參考檔案。
3. 當程式碼使用 Jest API 或 Vitest 4 的行為時，請先閱讀 references/migration.md。

快速入門

// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { restoreMocks: true } })

// math.test.ts
import { expect, test } from 'vitest'

test.for([[1, 1, 2], [1, 2, 3]])('add(%i, %i) -> %i', ([a, b, expected]) => {
  expect(a + b).toBe(expected)
})

• 需要 Vite >= 6.4.0 和 Node.js >= 22.12.0。vite 是同等依賴。 https://vitest.dev/guide/migration
• 在指令稿、CI 和代理程式中執行 vitest run。單純的 vitest 會在終端機中啟動監看模式。 https://vitest.dev/guide/learn/writing-tests-with-ai
• 將 .vitest/ 加入 .gitignore。 https://vitest.dev/guide

快速規則

撰寫測試

• globals 是關閉的：從 vitest 匯入 test、expect、vi。 https://vitest.dev/config/globals
• 使用 test.for 而非 test.each 來參數化測試。 https://vitest.dev/guide/learn/writing-tests
• 透過 fixture 共享設定：test.extend('name', fn)，並務必解構它們。 https://vitest.dev/guide/test-context
• 從 beforeEach 回傳清理函式，而不是撰寫對應的 afterEach。 https://vitest.dev/api/hooks
• 不使用 done 回呼。請使用非同步測試。 https://vitest.dev/api/test
• 測試在執行時不會進行型別檢查。請執行 tsc 或 vitest --typecheck.enabled。 https://vitest.dev/guide/learn/writing-tests ， https://vitest.dev/guide/cli
• 在並行測試中，從 context 使用 expect：async ({ expect }) => {}。 https://vitest.dev/api/test

斷言

• 對每個 .resolves、.rejects、expect.poll 和 toMatchFileSnapshot 使用 await，否則測試會失敗。 https://vitest.dev/guide/migration
• 使用 expect.poll 或 vi.waitFor 輪詢，絕對不要用 setTimeout 睡眠。 https://vitest.dev/guide/recipes/wait-for
• 使用 expect.assert(x) 縮小型別。toBeDefined() 不會縮小型別。 https://vitest.dev/guide/recipes/type-narrowing
• 快照不會在 CI 中寫入。請在閱讀 diff 後使用 vitest -u 更新。 https://vitest.dev/guide/snapshot

模擬

• 優先使用 vi.mock(import('./x.js')) 而非字串：路徑會跟著檔案移動，且工廠函式會進行型別檢查。 https://vitest.dev/api/vi
• 將 vi.mock 和 vi.hoisted 保持在模組頂層。在其他地方使用會拋出錯誤。 https://vitest.dev/guide/migration
• 工廠函式需回傳所有匯出，包括 default。 https://vitest.dev/guide/migration/jest
• clearMocks 預設為開啟。加入 restoreMocks: true 以在每次測試後還原間諜。 https://vitest.dev/config/clearmocks ， https://vitest.dev/guide/learn/mock-functions
• 依參數指定回傳值：vi.when(fn).calledWith(1).thenReturn(x)。 https://vitest.dev/guide/recipes/conditional-mocking
• 使用 vi.fn(class { ... }) 模擬類別。 https://vitest.dev/guide/mocking/classes
• 在其自身檔案內部被呼叫的函式無法被模擬。 https://vitest.dev/guide/mocking/modules

設定與執行

• vitest.config.* 會忽略 vite.config.*，除非你使用 mergeConfig 合併它。 https://vitest.dev/config
• 設定 include、exclude 或 reporters 會取代預設值。請展開 configDefaults。 https://vitest.dev/config/include
• 預設環境為 node。請自行安裝 jsdom 或 happy-dom。 https://vitest.dev/guide/environment
• 預設 pool 為 forks。對於原生模組和 process.chdir，請保留此設定。 https://vitest.dev/config/pool
• .only 在 CI 中會導致執行失敗（請參閱 allowOnly）。 https://vitest.dev/api/test
• -t 比對由 ' > ' 連接的完整名稱。 https://vitest.dev/guide/filtering

舊模式

舊模式	目前模式
jest.fn, jest.mock, jest.requireActual	vi.fn, vi.mock, await vi.importActual
test.each 行展開為引數	test.for 搭配解構的行和 context
test.sequential, describe.sequential	{ concurrent: false }
import { bench } from 'vitest'	test() 內部的 bench fixture
test.scoped	test.override
workspace	test.projects
toMatchTypeOf	toExtend
在 test 或 describe 內部的 vi.mock	頂層 vi.mock，或 vi.doMock
未 await 的 .resolves 自動 await	await expect(p).resolves
toHaveTextContent(/regex/)	toMatchTextContent(/regex/)
vitest --reporter=json 輸出至 stdout	.vitest/json/output.json，或 stdout: true
vitest/environments, vitest/coverage	vitest/runtime, vitest/node

詳細資訊和完整清單：references/migration.md。

參考檔案

檔案	適用於
references/writing-tests.md	測試選項、test.for、並行、fixture、鉤子、設定檔案、全域設定、標籤、基準測試、原始碼內測試
references/assertions-and-snapshots.md	expect 陷阱、非同步斷言、輪詢、型別縮小、綱目比對、自訂匹配器、快照、型別測試
references/mocking.md	模擬清理、vi.fn、vi.spyOn、vi.mock、類別模擬、vi.when、假計時器、全域變數、環境變數、MSW、memfs
references/config-and-cli.md	設定解析、include、globals、環境、pool、專案、CLI 篩選器、監看、報告器、分片
references/coverage.md	v8 和 istanbul、coverage.include、報告、閾值、忽略提示
references/debugging-and-performance.md	除錯器設定、常見錯誤、依賴內聯、CommonJS、效能分析、加速、停用隔離
references/browser-mode.md	瀏覽器模式設定、實例、Playwright 提供者、定位器、expect.element、userEvent、元件測試、視覺與 ARIA 快照
references/migration.md	Vitest 4 到 5 的變更與移除、Jest 和 Mocha 對應表、升級衛生習慣

已爬取頁面：SOURCES.md。