メインコンテンツへスキップ
バージョン: 次へ

v29 から v30 への移行

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。 エラーを見つけましたか？ 問題を報告 →

Jest を v29 から v30 にアップグレードしますか？このガイドでは設定とテストのリファクタリングを支援します。

情報

完全な変更リストは変更履歴をご覧ください。

メモ

より古いバージョンからアップグレードしますか？v28 から v29 への移行ガイドはこちらで確認できます。

互換性​

  • Jest 30 は Node 14, 16, 19, 21 のサポートを終了しました。現在の最低サポート Node バージョンは 18.x です。アップグレード前に環境が互換性のある Node リリースを使用していることを確認してください。

  • TypeScript の最低バージョン要件が 5.4 になりました。Jest（または関連パッケージ）の型定義を使用している場合は TypeScript を更新してください。

  • jest-environment-jsdom パッケージは JSDOM v26 を使用するようになりました。この更新により DOM 環境の動作が変わる可能性があります。DOM の動作差異や新規警告が発生した場合は、JSDOM のリリースノート v21–26 を参照してください。

Jest Expect とマッチャー​

エイリアスマッチャー関数の削除​

すべての_エイリアス_マッチャー名が削除され、主要な名前が優先されます。非推奨の古いマッチャー名を使用している場合はテストを更新する必要があります：

  • 削除されたエイリアスと代替マッチャー：
    • expect(fn).toBeCalled() → expect(fn).toHaveBeenCalled()
    • expect(fn).toBeCalledTimes(n) → expect(fn).toHaveBeenCalledTimes(n)
    • expect(fn).toBeCalledWith(arg) → expect(fn).toHaveBeenCalledWith(arg)
    • expect(fn).lastCalledWith(arg) → expect(fn).toHaveBeenLastCalledWith(arg)
    • expect(fn).nthCalledWith(n, arg) → expect(fn).toHaveBeenNthCalledWith(n, arg)
    • expect(fn).toReturn() → expect(fn).toHaveReturned()
    • expect(fn).toReturnTimes(n) → expect(fn).toHaveReturnedTimes(n)
    • expect(fn).toReturnWith(val) → expect(fn).toHaveReturnedWith(val)
    • expect(fn).lastReturnedWith(val) → expect(fn).toHaveLastReturnedWith(val)
    • expect(fn).nthReturnedWith(n, val) → expect(fn).toHaveNthReturnedWith(n, val)
    • expect(func).toThrowError(message) → expect(func).toThrow(message)
情報

これらのエイリアスメソッドは Jest 26 以降非推奨となり、Jest 30 で完全削除されました。コードベース全体で検索・置換を行い、正規のマッチャー名に更新してください。機能は同一です（メソッド名のみ変更されています）。（ESLint と eslint-plugin-jest を使用している場合、no-alias-methods ルールで置換を自動化できます）

非列挙プロパティの扱い​

非列挙オブジェクトプロパティはデフォルトでオブジェクトマッチャーから除外されるようになりました。expect.objectContaining や等価性チェックに影響する可能性があります。

CalledWith の型推論改善​

TypeScript ユーザー向け：CalledWith 系マッチャー（例：toHaveBeenCalledWith）の型が関数パラメーター型を推論するよう改善されました。多くの場合、型不一致をより正確に検出します。これはコンパイル時の破壊的変更です。

関数の呼び出しを、実際の関数パラメータの型と一致しない引数でアサートしていた場合、TypeScriptがこれらのテストでエラーを発生させるようになりました。たとえば、関数が数値を受け取る型指定されており、expect(fn).toHaveBeenCalledWith("string")と記述していた場合、TypeScript 5 + Jest 30の型システムがこれを検出します。ただし、マッチャーの実行時の動作は変更されていません。

新たなTypeScriptエラーを修正するには、テスト引数が関数の期待型と一致することを確認してください（意図的に異なる型で呼び出す場合は型キャストを使用してください）。

この変更は実行時に影響を与えませんが、これまで検出されなかった型エラーをテストコード内で発見できるようになり、テストの型安全性が向上します。

設定の更新​

.mtsおよび.ctsファイル拡張子のサポート​

Jest 30ではESMおよびTypeScriptモジュールファイル拡張子のサポートが拡張されました：

  • デフォルトのmoduleFileExtensionsに、通常の拡張子に加えて.mtsおよび.cts（TypeScriptのESMおよびCommonJSモジュール）が含まれるようになりました。

  • デフォルトのtestMatchおよびtestRegexパターンが更新され、.mjs、.cjs、.mts、.ctsファイルをテストファイルとして認識するようになりました。

情報

これらの拡張子を持つファイルがモジュールやテストとして扱われることを意図していない場合、設定の調整が必要になる可能性があります。逆に、これらの拡張子を持つテストファイルがある場合、Jestはデフォルトでそれらを検出します（以前にそれらを含めるために必要だったカスタム設定は削除可能です）。

--testPathPatternが--testPathPatternsに名称変更​

パスでテストをフィルタリングする場合、CLIフラグが変更されていることに注意してください：--testPathPatternフラグは--testPathPatternsになりました。複数のパターンを渡すには、スペースで区切るかフラグを繰り返し使用します。例：

# Old (Jest 29)
jest --testPathPattern="unit/.*"

# New (Jest 30)
jest --testPathPatterns "unit/.*" "integration/.*"

内部的には、JestはこれらのパターンをTestPathPatternsオブジェクトに統合します。プログラムからJestのウォッチモードをtestPathPatternで呼び出していた場合、代わりにTestPathPatternsインスタンスを構築する必要があります。

--initコマンドの削除​

インタラクティブな設定初期化コマンドjest --initは削除されました。この非推奨コマンドはJest設定ファイルのスキャフォールディングに使用されていました。設定ファイルを作成する必要がある場合は、以下を実行できます：

npm init jest@latest
# Or for Yarn
yarn create jest
# Or for pnpm
pnpm create jest

その他のCLI変更点​

  • Jestは引数を必要とするCLIフラグの検証を強化し、引数が提供されていることを確認します。たとえば--maxWorkersや--selectProjectsを使用する場合、値を含める必要があります（例：--maxWorkers=50%）。以前はJestが値なしでフラグを許可していましたが（デフォルトにフォールバック）、現在は値がない場合にエラーがスローされます。Jestフラグを渡すスクリプトやnpmコマンドに必要な引数が含まれていることを確認してください。

  • テストファイルをフィルタリングするために--filterオプションを使用する場合（フィルタ実装へのパスを提供する高度なユースケース）、期待されるインターフェースが変更されました。フィルター関数はドキュメント記載の形式に一致する{filtered: Array<string>}形式のオブジェクトを返す必要があります。以前のバージョンでは異なる戻り形式が許容されていました（例：配列を直接返す）。カスタムテストフィルター関数を更新し、ドキュメント通りfilteredプロパティを持つオブジェクトを返すようにしてください。

テストランナーの動作変更​

テスト内の未処理Promise拒否​

Jestは、拒否されたPromiseが後でキャッチされる場合の処理を修正し、誤ったテスト失敗を回避します。Jest 29では、非同期に（テストティック後に）処理されたPromise拒否が、それでもテストを誤って失敗させる可能性がありました。Jest 30では、テストを失敗させる前にPromise拒否が未処理のまま残っていることを確認するため、追加のイベントループターンを待機します。

情報

未処理のプロミス拒否による誤検知が減少します。非同期で処理済みの拒否が原因で以前失敗していたテストは、現在パスするはずです。ただし、この変更によりテスト終了がわずかに遅延する可能性があり、特に意図的にプロミスを拒否するテストで顕著です。パフォーマンスへの影響を軽減するため、新しい設定フラグwaitForUnhandledRejectionsが導入されました。このフラグを無効にすると（待機しない）以前の動作を復元できますが、基本的には変更不要です。デフォルト設定では誤検知を防止する正確性が優先されており、大多数のユーザーはこの設定を変更する必要はありません。

カスタムテストシーケンサー​

カスタムテストシーケンサー（JestのTestSequencerを継承したクラス）を使用している場合、Jest 30向けに更新が必要です。Jestはテストシーケンサーに追加のコンテキストを渡すようになりました。具体的にはTestSequencer APIが拡張され、globalConfigとcontextsがシーケンサーで利用可能になりました。

ランタイムでの必須globalConfig​

JestのプログラムAPIを使用している場合：Runtimeの構築にはglobalConfigパラメータが必須になりました。jest.runCLIや類似のヘルパーを使用する場合は、更新されたAPIに従ってすべての必須オプションを渡してください（通常のjest CLIやnpm testの使用には影響ありません）。

スナップショットと出力変更​

破損ドキュメントリンクの更新​

非推奨のgoo.gl URLがスナップショットテストから削除されました。既存のスナップショット内のgoo.glリンクは完全な非短縮URLに置換されます。

スナップショット内のエラー原因​

スナップショットのエラーシリアライゼーションが変更されました。Jest 30のスナップショットシリアライザーは、Errorに**cause**プロパティが存在する場合、エラー出力時にこれを含めるようになりました。

Reactの空文字列レンダリング​

React固有のスナップショットシリアライザーは、出力で空文字列の子要素（""）を表示しなくなりました。Jest 29ではReact要素内の空文字列の子要素がスナップショット出力に""と表示されていましたが、Jest 30では省略されます（コンテンツなしとして扱われます）。

pretty-formatでのオブジェクト出力改善​

ArrayBufferとDataViewが内部フィールドを持つオブジェクトとしてではなく、人間可読形式で出力されるようになりました。

JestモックAPIの変更​

jest.genMockFromModuleの削除​

非推奨のjest.genMockFromModule(moduleName)が削除されました。以前からjest.createMockFromModule(moduleName)への移行が推奨されていました。genMockFromModuleを使用している場合はcreateMockFromModuleに切り替えてください（機能は同じです）。例：

旧コード（Jest 29）:

const mockFs = jest.genMockFromModule('fs');

新コード（Jest 30）:

const mockFs = jest.createMockFromModule('fs');

削除されたモック関数タイプ​

情報

これらの型変更はJest APIを明示的にインポートする場合のみ適用されます：

import {expect, jest, test} from '@jest/globals';

モック関数に関連する一部のTypeScript型が公開APIから削除されました。

  • MockFunctionMetadata

  • MockFunctionMetadataType

  • SpyInstance

jest.SpyInstance（例：jest.spyOnの返り値の注釈に使用）を使用していた場合は、jest.Spiedを使用するように更新してください。

jest.mock は大文字小文字を区別するモジュールパスでのみ動作する​

jest.mock() は今後、大文字小文字を区別するモジュールパスでのみ動作します。ほとんどのユーザーはOSのファイル命名規則に従っているため、影響は限定的です。将来同様の障害を避けるため、正しく命名されたモジュールパスを使用することを推奨します。

旧コード（Jest 29）:

jest.mock('./path/to/FILENAME.js'); // This works EVEN when you only have `filename.js`

新コード（Jest 30）:

jest.mock('./path/to/filename.js'); // This strictly works when you ONLY have `filename.js`

モジュール＆ランタイム変更​

ESMモジュールサポートと内部再構成​

Jestはパッケージのバンドル方法とエクスポート方法について重要な内部変更を導入しました：

  • Jestの内部モジュールは起動時間を短縮するため単一ファイルにバンドルされました。これによりJestインストール時のファイル読み込み数が大幅に減少しパフォーマンスが向上します。ただし副作用として、Jestパッケージへの非公式な深いインポートは動作しなくなる可能性があります。例：require('jest-runner/build/testWorker')（非公開API）のようなパスは存在しなくなります。解決策： Jestの公開APIまたは公式ドキュメント記載のインターフェースのみを使用してください。公開APIに含めるべき内部モジュールを利用している場合は、Pull Requestで公開化を提案してください。

  • JestパッケージにESMラッパーが追加されました。これはESM環境でJestを実行可能にする継続的な取り組みの一環です。公式Jestパッケージは全てpackage.jsonの"exports"フィールドを通じて適切にエクスポートされます。多くのユーザーには直接的な影響はなく、これまで通りJestを使用できます。ただしツールやプラグインを開発している場合は、Node.jsのモジュール解決を利用するパッケージ名によるインポートを確実に行ってください。

これらの変更はJestの内部実装に依存するケースでは破壊的変更となりますが、Jest CLIや設定を通常通り使用する場合には影響しません。アップグレード後は通常通りテストを実行してください。Jest自身のモジュールに関連する解決エラーが発生した場合、サポートされていないインポートを削除または更新する必要があります。

グロブパターンマッチングの変更​

ファイルパターンマッチング用の依存ライブラリ(glob)がv10にアップグレードされました。Glob v10では構文や挙動に微妙な差異が生じる可能性があります。

注目すべき変更点として、glob@10はブレース展開や拡張グロブの扱いが異なり、特定のパターンに対してより厳密になります。カスタムのtestMatchパターンやmoduleNameMapperパターンなど、グロブベースの設定を使用している場合、ほとんどのケースでは引き続き動作します。ただし以前と異なるファイルマッチングが発生した場合は、新しいグロブエンジン向けにパターンを調整する必要があるかもしれません。

まとめ​

Jest 30へのアップグレードでは、まず環境が新しいNode.jsとTypeScriptの要件を満たしていることを確認してください。リネームおよび削除されたオプション（特にtestPathPatternsと--initフラグの削除）に対応するためJest設定ファイルとCLI使用法を更新します。その後テストスイートを実行し、失敗に対処してください：

  • 削除されたエイリアスマッチャーを使用しているテストは公式マッチャー名で置換

  • フォーマット変更（エラー原因表示、空文字列処理など）で失敗したスナップショットを更新

  • TypeScriptコンパイラエラーに注意（genMockFromModuleなどの非推奨API使用箇所や型制約が厳格化されたテストの修正が必要）

テストを楽しみましょう！