migrate-to-rstest

Rstest への移行

目標

動作の変更を最小限に抑えながら、Jest、Vitest、または Playwright Test の実行可能な最小スコープを移行します。インストール済みの Rstest のバージョンに対応するドキュメントと型を使用し、最新のオンラインドキュメントは、機能の適用可否を確認してから使用してください。

ワークフロー

1. references/detect-test-framework.md を使って、テストランナー、環境、Rstack との統合、および実行可能な最小スコープを検出します。
2. Rstest、カバレッジ、アダプター、またはプラグインの API を選ぶ前に、references/dependency-install-gate.md を実行します。
3. 編集する前に、正確なコマンド、Node とテストランナーのバージョン、環境、ファイル／テスト／スキップ／スナップショット、および失敗を記録します。移行前のテストマニフェストを取得し、移行中は references/discovery-parity.md に従ってください。
4. Jest の場合は references/jest-migration-deltas.md を、Vitest の場合は references/vitest-migration-deltas.md を、グローバル API の場合は references/global-api-migration.md も読みます。Playwright Test の実行環境が検出された場合は、references/playwright-migration-deltas.md を読みます。実行環境が Playwright Test ではないブラウザーのみの依頼では、Playwright の手順を読み込まないでください。テスト本体を編集する前に、スクリプト、設定、セットアップを移行します。広範囲なテスト書き換えより、アダプターや Rsbuild／Rspack による修正を優先してください。
5. 設定の読み込み時に [MODULE_TYPELESS_PACKAGE_JSON] が出力された場合は、references/config-module-type.md を使用します。監査せずに警告を抑制したり、パッケージ全体のモジュールタイプを変更したりしないでください。
6. 移行対象のスコープを意味的に問題なく実行できる状態にします。失敗は次の順に修正します。依存関係の不整合、設定／リゾルバー、検出、セットアップ／環境／カバレッジ、モック／タイマー／スナップショット、テスト本体。
7. 移行後のマニフェストと実行数をベースラインと比較します。追加、削除、スキップ、除外されたテストをすべて明示的に分類してください。実行が成功しただけで同等と判断してはいけません。Jest のスナップショットを移行する場合は、references/jest-migration-deltas.md にあるスナップショットのクリーンアップと unchecked の検証も完了してください。
8. 不要になった一時的なエイリアス、診断用フック、コピーした旧来の回避策を削除します。動作または測定によって必要性が確認された設定だけを残してください。
9. 実行時間、ビルド、テスト実行時間、ログ、またはメモリに重大な悪化がある場合は、利用可能であれば rstest-debugging スキルを読み込んで従ってください。利用できない場合は、references/performance-diagnosis.md の移行時のフォールバックを使用し、測定されたボトルネックに応じて references/dependency-bundling-performance.md および／または references/mocked-module-build-graph.md を読みます。一度に変更する変数は1つにしてください。
10. 正確性とパフォーマンスの検証後、移行対象スコープが所有する旧ファイルと依存関係のみを削除します。動作の同等性、検出の差異、サポートされないフィールド、保持した互換性設定、パフォーマンス上のトレードオフ、TODO を要約してください。

ガードレール

• 実行可能な最小スコープを維持します。スコープがロックファイルを共有しているという理由だけで、モノレポの移行範囲を広げないでください。
• 移行を通すために、本番環境での動作、アサーション、テスト名、シナリオ、カバレッジしきい値、または除外指示を変更しないでください。
• jest／vi のシムやエイリアスを導入しないでください。references/global-api-migration.md を使って呼び出し箇所を書き換えてください。
• 不明な設定フィールドや過去からの除外を黙って削除しないでください。それぞれを検証するか、置き換えるか、報告してください。
• 異なるテストマニフェスト、Node バージョン、カバレッジモード、キャッシュ状態、またはワーカー設定の間でパフォーマンスを比較しないでください。
• Rstest で問題なく実行できるまでは、以前のテストランナーを残してください。ローカルの Rstest チェックアウトは、診断目的であることを明記して使用する場合に限ります。その後、プロジェクトにインストール済みの依存関係で最終結果を検証してください。
• 多数のテストを編集する前、または本番ソースを変更する前にエスカレーションします。小規模な設定／セットアップの修正で解決しなかった理由、選択肢、リスク、および推奨する進め方を報告してください。

Rstest で特に注意が必要な差分

• rstest／rstest run は単発実行です。ウォッチモードには rstest --watch または rstest watch を使います。
• globals のデフォルト値は false です。グローバル API を維持するには、globals: true と @rstest/core/globals の型が必要です。
• Rstest はテストの実行前にビルドします。rs.mock() は実行時の置き換えであり、それだけでは実際のモジュールグラフを削減できません。
• 依存関係のバンドルでは、コンパイラーの作業と引き換えに実行時の Node 読み込みを減らします。「すべてをバンドル」も「すべてを外部化」も、常に高速とは限りません。代表的なファイルと対象範囲全体で測定してください。
• 外部化された実行時モックは、リクエストとモジュール形式が完全に一致する必要があります。テストで実際のモジュールが必要な場合があるため、設定全体に適用する外部化は安全ではありません。