apidog-test-scenario

テストシナリオのモデリング

前提条件：まず ../apidog-cli/SKILL.md を読んでください。安定版のエントリースキルとこのドメインスキルが矛盾する場合は、現在の CLI ヘルプとこのスキルを信頼できる情報源として使用してください。単一エンドポイントのケースについては ../apidog-test-case/SKILL.md を、実行、CI、レポートの範囲については ../apidog-test-automation/SKILL.md を読んでください。環境と変数に関するコマンドは、現在の CLI ヘルプに従ってください。

正確な引数を確認するには、常に現在の CLI ヘルプを使用してください。テストシナリオを作成または更新するときは、ステップの永続化の意味、インポートと参照の境界、変数の受け渡し、複雑なステップのフィールドに関するリスク、実行時の検証を重視してください。エージェントは、ローカルで更新を行う前に、インポート／参照コマンドと get --with-case-detail を優先して使用し、実際の構造を確認してください。

使用する場面

• テストシナリオを作成または更新する場合。
• ログイン -> リソース作成 -> クエリ -> アサーション -> クリーンアップなど、複数ステップからなる自動化フローを設計する場合。
• 条件、ループ、待機、スクリプト、データベース操作、外部プログラムなどのステップタイプをオーケストレーションする場合。
• 前処理／後処理、変数参照、変数抽出器、アサーションチェーンを扱う場合。
• シナリオの作成後に発生するシナリオステップのリンクエラー、空の変数、誤ったステップ順序、クライアントでの表示問題を診断する場合。

使用しない場面

• 単一エンドポイントのテストケース：apidog-test-case を使用してください。
• 既存のシナリオ、スイート、CI コマンドの実行のみ：apidog-test-automation を使用してください。
• レポートの閲覧のみ：現在の CLI ヘルプにある test-report を使用してください。実行とレポートの範囲については apidog-test-automation を使用してください。
• 環境、変数、データベース接続、その他の実行時コンテキストの設定のみ：現在の CLI ヘルプにある environment、variables、database-connection、および関連コマンドを使用してください。

基本的な境界

概念	CLI リソース	注記
API テストケース	test-case	1 つのエンドポイントに紐付くケース。単一エンドポイントの検証に適しています
テストシナリオ	test-scenario	複数ステップのワークフローオーケストレーション
テストスイート	test-suite	回帰テスト用のシナリオ／ケースのコレクション
環境	environment	baseUrl、変数、サービス設定を提供します
テストデータ	test-data	シナリオまたはケースの反復データソース

コマンドのエントリーポイント

test-scenario のパラメーターには、現在の CLI ヘルプを使用してください。import-steps と add-ref はトップレベルのコマンド一覧に表示されない場合がありますが、どちらも --help に対応しており、ステップのインポートやシナリオ参照の追加に使用できます。

重要な点：test-scenario create はメタデータのみを保存します。作成ペイロードに steps が含まれていても、そのステップは作成時には保存されません。正しい手順は、まずメタデータを作成し、次に get --with-case-detail を実行してから、import-steps、add-ref、または test-scenario update --file でステップを追加または変更することです。

一般的なインポートでは、高レベルのインポートコマンドを優先してください。既存のリソースをインポートする際に、複雑な HTTP バインディング構造を手書きしないでください。確認済みのエントリーポイントは次のとおりです。

apidog test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointIds> --sync manual
apidog test-scenario import-steps <scenarioId> --project <projectId> --source test-case --endpoint <endpointId> --ids <testCaseIds> --sync manual
apidog test-scenario import-steps <scenarioId> --project <projectId> --source test-scenario --from-scenario <sourceScenarioId> --step-ids <stepIds>
apidog test-scenario add-ref <scenarioId> --project <projectId> --scenario <sourceScenarioId>

意味上の境界：

• import-steps は、現在のシナリオにステップをコピー／インポートします。
• add-ref は、別のシナリオへの参照を追加します。ソースシナリオの内部ステップはコピーしません。
• --sync manual がデフォルトです。インポートしたステップにビジネスパラメーター、変数参照、アサーションが必要な場合に適しています。
• --sync auto はエンドポイント／テストケースのソースにのみ適用され、ステップがソースの API 定義または単一エンドポイントのケースと同期することを意味します。テストシナリオのソースでは自動同期はサポートされません。
• CLI コマンドは非対話型であり、ID がない場合にすべてのリソースを自動的に一覧表示することはありません。エンドポイント、ケース、シナリオ、またはステップの ID がない場合は、agentHints に従って、まず list/get を使用してください。

簡略化した作成でも、必須のメタデータをすべて含める必要がありますが、それでも空のシナリオが作成されます。ユーザーが明示的にプレースホルダーを求めている場合を除き、自動テストまたはシナリオの作成を空のシナリオのまま終えてはいけません。

標準的なモデリングの流れ

1. ビジネス目標を明確にします。どのフローを検証するのか、成功とは何か、失敗時にどのように後処理するのかを確認します。
2. プロジェクト、ブランチ、環境を確認します。
3. 関連するエンドポイント、ケース、環境変数、テストデータ、データベース接続、スクリプトを一覧にします。
4. AI ブランチまたはスプリントブランチでシナリオを作成する場合、シナリオ自体のみを編集するのであれば、参照先のエンドポイントやケースを選択する必要はありません。参照先のエンドポイント、単一エンドポイントのケース、または元のシナリオを変更する必要がある場合にのみ、リソースを選択します。
5. 類似するシナリオがある場合は、テンプレートとして test-scenario list/get で読み込みます。
6. JSON に変換する前に、自然言語でステップのグラフを設計します。フィールドを推測して記述しないでください。
7. test-scenario-create のスキーマを取得し、メタデータを作成します。
8. 作成後、test-scenario get --with-case-detail を実行して、構造全体を読み込みます。
9. 既存のリソースをインポートする場合は、import-steps または add-ref を優先します。複雑なバインディングフィールドを手作業で記述しないでください。
10. インポート後、再度 test-scenario get --with-case-detail を実行し、ステップが書き込まれていることと、HTTP ケース／詳細が正しく展開されることを確認します。
11. API 定義やテストケースをインポートした後、パラメーター、ヘッダー、本文、スクリプト変数がスキーマ上の例にすぎないか確認します。必要に応じて、test-scenario update --file で実際のビジネス値に更新します。
12. 詳細な編集を行う場合は、test-scenario-update のスキーマを取得し、完全な読み戻し構造を編集します。
13. cli-schema validate が成功したら、更新を行い、その後 test-scenario get --with-case-detail を実行して、steps が空でなく、構造的に正しいことを確認します。

test-scenario-update スキーマには、ステップ、前処理／後処理プロセッサー、アサーション、抽出子、列挙型のドキュメントが含まれます。プロセッサーを初めて記述する際は、まずスキーマを読み込んでください。フィールド名、列挙値、旧形式を推測しないでください。

ステップ設計のベストプラクティス

各ステップについて、次の内容を記述します。

stepName: what this step does
stepType: which step type to use
input: request, script, SQL, wait condition, or referenced variables
output: variables to extract
assertions: success criteria
onError: continue, stop, or cleanup behavior
cleanup: whether post-run cleanup is needed

複雑なフローでは、階層を使います。

Prepare data
Authenticate/login
Main business operation
Query and assert result
Verify side effects
Clean up resources

データの受け渡しと変数参照

• 作成前に、環境変数、グローバル変数、前のステップのリクエスト／レスポンス、反復データ、スクリプトの出力など、データソースを一覧にします。
• ステップ間のデータには、{{$.1.response.body.token}} や {{$.2.response.body.data.id}} など、Apidog に組み込まれた前のステップの結果参照を優先します。これらはシナリオ全体の自動実行時にのみ機能し、単一ステップの実行では解決できません。
• 同じ値を複数のモジュールで再利用する場合や、固定の名前が必要な場合は、その値を変数に抽出して {{token}} として参照します。
• ランダムな接尾辞、一時的な識別子、レスポンスに由来しない生成値は、pm.environment.set('runSuffix', suffix); のように環境変数にするのが適しています。
• スクリプトでは、前のステップの値に対して {{...}} を直接記述せず、pm.variables.get("$.1.response.body.token") を使用します。
• ステップ参照はステップ ID／番号に依存します。ステップを挿入、削除、並べ替えた後は、すべての {{$.step...}} 参照を再確認してください。
• レスポンスのパスが常に body.data.id だとは限りません。{{$.2.response.body.id}}、{{$.2.response.body.data.id}}、{{$.2.response.body.data[0].id}} など、実際のレスポンスパスを確認してください。
• 生成されるペイロード内の {{...}} プレースホルダーは、そのまま保持してください。エスケープ、分割、書き換えを行うと、実行時の置換に失敗します。
• 変数が空の場合は、まずシナリオ全体を実行したか、ステップ ID、JSONPath、レスポンスの形状、実行順序、選択した環境を確認してください。

更新時の安全性

• 既存のステップを編集する際は、必ず完全な get --with-case-detail の読み戻し結果を元に更新します。
• update は JSON Patch ではなく、配列の項目を ID でマージしません。
• 既存の構造を編集する際は、ステップとプロセッサーの安定した ID を維持します。
• 既存の HTTP／カスタム／ソケットステップでは、意図的に変更する場合を除き、読み戻し結果に含まれる内部のケースオブジェクトを維持します。
• 更新後、読み戻しを行い、シナリオを実行するか、必要に応じて対象を絞ったドライランを行います。

一般的な復旧方法

症状	対処方法
シナリオを作成したが、ステップがない	create のみを使用した場合は想定どおりです。import-steps、add-ref、または update --file でステップを追加してください
インポートしたステップでサンプル値が使用されている	インポート後に、ビジネスパラメーターを使ってシナリオを更新してください
変数が空になっている	全体実行、ステップ番号、レスポンスパス、抽出器、環境を確認してください
クライアントにステップが表示されない	get --with-case-detail を実行し、ステップが保存されていて空でないことを確認してください
レポートを実行または確認する必要がある	apidog-test-automation に切り替えてください