マイグレーションガイド

Vitest 0.34.6 から 1.0 への移行

最低動作環境

Vitest 1.0 は Vite 5.0 および Node.js 18 以上を必要とします。

すべての @vitest/* サブパッケージは Vitest バージョン 1.0 が必要です。

スナップショットの更新 #3961

スナップショット内の引用符のエスケープが不要になり、1 行の文字列の場合でも、すべてのスナップショットがバッククォート (`) を使用するようになります。

引用符がエスケープされなくなりました:

diff

expect({ foo: 'bar' }).toMatchInlineSnapshot(`
  Object {
-    \\"foo\\": \\"bar\\",
+    "foo": "bar",
  }
`)

1 行のスナップショットで、シングルクォートの代わりに "`" 引用符を使用するようになりました:

diff

- expect('some string').toMatchInlineSnapshot('"some string"')
+ expect('some string').toMatchInlineSnapshot(`"some string"`)

@vitest/snapshot パッケージにも変更がありました。直接使用していない場合は、変更する必要はありません。

equalityCheck メソッドをオーバーライドするためだけに SnapshotClient を拡張する必要はなくなりました。インスタンスを作成する際に isEqual として渡すだけで済みます。
client.setTest は client.startCurrentRun に名前が変更されました。
client.resetCurrent は client.finishCurrentRun に名前が変更されました。

プールの標準化 #4172

ランナーの設定を簡素化するために、多くの設定オプションを削除しました。--threads またはその他の関連フラグを使用している場合は、移行例をご覧ください。

--threads は --pool=threads になりました。
--no-threads は --pool=forks になりました。
--single-thread は --poolOptions.threads.singleThread になりました。
--experimental-vm-threads は --pool=vmThreads になりました。
--experimental-vm-worker-memory-limit は --poolOptions.vmThreads.memoryLimit になりました。
--isolate は --poolOptions.<pool-name>.isolate および browser.isolate になりました。
test.maxThreads は test.poolOptions.<pool-name>.maxThreads になりました。
test.minThreads は test.poolOptions.<pool-name>.minThreads になりました。
test.useAtomics は test.poolOptions.<pool-name>.useAtomics になりました。
test.poolMatchGlobs.child_process は test.poolMatchGlobs.forks になりました。
test.poolMatchGlobs.experimentalVmThreads は test.poolMatchGlobs.vmThreads になりました。

diff

{
  scripts: {
-    "test": "vitest --no-threads"
     // For identical behaviour:
+    "test": "vitest --pool forks --poolOptions.forks.singleFork"
     // Or multi parallel forks:
+    "test": "vitest --pool forks"

  }
}

diff

{
  scripts: {
-    "test": "vitest --experimental-vm-threads"
+    "test": "vitest --pool vmThreads"
  }
}

diff

{
  scripts: {
-    "test": "vitest --isolate false"
+    "test": "vitest --poolOptions.threads.isolate false"
  }
}

diff

{
  scripts: {
-    "test": "vitest --no-threads --isolate false"
+    "test": "vitest --pool forks --poolOptions.forks.isolate false"
  }
}

Coverage の変更 #4265, #4442

オプション coverage.all がデフォルトで有効になりました。これは、coverage.include パターンに一致するすべてのプロジェクトファイルが、実行されなくても処理されることを意味します。

Coverage のしきい値 API の構造が変更され、グロブパターンを使用して特定のファイルのしきい値を指定できるようになりました。

diff

export default defineConfig({
  test: {
    coverage: {
-      perFile: true,
-      thresholdAutoUpdate: true,
-      100: true,
-      lines: 100,
-      functions: 100,
-      branches: 100,
-      statements: 100,
+      thresholds: {
+        perFile: true,
+        autoUpdate: true,
+        100: true,
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      }
    }
  }
})

Mock の型 #4400

Jest スタイルの "Mock" という命名規則に合わせて、いくつかの型が削除されました。

diff

- import { EnhancedSpy, SpyInstance } from 'vitest'
+ import { MockInstance } from 'vitest'

WARNING

SpyInstance は MockInstance に置き換えられ、非推奨となりました。次のメジャーリリースで削除されます。

タイマーのモック #3925

vi.useFakeTimers() は、process.nextTick を自動的にモックしなくなりました。vi.useFakeTimers({ toFake: ['nextTick'] }) を使用して明示的に指定することで、process.nextTick をモックできます。

ただし、--pool=forks を使用している場合、process.nextTick をモックすることはできません。process.nextTick のモックが必要な場合は、別の --pool オプションを使用してください。

Jest からの移行

Vitest は、Jest と互換性のある API で設計されており、Jest からの移行をできるだけ簡単にするように設計されています。しかし、移行の際には、以下の違いに遭遇する可能性があります。

デフォルトでのグローバル変数の使用

Jest では、グローバル APIがデフォルトで有効になっていますが、Vitest ではそうではありません。globals 構成設定を使用してグローバル変数を有効にするか、vitest モジュールからインポートを使用するようにコードを更新できます。

グローバル変数を無効にした場合、testing-library などの一般的なライブラリは、自動的に DOM cleanup を実行しないことに注意してください。

モジュールモック

Jest でモジュールをモックする場合、ファクトリ関数の戻り値はデフォルトのエクスポートになります。Vitest では、ファクトリ関数は、各エクスポートが明示的に定義されたオブジェクトを返す必要があります。たとえば、次の jest.mock は次のように更新する必要があります。

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

詳細については、vi.mock API のセクションを参照してください。

自動モックの動作

Jest とは異なり、<root>/__mocks__ ディレクトリ内のモックされたモジュールは、vi.mock() が呼び出されない限りロードされません。Jest のように、すべてのテストでモックする必要がある場合は、setupFiles 内でモックできます。

モック化されたパッケージのオリジナルをインポートする

パッケージを部分的にのみモックしている場合は、以前に Jest の関数 requireActual を使用していた可能性があります。Vitest では、これらの呼び出しを vi.importActual に置き換える必要があります。

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

外部ライブラリへのモックの拡張

モジュールをモックし、このモックを同じモジュールを使用する他の外部ライブラリに拡張したい場合（Jest がデフォルトで行うように）、モックするサードパーティライブラリを明示的に指定し、外部ライブラリがserver.deps.inlineの設定によってソースコードの一部として扱われるようにする必要があります。

server.deps.inline: ["lib-name"]

モックされた Promise の戻り値へのアクセス

Jest と Vitest のどちらも、すべてのモック呼び出しの結果はmock.results配列に格納され、各呼び出しの戻り値はvalueプロパティに格納されます。ただし、Promise をモックまたはスパイする場合 (例: mockResolvedValue を使用)、Jest では value プロパティは Promise になりますが、Vitest では、Promise が解決されると解決された値になります。

await expect(spy.mock.results[0].value).resolves.toBe(123); 
expect(spy.mock.results[0].value).toBe(123);

環境変数

Jest と同様に、Vitest は NODE_ENV が以前に設定されていない場合、test に設定します。Vitest には、JEST_WORKER_ID に対応する VITEST_POOL_ID（常に maxThreads 以下）も用意されています。これに依存している場合は、名前を変更することを忘れないでください。Vitest は、実行中のワーカーに割り当てられる一意の ID である VITEST_WORKER_ID も公開します。この数値は maxThreads の影響を受けず、作成されたワーカーごとに増加します。

プロパティの置換

オブジェクトのプロパティを置き換える場合、Jest ではreplaceProperty APIを使用しますが、Vitest ではvi.stubEnvまたはvi.spyOnを使用して同様のことができます。

Done コールバック

Vitest v0.10.0 以降、テストを定義する際のコールバック形式は非推奨となりました。async/await 関数を使用するか、Promise を使用してコールバック形式を模倣するように書き換えることができます。

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

フック

beforeAll/beforeEach フックは、Vitest でティアダウン関数を返す場合があります。そのため、undefined または null 以外の値を返す場合は、フックの定義を書き換える必要がある場合があります。

beforeEach(() => setActivePinia(createTestingPinia())); 
beforeEach(() => {
  setActivePinia(createTestingPinia());
});

Jest では、フックは順番に（1 つずつ）呼び出されます。デフォルトでは、Vitest はフックを並行して実行します。Jest の動作を使用するには、sequence.hooks オプションを更新します。

export default defineConfig({
  test: {
    sequence: {
      hooks: 'list', 
    }, 
  },
});

型

Vitest には jest 名前空間に相当するものが存在しないため、型定義を vitest から直接インポートする必要があります。

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

また、Vitest には、差分からわかるように、Returns の代わりに最初の引数として Args 型があります。

タイマー

Vitest は Jest の旧式タイマーをサポートしていません。

タイムアウト

jest.setTimeout を使用した場合は、vi.setConfig に移行する必要があります。

jest.setTimeout(5_000); 
vi.setConfig({ testTimeout: 5_000 });

Vue スナップショット

これは Jest 固有の機能ではありませんが、以前に vue-cli のプリセットで Jest を使用していた場合は、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);

そうしないと、スナップショット内の"文字が多数エスケープされて表示されます。

マイグレーションガイド ​

Vitest 0.34.6 から 1.0 への移行 ​

最低動作環境 ​

スナップショットの更新 #3961 ​

プールの標準化 #4172 ​

Coverage の変更 #4265, #4442 ​

Mock の型 #4400 ​

タイマーのモック #3925 ​

Jest からの移行 ​

デフォルトでのグローバル変数の使用 ​

モジュールモック ​

自動モックの動作 ​

モック化されたパッケージのオリジナルをインポートする ​

外部ライブラリへのモックの拡張 ​

モックされた Promise の戻り値へのアクセス ​

環境変数 ​

プロパティの置換 ​

Done コールバック ​

フック ​

型 ​

タイマー ​

タイムアウト ​

Vue スナップショット ​

マイグレーションガイド

Vitest 0.34.6 から 1.0 への移行

最低動作環境

スナップショットの更新 #3961

プールの標準化 #4172

Coverage の変更 #4265, #4442

Mock の型 #4400

タイマーのモック #3925

Jest からの移行

デフォルトでのグローバル変数の使用

モジュールモック

自動モックの動作

モック化されたパッケージのオリジナルをインポートする

外部ライブラリへのモックの拡張

モックされた Promise の戻り値へのアクセス

環境変数

プロパティの置換

Done コールバック

フック

型

タイマー

タイムアウト

Vue スナップショット