apidog-test-automation

テスト自動化、スイート、CI

前提条件：まず ../apidog-cli/SKILL.md を読んでください。安定版のエントリースキルとこのドメインスキルに矛盾がある場合は、現在の CLI ヘルプとこのスキルを信頼できる情報源として使用してください。複雑なシナリオのステップをモデリングする場合は ../apidog-test-scenario/SKILL.md を、単一エンドポイントのケースについては ../apidog-test-case/SKILL.md を読んでください。環境、変数、レポートの各コマンドは、現在の CLI ヘルプに従ってください。このスキルでは、実行の境界とよくある落とし穴に焦点を当てています。

引数を正確に確認するには、常に現在の CLI ヘルプを使用してください。実行前に、リソースの境界、空のスイートに関するリスク、ランナー／スケジュールタスクの制約、CI レポートの境界、実行後の診断順序を確認してください。エージェントのワークフローでは、実行結果を受け入れ確認として扱ってください。CI では、終了コード、レポートファイル、アップロード状況をゲートとして使用してください。

使用する場面

• テストスイートを作成、更新、実行する。
• 既存のテストシナリオを実行する。
• スケジュールタスクまたは CI 回帰テストを設定する。
• ランナーを管理する、またはランナーの状態を確認する。
• apidog run のパラメーター、レポーター、反復、変数の上書き、SSL、タイムアウト、レポートのアップロード、--carry-runtime-variables を扱う。

リソースの境界

ユーザーの意図	推奨リソース
単一エンドポイントのテストケース	test-case。apidog-test-case に切り替える
複数ステップのビジネスフロー	test-scenario。apidog-test-scenario に切り替える
複数のシナリオをまとめた回帰テスト	test-suite
スケジュール実行	scheduled-task
専用の実行マシン	runner
実行結果の表示	test-report。現在の CLI ヘルプに従って照会またはダウンロードする

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

test-suite、scheduled-task、runner、run の各パラメーターには、現在の CLI ヘルプを使用してください。run --help では、レポーター、out-dir、upload-report、iteration、変数の上書き、SSL、timeout、--carry-runtime-variables を確認できます。

test-suite create --name は空のスイートを作成します。クライアントには表示されますが、items: [] は回帰テストスイートとして使用できないことを意味します。ユーザーがプレースホルダーのスイートを明示的に求めている場合を除き、回帰テスト用または自動化用のスイートを作成するときは、--file を使用するか、後続の更新で項目を追加してから、get で items が空でないことを確認してください。

空でないスイートでは、cli-schema get test-suite-create によるフロントエンド互換の構造を使用してください。たとえば、testCases[].id の参照を含む STATIC_TEST_CASE を使用します。{ testScenarioId } のような古い省略記法は使用しないでください。スキーマ検証では意図的に拒否されます。

ランナーはチームレベルの実行リソースです。作成する前にチームと目的を確認してください。一般的によく使われる組み合わせは runnerType=GENERAL と serverType=SELF_HOSTED です。ランナーを軽量なプロジェクト内リソースとして扱わないでください。

作成と更新のルール

複雑なテストシナリオの作成や更新には apidog-test-scenario を使用してください。

空の例からスケジュールタスクを作成しないでください。スキーマ上の必須フィールドが name/cronExpression/runOn だけに見える場合でも、使用可能なタスクには通常、有効なランナーや TEST_SUITE の entityId などのコンテキストが必要です。runOn には、APP/TSHGR/OSHGR など、現在の CLI ヘルプ／スキーマでサポートされている値を使用してください。CLOUD のようなサポートされていない値は記述しないでください。

更新前には必ず元の構造を get し、ステップ、変数、シナリオ参照、スイートのメンバーを上書きしないようにしてください。

実行パラメーター

現在の引数を確認するには apidog run --help と、実行コマンド固有のヘルプを使用してください。CI ワークフローでは、環境、レポーター、out-dir、upload-report、iteration、変数の上書き、timeout、bigint の動作、--carry-runtime-variables が必要かどうかを明示的に確認してください。

推奨される最小限の CI コマンド形式：

apidog test-suite run <suiteId> --project <projectId> --environment <environmentId> --reporters cli,json,junit --upload-report

実行後

• ローカルレポート：--out-dir と --out-file を確認します。
• クラウドレポート：--upload-report を指定して実行した後にのみ表示されます。その後、最新の test-report list/get/download のヘルプを使用します。
• 失敗の診断：CLI の出力、JSON レポート、agentHints から確認を始め、該当するシナリオ、スイート、またはケースを特定します。
• --upload-report を指定しない場合、クラウドの test-report list にこのローカル実行は表示されません。
• CI では、--environment を明示的に指定します。トークンは CI のシークレット経由で設定し、決してコミットしないでください。

よくある問題への対処

症状	対処方法
作成後にシナリオのステップが正しくない	apidog-test-scenario に切り替え、作成後にステップが更新されたかどうかを確認します
スイートの実行結果が空	test-suite get を実行し、含まれているシナリオ／ケースを確認します
スイートの items: []	有効な回帰テストスイートではなく、空のプレースホルダーです
CI で環境が見つからない	現在の CLI ヘルプに従って environment list/get を使用し、environmentId を確認します
ランナーが利用できない	runner check を実行してから、runner get/list を確認します
レポートにステップの詳細がない	ローカル JSON、クラウドへのアップロード、ダウンロードした要約を区別します。必要に応じて apidog-cli-checkup に切り替えます