rstest-best-practices

Rstest のベストプラクティス

Rstest プロジェクトのセットアップ、記述、レビューでは、以下のルールを適用してください。

ワークフロー

• 編集する前に、既存のパッケージマネージャー、依存関係のポリシー、モジュールモード、ビルド設定、テストの配置、フレームワークの規約を確認してください。
• @rstest/core、パッケージ固有のテストスクリプト、パッケージのモジュールモードに合った拡張子の設定ファイルを追加してください。
• 既存のビルド設定を再利用するのは、メンテナンスコストを削減でき、互換性も保てる場合に限ってください。アダプターは任意です。アダプターとの統合に互換性がない場合や、コストが不釣り合いに高い場合は、独立した Rstest 設定を使用し、必要なエイリアス、プラグイン、定義、環境、外部モジュールを明示的に再現してください。
• テストの検出、環境、セットアップファイルは意図を持って設定してください。テストがない状態を想定し、その状態が文書化されている場合を除き、passWithNoTests を有効にしないでください。
• rstest list でテストが検出されることを確認してから、対象を絞ったテスト、全テスト、プロジェクト既存のビルドまたは型チェックのコマンドを実行してください。

設定と環境

• @rstest/core の defineConfig を使用し、パッケージのモジュールモードに対応した拡張子の設定ファイルを使用してください。
• globals: true よりも、@rstest/core からの明示的なインポートを優先してください。
• 共通のマッチャーとクリーンアップには setupFiles を使用してください。通常のビルド統合には plugins、resolve、または source を使用し、低レベルの tools は必要な場合にのみ使用してください。
• パッケージのテスト配置が標準的でない場合は、include を明示的に設定してください。デフォルトの検出パターンを前提にしないでください。
• サーバー／SSR のテストには node、シミュレートした DOM のテストには happy-dom または jsdom、実ブラウザーの動作確認には Browser Mode を使用し、選択した環境パッケージを明示的にインストールしてください。
• React または Vue のコンポーネントテストでは、対応するビルドプラグインを登録し、該当する Testing Library を使用してください。また、マッチャーの拡張とクリーンアップをセットアップファイルにまとめてください。
• 環境や設定が実際に異なる場合に限り、複数のテストプロジェクトを使用してください。レポーター、カバレッジ、プール、分離、打ち切りなどのグローバルオプションはルートにまとめてください。

テストの記述

• 1 つの公開動作を検証する小さなテストを優先してください。.skip や .todo は意図を持って使用し、.only は決してコミットしないでください。
• テスト API とテストファイルは、プロジェクトと同じモジュールシステムを使用してください。ランタイムとバンドラーの動作を検証せずに、ESM と CJS の前提を混在させないでください。
• アサーションを見落とす可能性がある try/catch パターンよりも、await expect(promise).resolves... や .rejects... を優先してください。
• includeSource は小さなユーティリティにのみ使用し、テストを import.meta.rstest で保護し、本番ビルドでは false に設定してください。

モック

• 関数には rs.fn()、オブジェクトのメソッドには rs.spyOn()、モジュールには rs.mock() ファクトリーを使用し、テスト対象そのものではなく外部との境界をモックしてください。
• テスト間で呼び出し、実装、元のメソッドのどれを復元する必要があるかに応じて、clearMocks、resetMocks、restoreMocks を選択してください。
• モジュールシステムに合ったモジュールモック API を選択してください。リクエスト文字列が正確であることを確認し、テスト対象モジュールが評価される前に、ホイストされるモックまたは静的モックを登録してください。
• モジュールモックはランタイムの動作を置き換えますが、Rspack のビルドグラフから実際の依存関係が必ず削除されるわけではありません。不要または利用できない依存関係をビルドが引き続きたどる場合に限り、エイリアスまたは範囲を絞った外部モジュール設定を使用し、ランタイムの外部化形式を確認してください。

スナップショットとカバレッジ

• スナップショットは小さく、決定的なものにしてください。短い出力にはインラインスナップショット、大きな構造化出力にはファイルスナップショットを使用し、不安定なデータやパスにはシリアライザーを使用してください。更新内容はすべて確認してください。
• --coverage または coverage.enabled を使用してカバレッジを有効にしてください。
• インストール済みの Rstest バージョンがサポートするカバレッジプロバイダーを選択し、そのパッケージを明示的に追加してください。プロジェクトの要件を確認せずに、V8 または Istanbul のプロバイダーをそのまま選ばないでください。
• しきい値を追加する前に coverage.include を慎重に設定してください。人が確認するレポーターと CI 成果物向けのレポーターは分けて選択してください。

実行と CI

• 1 回の実行には rstest を使用します。rstest run も任意の明示的な同等コマンドです。rstest --watch または rstest watch は、ローカル開発時にのみ使用してください。
• テストの検出を確認するには rstest list を使用します。実行対象を絞るには位置引数のフィルターまたは -t を、意図的にスナップショットを更新するには -u を、デフォルト以外の設定を使用するには -c を使用します。
• CI では、ウォッチモードを使用しないでください。テストを分割して実行する場合は、シャーディングと Blob レポート、および rstest merge-reports を使用してください。CI システムで機械可読な結果が必要な場合は、JUnit を使用してください。
• テスト成功時のログが多すぎる場合は、silent: 'passed-only' の使用を検討してください。セットアップまたは実行時の出力を診断する際は、一時的に無効にしてください。

まず行うデバッグ

• 実行対象を絞った再現から始め、--reporter=verbose を指定します。コンソール出力が多すぎる、または不明瞭な場合は、--printConsoleTrace を使用してください。
• DEBUG=rstest を使用し、dist/.rstest-temp/.rsbuild/ を確認して、最終的な Rstest／Rsbuild／Rspack の設定と生成されたビルド出力を検証してください。
• 実行時の障害には、Rstest VS Code 拡張機能または JavaScript Debug Terminal を使ってブレークポイントを設定してください。
• 起動、ビルド、実行、ログ、メモリ、パフォーマンスを体系的に診断するには、rstest-debugging を使用してください。

ドキュメント

• 最新の Rstest ドキュメントについては、https://rstest.rs/llms.txt を参照してください。