遷移指南

從 Jest 遷移

Vitest 的設計與 Jest 的 API 相容，目的是盡可能簡化從 Jest 的遷移過程。儘管如此，您可能仍然會遇到以下差異：

預設的全域變數

Jest 預設啟用其 globals API。Vitest 則不然。您可以透過 globals 配置設定 啟用全域變數，或者更新您的程式碼以使用從 vitest 模組匯入的內容。

如果您決定保持停用全域變數，請注意，像 testing-library 這樣的常用函式庫將不會自動執行 DOM 清理。

模組模擬 (Module Mocks)

在 Jest 中模擬一個模組時，工廠函式 (factory argument) 的回傳值會作為預設匯出 (default export)。在 Vitest 中，工廠函式必須回傳一個物件，其中明確定義了每個匯出。例如，以下 jest.mock 必須更新如下：

- jest.mock('./some-path', () => 'hello')
+ vi.mock('./some-path', () => ({
+   default: 'hello',
+ })

更多詳細資訊請參考 vi.mock api 章節。

自動模擬行為 (Auto-Mocking Behavior)

與 Jest 不同，除非呼叫 vi.mock()，否則 <root>/__mocks__ 中的模擬模組不會載入。如果您需要在每個測試中都模擬這些模組，就像在 Jest 中一樣，您可以在 setupFiles 中模擬這些模組。

匯入模擬套件的原始版本

如果您僅對套件進行部分模擬，您可能之前使用過 Jest 的 requireActual 函數。在 Vitest 中，您應該將這些呼叫替換為 vi.importActual。

- const { cloneDeep } = jest.requireActual('lodash/cloneDeep')
+ const { cloneDeep } = await vi.importActual('lodash/cloneDeep')

環境變數設定 (Envs)

與 Jest 一樣，如果之前未設定，Vitest 會將 NODE_ENV 設定為 test。Vitest 還有一個對應於 JEST_WORKER_ID 的變數，稱為 VITEST_POOL_ID（始終小於或等於 maxThreads）。如果您依賴此變數，請不要忘記重新命名它。Vitest 還公開了 VITEST_WORKER_ID，它是正在執行的 worker 的唯一 ID - 這個數字不受 maxThreads 的影響，並且會隨著每個建立的 worker 而增加。

如果您想修改環境變數，在 Jest 中可以使用 replaceProperty API，而在 Vitest 中，則可以使用 vi.stubEnv 執行相同的操作。

Done 回調函式

從 Vitest v0.10.0 開始，宣告測試時使用的回調函式寫法已不再建議使用。您可以將其重寫為使用 async/await 函數，或使用 Promise 來模擬回呼樣式。

- it('should work', (done) => {
+ it('should work', () => new Promise(done => {
    // ...
    done()
- })
+ }))

鉤子

beforeAll/beforeEach hooks 在 Vitest 中可以回傳 teardown 函數。因此，如果這些 hooks 回傳的不是 undefined 或 null，您可能需要重寫您的 hooks 宣告：

- beforeEach(() => setActivePinia(createTestingPinia()))
+ beforeEach(() => { setActivePinia(createTestingPinia()) })

型別 (Types)

Vitest 不會在 Vi 命名空間上公開許多型別，它主要用於與 matchers 相容。因此，您可能需要直接從 vitest 匯入型別，而不是依賴 Vi 命名空間：

- let fn: jest.Mock<string, [string]>
+ import type { Mock } from 'vitest'
+ let fn: Mock<[string], string>

此外，正如您在 diff 中看到的，Vitest 使用 Args 型別作為第一個參數，而非 Returns 型別。

定時器 (Timers)

Vitest 不支援 Jest 的舊版計時器。

Vue 快照 (Vue Snapshots)

這不是 Jest 特有的功能，但如果您之前使用 Jest 與 vue-cli 的預設配置，您將需要安裝 jest-serializer-vue 套件，並在 setupFiles 中使用它：

vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    setupFiles: ['./tests/unit/setup.js'],
  },
});

tests/unit/setup.js

import vueSnapshotSerializer from 'jest-serializer-vue';

expect.addSnapshotSerializer(vueSnapshotSerializer);

否則，您的畫面快照將會包含許多逸出的 " 字元。