qa-data-seeder

QA データシーダー

機能の実装方法を分析し、QA に必要なすべてのカテゴリを網羅するバランスの取れたデータセットを設計して、対象環境に投入します。これにより、手動または自動で機能をテストできます。

重要な制約

• 本番環境には絶対にデータを投入しないでください。 データを書き込む前に、対象環境がテスト／開発／ステージング環境であることを確認してください。不明な場合は、作業を中止して確認してください。
• 壊れたデータは絶対に生成しないでください。 シードするすべてのレコードが、アプリケーション独自の検証に合格する必要があります。エッジケースは、極端ではあっても有効な値であり、破損したデータではありません。不正な形式の入力は、永続化されたシードデータではなく、実行時のネガティブテストで扱ってください。
• データセットのバランスを保ってください。通常（想定どおり）のデータを少なくとも70％、エッジケースを最大30％にします。
• ユーザーがカテゴリと正確な件数を承認するまで、データを投入しないでください（ステップ3のゲート）。
• 認証情報、トークン、接続文字列は環境変数またはユーザー入力から取得し、ハードコードしないでください。
• プロジェクトに既存のシード方法（ファクトリー、シードスクリプト、フィクスチャ、管理コンソール）があれば優先してください。ほかに、REST API または MCP も利用できます。シードスクリプトはアプリケーションの言語で記述してください。
• 生成した成果物（データセット計画、一時的なシードスクリプト）は、Git で無視される .testeiya/seed-data/ に保存してください。.gitignore に .testeiya/ がない場合は追加してください。
• すべてのシードレコードに、認識しやすい同一の識別子を付けてください（スキーマで許可されている名前、メモ、タグフィールドなどを使用します）。これにより、QA がデータを見つけ、後で削除できます。今回の実行では、すべてのレコードに同じ識別子を使用してください。

ワークフロー

ステップ1：機能を理解する

何かを提案する前に実装を確認してください。以下を収集します。

• この機能が扱うエンティティとモデル、およびすべてのフィールド：型、形式、長さ制限、数値範囲、列挙値、必須／任意、一意性、デフォルト値。
• 検証ルール（アプリケーションレベルのもの、およびデータベースの制約やマイグレーション）。
• 関連付けと前提条件：ほかのレコードを作成する前に存在している必要があるレコード。
• 動作を変えるビジネス上の差異：ロール、ステータス、種別、プラン／ティア、ロケール、機能フラグ、時間依存のロジック。
• これらのレコードを作成する API エンドポイント（または UI フロー）と、それらが要求する情報。

コードにアクセスできない場合は、API スキーマ（OpenAPI／Swagger、GraphQL のイントロスペクション）を利用するか、ユーザーにドキュメントを依頼してください。MCP が利用可能な場合は使用してください。

ステップ2：環境の詳細を収集する

❓ コードからは分からない情報を確認してください。

• プラットフォーム：ウェブ、モバイル、または API のみ。
• ウェブの場合はベース URL、シード投入用の API ベース URL。
• 環境の種類（ローカル、開発、ステージング）。本番環境ではないことを確認します。
• 利用可能なアクセス手段：既存のシード方法、REST API、データベース／コンソールへのアクセス。
• 認証方法：トークンや認証情報が格納されている環境変数。
• シードを投入するアカウント／テナント／ワークスペース、または新規に作成するかどうか。

シード方法は、次の順に選択します：既存のシード方法 → アプリのコンソール／コード → 新しい小規模スクリプト → REST API → MCP。 ローカル環境では、バックエンド経由でデータをシードできます。

ステップ3：カテゴリを提案して件数を確認する

• ステップ1をもとにカテゴリを導き出します。ビジネス上の差異ごとに1カテゴリを設け、エッジケースのグループ（最小／最大の長さと金額、Unicode、日付の境界、すべての列挙値と到達可能な状態、任意フィールドが空の場合とすべて入力された場合、コレクションと関連付けの両極端）を加えます。
• 次の項目を含む表を提示します：カテゴリ、QA がテストできる内容、通常／エッジ、予定割合。
• 通常カテゴリは全体の70％以上、エッジカテゴリは30％以下にします。
• ❓ ユーザーに項目の正確な合計数を確認し、カテゴリごとの件数を再計算して確認します。
• 何かを生成する前に、ユーザーのフィードバックに応じてカテゴリを調整します。

ステップ 4：データセットを生成する

• 現実的な値を使用します。本番データのように見える名前、メールアドレス、住所、金額を使い、スキーマで一意性が求められる場合は一意にします。
• 利用できる場合は、faker／Lorem Ipsum のジェネレーターを使用します。
• 前提となるレコードを先に配置します（親レコードを子レコードより先に、参照先のレコードを参照元のレコードより先にします）。
• すべてのレコードに実行マーカーを適用します。
• シードを実行する前に、データセット（レコードまたは生成ルール）を .testeiya/seed-data/ に保存し、実行内容を確認・再現できるようにします。

ステップ 5：環境にシードデータを投入する

• 選択したチャネルを使い、依存関係の順にシードデータを投入します。チャネルが対応している場合は、バッチ処理を行います。
• 各バッチの書き込み時に検証します。API のレスポンスコード、返された ID、レコード数を確認します。
• アプリケーションがレコードを拒否した場合は、ジェネレーターを修正して要件に適合させます。データベースに直接書き込んで検証を回避してはいけません。
• あるカテゴリで 3 回失敗した場合は、エラー出力とともに失敗を報告し、次の進め方を確認します。

ステップ 6：検証して引き継ぐ

• カテゴリごとに環境へ再クエリし、件数を承認済みの計画と比較します。
• カテゴリ、要求数、作成数、レコードの検索方法（マーカー）を記載した表を報告します。
• 環境の URL と、Web の場合は QA がシードデータを確認できるページを記載します。
• クリーンアップ手順を示します。マーカーでレコードを検索し、同じチャネルを使って削除する方法を説明します。
• 追加対応として、シードデータを使ったテストケースを作成する qa-write-test-cases、またはデータセットで網羅すべきシナリオを探る qa-thinking を提案します。