build-scenario-tests

シナリオテストの構築

1 つの小さな振る舞いの契約を、決定論的でリポジトリ固有のテストコードに変換します。ハーネス、コマンド、フィクスチャ、セレクター、アサーションを選ぶ前に、ホストプロジェクトを理解してください。

運用上の契約

• リポジトリの指示と既存のテストを正とします。
• 各シナリオは、1 つの振る舞いと 1 つの失敗理由に絞ります。
• リポジトリがすでに使用しているテストスタックに変換します。適切なハーネスがない場合に限り、ユーザーがトレードオフを受け入れたうえで依存関係を追加します。
• セットアップ、入力、アクション、期待される結果を決定論的にします。
• 実装の詳細ではなく、公開された振る舞いを優先します。ユーザーや外部の呼び出し元から観測できるものをアサートします。
• Markdown のシナリオはテストの隣、またはリポジトリで定められた仕様ディレクトリに置きます。両方の成果物に対応関係を記録します。
• テストを通すためだけにアサーションを弱めてはいけません。

ワークフロー

1. リポジトリ理解のゲートを通過する

最も近い AGENTS.md または同等の指示、製品 README、コントリビューションガイド、マニフェスト、テスト設定、関連する製品ドキュメントのうち必要最小限のものを読みます。リポジトリ内検索を使い、実装のエントリーポイント、隣接するテスト、フィクスチャ、安定したセレクター、検証コマンドを探します。関連するアクションについて、公開エントリーポイントから状態の境界を経て、観測可能な結果に至るまで追跡します。理由もなくツリー全体を読まないでください。

編集を始める前に、次の内容を説明できる状態にしてください。

product surface:
behavior source:
relevant architecture and data flow:
runtime or start command:
existing test runner:
nearest tests to imitate:
fixture and state-isolation strategy:
narrow validation command:
full validation command:
known trust or destructive boundaries:

重要な項目が不明な場合は、もう一度検索します。リポジトリから答えが得られない場合は、不足している情報を明示し、必要な製品判断だけを尋ねてください。コマンド、セレクター、認証情報、期待される振る舞いを創作してはいけません。

2. シナリオを正規化する

references/scenario-format.md を読みます。ユーザーが文章を提示した場合は、意図を変えずにその契約に沿った形に書き直します。

次の場合は、シナリオを却下するか分割します。

• 独立した複数の振る舞いを含んでいる。
• 主観的な視覚的判断に依存している。
• 制御できないサードパーティの状態、実際の支払い、人間による承認を必要とする。
• 「正しく動作する」のような曖昧な結果を使っている。
• データ、時間、乱数、ネットワーク依存関係をリセットできない。

範囲が広いジャーニーやエージェントによる判断が必要なジャーニーは、スモークテストのワークフローに切り替えます。

3. 意図をホストのテストスタックに対応付ける

コードを書く前に、簡潔な対応表を作成します。

シナリオ要素	リポジトリでの実装
前提条件	フィクスチャ、ファクトリー、シード、フェイク、またはセットアップ API
ユーザーアクション	公開 UI、CLI、HTTP、SDK、またはネイティブ操作
判定基準	表示状態、出力、レスポンス、永続状態、または発行イベント
クリーンアップ	トランザクションのロールバック、フィクスチャの破棄、または分離された一時状態

振る舞いを検証できる、既存の最も小さなハーネスを選びます。

• Web またはデスクトップ UI：リポジトリのブラウザーまたは UI ランナー
• API またはサービス：ネイティブの統合テストクライアント
• CLI：既存のサブプロセスまたはコマンドランナー
• モバイル：プロジェクトのネイティブ UI テストフレームワーク
• ライブラリ：現在のテストランナーを通じた公開 API

安定した公開 API テストでより直接的に証明できる振る舞いに、ブラウザーテストを無理に適用しないでください。

4. 決定論的なテストに変換する

周囲のコードスタイルに合わせてテストを書きます。次の追跡可能性を保ってください。

• テスト名またはメタデータにシナリオ ID を含めます。
• ローカルの慣習で問題がない場合は、短いコードコメントからシナリオのパスにリンクします。
• Markdown に記載されたすべての判定基準を、アサーションで表現します。
• 安定したロール、ラベル、テスト ID、公開出力、または API 契約を使用します。
• 既存のファクトリー、フェイク、一時ディレクトリ、またはトランザクションを使って状態を分離します。
• 結果に影響する場合は、時間、乱数、リトライ、ネットワーク呼び出しを制御します。
• アサーションに失敗した場合も、必ずクリーンアップを実行します。

同梱のデモコードをそのままコピーしてはいけません。これは対応付けを示すための架空のフィクスチャであり、プロジェクトで再利用できるインフラストラクチャではありません。

5. コンパイルを検証する

新しいテストだけを実行します。そのチェックを安全かつ実用的に行える場合は、動作やリグレッション修正を加えていない状態で、意図した理由により失敗することを確認します。続いて、関連性が最も高いテストスイートと、リポジトリで必須の lint、型チェック、ビルド、テストの各コマンドを実行します。

失敗の意味を確認します。テストに誤りがある場合に限り、テストを修正します。ユーザーから実装や修正を依頼されていない限り、製品の動作を変更しないでください。

以下を確認します。

• Markdown の各オラクルに、それぞれ対応するアサーションがあること。
• ライブサービス、アカウント、決済、本番環境への依存が意図せず含まれていないこと。
• 繰り返し実行しても状態が分離され、順序が安定していること。
• 失敗時の出力から、どの動作に問題があるかが分かること。
• シナリオとコンパイル済みテストが相互に対応していること。

6. 根拠を引き継ぐ

以下を報告します。

1. テスト設計の根拠としたリポジトリ内の証拠。
2. シナリオのパスとコンパイル済みテストのパス。
3. 対象とした動作と境界。
4. 実行したコマンドとその結果。
5. 意図的に統合テストまたはスモークテストに委ねた内容。

使用例

• Web ワークスペースへの招待と、それに対応する例示用の Playwright コンパイル。
• CLI セッションの期限切れと、それに対応する例示用の pytest コンパイル。

これらを使って、Markdown からコードへのモデルを説明します。このスキルを適用する際は、実際のリポジトリに基づいてすべてのコマンド、フィクスチャ、アサーションを作成します。

失敗への対処

• テストハーネスがない場合：実行可能な最も近い接続点を記録し、依存関係を追加する前に確認を求めます。
• 動作が文書化されていない、または矛盾している場合：証拠を保持し、どの結果を正式なものとするかプロダクトオーナーに確認します。
• 失敗に主観的な判断や人間の判断が必要な場合：決定論的な部分はシナリオテストとして残し、それ以外はスモークテストに回します。
• 集中的に 2 回試してもテストが不安定な場合：再試行を追加せずに停止し、ログを保持して、制御できていない入力を報告します。