ts-testing

このスキルは、TypeScript コード向けに実用的で保守しやすいテストスイートを構築するためのガイドです。動作の網羅性、迅速なフィードバック、プロジェクトで既に使われているツールとの整合性を重視します。

ユーザーは TypeScript を中心に開発しています。正確性やリファクタリング時の安全性を重視し、不安定で壊れやすいテストに振り回されたくないと考えているでしょう。

このスキルを使う場面

次のような場合に、このスキルを使ってください。

• ユーザーが単体テスト、統合テスト、またはエンドツーエンドテストを追加・更新している
• ユーザーがバグを報告し、回帰テストを求めている
• ユーザーがリファクタリングを行い、動作を壊していないという確信を得たいと考えている
• リポジトリにテストツールが設定されている（または明らかに必要である）状態で、「テストを追加」または「テストを改善」するよう依頼されている

リポジトリに既存のテストスタックがある場合、新しいものを独断で導入しないでください。まず既存の設定を確認し、それに従ってください。

ライブラリの選択

まず、必ずリポジトリの構成に合わせてください（package.json、devDependencies、設定ファイルを確認します）。

• リポジトリですでにフレームワーク（Jest、Vitest、Playwright、Cypress など）を使っている場合は、そのまま使ってください。
• 明確なテストスタックがまだない場合に限り、新しいライブラリを提案してください。

選択が必要な場合は、次を優先してください。

• 単体テスト／統合テスト
  • Node／バックエンド／共有ライブラリ：
    • Vitest（vitest）または Jest（jest）を優先します
    • vitest がある場合はそれを使ってください。なければ jest がある場合はそれを使ってください。
• React／UI コンポーネントのテスト
  • 既存のランナーと組み合わせて Testing Library を使います。
    • Vitest または Jest と @testing-library/react を使います
• ブラウザーのエンドツーエンドテスト
  • インストール済みの場合、または新規に始める場合は Playwright を優先します。
  • リポジトリですでに使われている場合、またはユーザーが明示的に求めている場合は Cypress を使います。

リポジトリで一般的ではないスタック（Mocha、Ava、Node の組み込みテストランナーなど）を使っている場合は、その選択を尊重し、それに合わせてください。

テストの基本方針

次の原則に従ってください。

• 実装の詳細ではなく、動作をテストする
  • React／UI の場合：内部状態や非公開メソッドではなく、ユーザーが見て操作する内容（DOM、イベント、ARIA）をテストします。
  • サービスの場合：非公開のヘルパーではなく、公開 API をテストします。
• テストは高速かつ的を絞る
  • すばやく実行できる、小規模で決定的なテストを優先します。
  • 統合テストを明示的に作成する場合を除き、不要なネットワーク、ファイルシステム、データベースの呼び出しは避けます。
• 失敗の原因がすぐ分かるようにする
  • 失敗の理由を説明する、明確な名前とアサーションを使います。
  • 役立つ場合は、「前提／操作／結果」の形式に沿った、説明的なテスト名を付けます。
• モックは最小限にし、適切な場面で使う
  • 外部サービス、ネットワーク呼び出し、処理に時間のかかる依存関係をモックします。
  • 強い理由がない限り、独自のビジネスロジックはモックしないでください。

標準的なワークフロー

テストの追加または改善を依頼された場合は、次のワークフローに従ってください。

1. 既存のスタックを確認する

   • package.json で jest、vitest、@playwright/test、cypress、@testing-library/* を確認します
   • 設定ファイルを探します：jest.config.*、vitest.config.*、playwright.config.*、cypress.config.*
   • package.json の test、unit、e2e スクリプトを確認します

2. テストに適した場所を見つける

   • 既存のパターンに合わせます：
     • テストが __tests__ ディレクトリにある場合は、それに従います
     • *.test.ts または *.spec.ts を使っている場合は、同じ形式にします
   • UI の場合：既存の規約に従い、コンポーネントの近く（例：Component.test.tsx）にテストを配置します

3. TypeScript に適した方法でテストを書く

   • リポジトリの規約に応じて、.test.ts／.test.tsx（または .spec）を使います
   • 可能な限りテストで any を避け、実際の型または最小限のインターフェースを使ってテストの堅牢性を保ちます
   • 非同期コードでは、非同期テスト関数内で await を使い、未処理の Promise を残さないようにします

4. ライブラリ固有のベストプラクティスに従う

   Vitest／Jest

   • わかりやすい名前を付けて describe／it または test を使います
   • スパイやモックには vi.fn()／jest.fn() を優先します
   • モジュールには vi.mock()／jest.mock() を使い、モックはファイルの先頭に置きます
   • タイマーには、必要な場合に限りフェイクタイマーを使います（vi.useFakeTimers()／jest.useFakeTimers()）

   React Testing Library

   • render、screen、ユーザー操作（userEvent）を使います
   • ユーザーと同じようにロール、ラベル、テキストで検索します（getByRole、getByLabelText を優先します）
   • 適切なセマンティックな代替手段がない場合を除き、テスト ID による検索は避けます

   Playwright／Cypress

   • 独自に作り直すのではなく、既存のフィクスチャやヘルパー（認証済みセッション、ベース URL など）を使います
   • テストは独立させ、実行順序に依存させないようにします
   • ロケーターには data-testid またはセマンティクスを一貫して使います

5. 報告されたバグの回帰テストを追加する

   • まず、失敗するテストでバグを再現します
   • その後、テストが通るように実装を変更します
   • 回帰テストには、内容が明確な名前を付けます（例：it("does not crash when X is null (regression #123)")）

6. テストを実行する

   • 既存のスクリプトを使います。例：npm test、pnpm test、npx vitest、npx jest、npx playwright test
   • 新しいテストコマンドを追加する場合は、既存のスタイルに従って package.json のスクリプトに組み込みます

推奨するパターン

• 1 つのテストにつき 1 つの振る舞い：同じシナリオの一部でない限り、互いに無関係な複数のアサーションを 1 つのテストに詰め込まないでください。
• ヘルパーファクトリー：セットアップを重複させず、テストデータを作成する小さなファクトリー関数（makeUser、makeOrder など）を使います。
• 明示的な非同期処理：Promise には必ず await を使い、非同期コールバックを想定していない API に非同期コールバックを渡さないでください。

避けるべきアンチパターン

• 複雑なオブジェクトや DOM に対するスナップショットの多用。代わりに、対象を絞ったアサーションを使います
• プライベートメソッドを直接テストすること
• テストが実装の配線をそのまま模倣するほどの過剰なモック
• 制御されていない実時間、ネットワーク、グローバル状態に依存する不安定なテスト

TypeScript 固有のガイダンス

• 可能であれば、テストにはプロジェクトの tsconfig（存在する場合は tsconfig.test.json）を使います
• 「テストをコンパイルするため」だけに型エラーを握りつぶさないでください
• データのスタブ化には、as any を使うのではなく、最小限の型付きヘルパーを作成します

テストの生成を依頼された場合は、大規模で機械的なテストスイートよりも、実際の使用状況を反映した、数を絞った価値の高いテストを優先してください。