cofounder-testing

自動テスト

テストは、検証対象のコードと同時に作成します。ハンドラーを作成したら、テストファイルを作成します。インタラクティブなコンポーネントを作成したら、テストファイルを作成します。

2 つのレイヤー

レイヤー	テスト対象	必要なもの
1. バックエンドの単体テスト／結合テスト	ハンドラー、クエリ、ロジック	データベースのみ
2. フロントエンドのコンポーネント	UI ロジック、レンダリング、操作	なし（シミュレートされた DOM）

レイヤー 1 では、実際のデータベースに対する API コントラクトをテストします。レイヤー 2 では、モックした API 呼び出しを使って、UI ロジック、レンダリング、ユーザー操作をテストします。

コマンドの実行

すべてのコマンドは mise x -- を使って実行する必要があります（例：mise x -- go test、mise x -- npx vitest）。ツールを直接実行しないでください。

セットアップ手順

新しいプロジェクトを始めるときは、最初の機能を実装する段階で両方のレイヤーをセットアップします。各レイヤーについて、プロジェクトの言語とフレームワークで現在推奨されているテストランナーとライブラリを調べ、それに応じて設定してください。以下のセクションでは、テスト対象とテスト量を説明します。特定のライブラリについて説明するものではありません。

---

レイヤー 1：バックエンドの単体テストと結合テスト

Go には、組み込みのテストランナーがあります。

カバレッジの要件

• すべてのハンドラーに、少なくとも 1 つの正常系を網羅するテストを作成します。
• データベースにアクセスするコードには、モックではなく、実際のローカルデータベースに対して実行する結合テストを作成します。マイグレーションを実行し、各テストをロールバックするトランザクションでラップするテストヘルパーを使用します。
• HTTP ハンドラーは、テストサーバーに実際の HTTP リクエストを送信し、ステータスコードとレスポンスボディを検証してテストします。
• テーブル駆動テストを使用します。各テストケースには、内容がわかる名前を付けます。

コードと同じ場所に置くテストファイル

テストファイルは、テスト対象のコードと同じ場所に置きます。たとえば、handler/todo_test.go で handler/todo.go をテストします。新しいハンドラーファイルを作成したら、対応するテストファイルもすぐに作成します。

既存のコードベースへのテストの追加

1. 対応するテストファイルがないハンドラーファイルをすべて一覧表示します。
2. それぞれにテストファイルを作成します。まず、データベースにアクセスするハンドラーや、複雑なロジックを持つハンドラーから始めます。
3. 単純な処理の受け渡しだけを行うハンドラー（例：200 を返すヘルスチェック）は省略できます。

---

レイヤー 2：フロントエンドのコンポーネントテスト

コンポーネントテストでは、個々の React コンポーネントをシミュレートされた DOM にレンダリングし、ユーザー操作をシミュレートして、画面に表示される内容を検証します。バックエンドを起動せずに、条件付きレンダリング、フォームのバリデーション、状態管理など、UI ロジックの不具合を検出できます。

カバレッジの要件

• 複雑なロジックを持つコンポーネント（条件付きレンダリング、フォーム処理、計算された状態、イベントハンドラー）にはテストを作成します。
• 純粋なプレゼンテーションコンポーネント、つまりロジックなしで props を表示するだけのコンポーネントには、テストは不要です。
• レイアウト用のラッパーであるページや、すでにテスト済みの他のコンポーネントを組み合わせるだけのページには、独自のテストは不要です。

原則

• 実装ではなく、振る舞いをテストします。 コンポーネントをレンダリングし、ユーザーが行う操作（クリック、入力、送信）をシミュレートして、ユーザーに表示される内容を検証します。内部状態や実装の詳細は検証しないでください。
• 外部依存関係をモックします。 コンポーネントテストをバックエンドなしで実行できるよう、API 呼び出し、ルーターのコンテキスト、その他のサービスをモックします。
• コードと同じ場所にテストファイルを置きます。 テストファイルは、テスト対象のコンポーネントと同じ場所に置きます（例：TodoList.tsx の隣に TodoList.test.tsx）。

インタラクティブなロジックを持つコンポーネントで作成するテストの例：

// Render with props → simulate a click → assert visible result changed
test('marks a todo as complete when clicked', async () => {
  render(<TodoList items={[{ id: 1, text: 'Buy milk', done: false }]} />)
  await user.click(screen.getByText('Buy milk'))
  expect(screen.getByText('Buy milk')).toHaveClass('completed')
})

具体的な API は、使用するテストランナーとテスティングライブラリによって異なります。レンダリングし、操作し、表示内容を検証するというパターンは、どの環境でも共通です。

セットアップ

フロントエンドフレームワークと互換性のあるテストランナー（Vite ベースのプロジェクトなら Vitest など）と、ユーザーの視点に立ったテストを推奨する DOM テストライブラリを選びます。シミュレートされた DOM 環境（jsdom など）を設定し、package.json に test スクリプトを追加します。プロジェクトのツールチェーンで現在推奨されているセットアップを調べてください。

Vitest + Vite の設定： 'vite' ではなく、'vitest/config' から defineConfig をインポートします。これが、型チェックで test ブロックを受け入れさせる唯一の方法です。/// <reference types="vitest" /> は使用しないでください。オーバーロードのシグネチャは解決されず、tsc は TS2769 で失敗します。

Vitest では @vitejs/plugin-react を使用しないでください。 React Router のフレームワークモードではルーターのツールチェーンと競合し（Babel に互換性がありません）、Vitest は JSX をネイティブに変換します。JSX の変換設定は一切追加しないでください。

既存のコンポーネントへのテストの追加

1. 複雑なロジックを持つコンポーネントを特定します。
2. まず、それらのコンポーネントのテストファイルを作成します。
3. 安定したセレクターを使えるよう、主要なインタラクティブ要素に data-testid 属性を追加します。

TypeScript の型チェック — コミット前に必ず実行

開発サーバーは速度を優先して型チェックを省略し、本番ビルド（react-router build）も型チェックを行いません。そのため、未使用のインポート、型の不一致、設定ファイルの問題などのエラーは、自動的には検出されません。コミット前に必ず型チェックを実行してください。

bash -c 'cd "$(git rev-parse --show-toplevel)/frontend" && mise x -- npm run typecheck'

スキャフォールドの typecheck スクリプトは react-router typegen && tsc を実行します。tsc が必要とするルートの型は、typegen のステップで frontend/.react-router/ に生成されます。生成済みの型がないと、新しくチェックアウトした環境では失敗するため、tsc だけを直接実行しないでください。

---

カバレッジの補完

テストの実行後、バックエンドで _test.go のないハンドラーや、ロジックがあるのに .test.tsx がないフロントエンドコンポーネントがないか確認します。不足している箇所をユーザーに報告し、テストの追加を提案してください。