name: tdd-workflow description: テスト駆動開発（TDD）のワークフロー定義。テスト実行はDockerコンテナ内で行う。Red→Green→Refactorのサイクル手順、テストの書き方、DDD規約との統合方法を定義する。テスト実装・実行時に使用する。 user-invocable: false allowed-tools: Read, Write, Edit, Glob, Grep, Bash, TaskUpdate, TaskGet, TaskList

TDDワークフロースキル

TDDサイクル

1. Red フェーズ（テストを先に書く）

手順

1. テストファイルを作成する（*.spec.ts）
2. テスト対象の期待する振る舞いをテストケースとして記述する
3. テストを実行し、失敗することを確認する

テストの書き方

describe('[テスト対象クラス名]', () => {
  beforeEach(async () => {
    // テスト用のモック・フィクスチャを準備
  });

  it('[期待する振る舞いを日本語で記述]', async () => {
    // Arrange: テストデータの準備
    // Act: テスト対象の実行
    // Assert: 結果の検証
  });
});

itのテスト名

• itのテキストは日本語で記述する
• テスト対象の振る舞いを簡潔に表現する（例: '有効なメールアドレスで生成できる'）

DDD層別のテスト方針

Adapter層のテスト方針

• Adapter層のテストではモックを使用せず、テストDBに実際に接続してアサーションを行う
• テストDBへの接続はDockerコンテナ内のテスト環境で自動的に行われる
• 各テストケースはデータの独立性を保つため、テストデータの投入・クリーンアップを各テストコードで必ず行う

2. Green フェーズ（最小限の実装）

手順

1. テストが通る最小限のコードを実装する
2. 「動くコード」を最優先する
3. テストを実行し、すべて通ることを確認する

原則

• 完璧なコードを書こうとしない
• テストに書かれていない機能は実装しない
• 既存のテストが壊れていないことも確認する

3. Refactor フェーズ（品質改善）

手順

1. コードの重複を排除する
2. 命名を改善する（DDD規約に準拠）
3. 不変性、ファクトリメソッド等のDDD規約への適合を確認する
4. テストを再実行し、すべて通ることを確認する

リファクタリング観点

• 単一責任の原則に違反していないか
• DDD層の責務が正しく分離されているか
• 命名がドメインの言葉を使っているか
• 不要なコメントや死んだコードがないか
  • コメントは基本的には記述せず、コード自体で意味を説明できるようにする

テスト実行コマンド

重要: テストは必ずDockerコンテナ内で実行する。

# 特定のテスト実行
docker compose exec backend npm run test -- /src/path/to/test.spec.ts

# 全テスト実行
docker compose exec backend npm run test

テスト失敗時の対応

1. エラーメッセージを正確に読む
2. 期待値と実際の値の差分を確認する
3. Greenフェーズの実装を修正する（テストは変更しない）
4. テストを再実行する
5. 3回修正しても通らない場合は、テストの前提条件を見直す

マイグレーション作成手順

エンティティ変更を伴うタスクでは、以下の手順でマイグレーションを作成する。

1. エンティティファイル（*.entity.ts）を変更・作成する
2. data-source.ts の entities 配列にエンティティを登録する
3. migration:generate コマンドでマイグレーションを自動生成する

docker compose exec backend npm run migration:generate -- src/infrastructure/typeorm/migrations/<MigrationName>

4. 生成されたマイグレーションクラスを data-source.ts の migrations 配列に登録する
5. data-source.spec.ts のテストを更新する

注意: マイグレーションファイルは手動作成しない。必ず migration:generate で自動生成する。

テストケースの原則

• テストケースはそのクラス固有の振る舞い（ドメインロジック・バリデーション・状態遷移等）のみを検証する
• 言語機能そのもの（getter/setterの動作、=== 演算子の挙動、型キャストの結果等）はテストしない
  • 例: value getterが値を返すだけのテストは不要（createテストで既に検証される）
  • 例: equals() の実装が単純な === 比較の場合、同値/非同値の基本テストは === のテストに過ぎない
  • 例: TypeScriptの型契約を as unknown as string でバイパスしたnull/undefinedのテストはクラスの責務外
• クラス固有のロジックが絡むケースのみテストする
  • 例: 正規化（トリム、null→undefined変換等）が等価性比較に影響するケース
  • 例: バリデーションルール（文字数制限、フォーマット検証等）
  • 例: ファクトリメソッドでの入力変換ロジック

テストのアンチパターン

• テストが実装の詳細に依存している（privateメソッドのテスト等）
• テスト間に順序依存がある
• テストデータが共有されている（各テストは独立すべき）
• テストデータがテストの並列実行時に重複エラーになってしまう
• モックが多すぎる（設計の問題のサイン）
• テスト名が意味のない名前になっている
• テスト名が過剰な説明文を反映したものになっている
• 言語機能のテスト（上記「テストケースの原則」参照）