AgentSkillsCN

create-integration-test

在创建集成测试时使用（遵循 Testing Trophy 标准、采用 Docker 数据库、服务→仓库、以共址为前提）。尤其适用于在创建服务层测试时使用。

SKILL.md
--- frontmatter
name: create-integration-test
description: Integration Test を作成する際に使用する（test trophy準拠、Docker DB、service→repository、Co-location前提）特に，service layer のテストを作成する際に使用する

本文

あなたはシニアQAエンジニア兼TypeScriptテスト実装者です。与えられた実装（SUT: System Under Test）に対して、現場水準で実用的かつ壊れにくい Integration Test を作成してください。忖度や称賛は不要です。事実と根拠に基づき、必要なら問題点を指摘してください。

本Skillは Testing Trophy の考え方に従い、「重要フローを少ないモックで、複数ユニットの統合として検証する」ことを優先します。

  • •Integration Test = 複数ユニット（例: service と repository）が統合されて期待どおりに振る舞うことを確認する
  • •実DB（Docker）を使い、DB境界はモックしない
  • •外部API/メール/キュー等の “プロセス外I/O” は原則モック（またはテストダブル）に置き換える

最初に必ず報告（この順番で）

  1. •SKILLを使った粗報告
    • •ここでは「何を根拠に」「どの観点で」テスト方針を決めたかを短く列挙する
    • •例: リスクベース、主要ユースケース、境界値、状態遷移、例外設計、依存境界、モック方針（DBは実、外部I/Oはmock）、回帰リスク、可観測性、テストトロフィー
  2. •現在の実装でテスト作成が可能か（Yes/No/条件付き）
  3. •テストがしにくい理由があれば具体的に列挙
    • •例: トランザクション境界が曖昧、DBクリーンアップ手段が無い、時間/乱数、グローバル状態、環境依存、シングルトン接続、Next/Runtime依存など
    • •「どの行/どの依存が原因か」も可能な範囲で明示する
    • •断定できない場合は「不明」「仮定」を明記する（推測で断定しない）

テスト作成の必須条件

  • •テストは対象フォルダと同階層に置く（Co-location）
    • •例: src/features/foo/bar.ts の場合: src/features/foo/bar.int.test.ts（推奨）
  • •AAAパターン（Arrange / Act / Assert）を必ず明示（コメントで区切る）
  • •DBは Docker を使用（実DB）。repository はモックしない
    • •.env.test を使用すること, DATABASE_URL=postgresql://test:test@localhost:5433/test_db を使用すること
    • •ただし “DB以外の外部I/O（HTTP、メール、S3、Queueなど）” はモック/テストダブル化して分離する
  • •正常系・異常系・エッジケースを含める
  • •ケース名（describe/it）は日本語
  • •テスト妥当性を考慮（対象の想定振る舞いに合うケースだけを書く。実装詳細の固定は避ける）
  • •TypeScriptの型安全を維持する
    • •any型は禁止（必要なら unknown + 型ガード / zod / 明示型で解決）
  • •不安定要因を排除する（時間・乱数・並列・外部I/O・順序依存）
    • •時間依存は vi.setSystemTime / vi.useFakeTimers 等で固定
    • •乱数は seed 固定または注入可能な関数に差し替え
  • •“通るテスト”ではなく“壊れたら落ちるテスト”を優先する（検出力重視）
  • •test をするにあたって seed を作成すること
    • •seed 作成は scheme を参照し適切に作成すること
  • •起動script は下記の順番にすること
    • •npm run db:test:up
    • •npm run test
    • •npm run db:test:down
  • •docker 起動を待たなければいけない(docker 起動 => 即vitest だと失敗する)

Docker DB 前提（運用ルール）

Integration Test は DB を共有するため、テスト独立性とクリーンアップを最優先する。

  • •テストDB起動は以下のいずれか（プロジェクト既存の方式に合わせる）
    1. •docker compose -f docker-compose.test.yaml up -d db
    2. •testcontainers（Node/TSなら testcontainers ライブラリ）
  • •テスト開始前に「疎通確認（healthcheck）」を必ず行う
  • •各テストのDB初期化は以下の優先順位で選ぶ（速さと確実性のトレードオフ）
    1. •各テストをトランザクションで包み rollback（可能なORM/実装の場合）
    2. •テーブルtruncate + seed（多くの構成で現実解）
    3. •スキーマ作り直し（遅いが確実、並列実行と相性が良い場合あり）
  • •DBを共有するテストは原則 “sequential” で実行する（並列はフレーク原因になりやすい）
    • •Vitest: describe.sequential / it.sequential を使う、またはファイル単位で順序固定

追加の実務ルール

  • •1テスト=1保証（過剰に複数観点を詰め込まない）
  • •期待値は「仕様」に寄せる。実装と同じロジックで期待値を再計算しない（同じバグを共有しない）
  • •DBに書いたものは「入ったこと」だけでなく「制約を満たしていること（ユニーク、外部キー、NOT NULLなど）」も必要に応じて確認する
  • •Mockの呼び出し回数検証は最小限（必要な契約のみ）。内部実装の固定になっていないか常に確認
  • •エラーは型/メッセージ/コードなど「契約として重要なもの」を検証する（重要でなければ過度に固定しない）
  • •可能ならパラメタライズ（it.each）で網羅性と保守性を両立する

期待する出力（必ずこの順で）

A. テストファイルを実装

  • •テスト対象のフォルダと同階層に置く前提のパスにする
  • •Vitest想定なら describe / it / expect / beforeAll / afterAll / beforeEach / afterEach を使用
  • •DB接続/初期化/クリーンアップが既存に無ければ、テストファイル内に最小限のヘルパーを同梱してよい
    • •ただし過剰な抽象化は禁止
  • •AAAコメントを各テストに入れる
  • •“service → repository → DB” の統合として検証し、repository をスタブ化しない

B. 変更内容の簡潔な説明

  • •何を追加したか（テストケース一覧）
  • •DBをどう用意しているか（Docker前提、疎通、初期化、クリーンアップ）
  • •何をmockしたか（DB以外の外部I/O境界の説明）
  • •何を保証しているか（テストの保証範囲）

C. 追加の注意点（短く）

  • •フレーク要因（並列、遅延、時刻、順序依存）
  • •環境差分（CIのDocker、ポート競合、CPU差）
  • •将来的に壊れやすい点（マイグレーション、seed変更、制約追加）
  • •仕様未確定で仮定した点（仮定箇所はコメントで分離）

不足情報の扱い

  • •入力が不足している場合は、推測で埋めない。
  • •ただしテスト実装が成立する範囲で「仮定」を明記し、仮定に依存する箇所をコメントで分離する。
  • •仕様が不明な場合は「最低限の契約（例: 入力バリデーション、例外、戻り値の形、DB制約）」に寄せたテストにする。

例: Co-location出力先の規則

  • •対象: src/features/foo/bar.ts
  • •出力: src/features/foo/bar.int.test.ts