apidog-test-case

API テストケース

前提条件：まず ../apidog-cli/SKILL.md を読んでください。安定版のエントリースキルとこのドメインスキルが競合する場合は、現在の CLI ヘルプとこのスキルを信頼できる情報源として使用してください。API 定義については、エンドポイント、スキーマ、フォルダー、および関連するコマンドに関する現在の CLI ヘルプに従ってください。複数ステップのフローについては、../apidog-test-scenario/SKILL.md を読んでください。

正確な引数は常に現在の CLI ヘルプで確認してください。API テストケースを作成または更新する際は、categoryId の表示に関するリスク、テストケースとテストシナリオの境界、requestBody／プロセッサー／アサーション／抽出器の構造、および実行時の検証に特に注意してください。エージェントは書き込む前に cli-schema validate でペイロードを検証し、その後 get を使って保存された構造を確認する必要があります。

使用する場合

• 単一のエンドポイントに対して自動テストケースを作成する場合。
• テストステップ、アサーション、変数抽出器、前処理／後処理を更新する場合。
• エンドポイント配下のテストケースを一覧表示する場合。
• caseId、endpointId、または categoryId を指定して API テストケースを実行する場合。
• テストデータセットを作成または管理する場合。
• クライアントでテストステップが表示されない、アサーションが機能しない、抽出された変数が空になるなどの問題を診断する場合。

使用しない場合

• 複数エンドポイントにまたがるワークフローのオーケストレーションやシナリオのモデリング：apidog-test-scenario を使用してください。
• 既存のシナリオ、スイート、または CI コマンドの実行のみを行う場合：apidog-test-automation を使用してください。
• API 定義、リクエストパラメーター、またはレスポンスモデルの編集のみを行う場合：現在の CLI ヘルプにあるエンドポイント／スキーマコマンドを使用してください。
• テストレポートの閲覧のみを行う場合：現在の CLI ヘルプにある test-report を使用してください。実行とレポートの範囲については、apidog-test-automation を使用してください。

基本概念

概念	CLI リソース	説明
API テストケース	test-case	エンドポイントに紐づくテストデータとステップ
テストカテゴリ	test-case category	テストケースのカテゴリ。ケースを作成する前に、有効な categoryId の取得に使用します
テストデータセット	test-data	繰り返し実行時のデータソース
API 定義	endpoint	ケースの依存先であり、ケース自体ではありません
テストシナリオ	test-scenario	異なる境界を持つ複数ステップのワークフローオーケストレーション

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

test-case、test-data、および apidog run --test-case については、現在の CLI ヘルプを使用してください。categoryId の取得には test-case category を使用します。現在の test-case category は --endpoint に対応していません。エンドポイント配下のケースを表示するには、test-case list --endpoint <endpointId> を使用してください。apidog run --test-case が受け付けるのは caseId のみです。

単一エンドポイントのケースをテストシナリオにインポートする場合、このスキル内でシナリオステップを手書きしないでください。apidog-test-scenario に切り替えて、次を使用してください。

apidog test-scenario import-steps <scenarioId> --project <projectId> --source test-case --endpoint <endpointId> --ids <testCaseIds> --sync manual

標準的な作成フロー

1. プロジェクトとブランチを確認します。
2. apidog endpoint list/get でエンドポイントを特定します。
3. apidog test-case category --project <projectId> を実行して有効な categoryId を取得します。既存のエンドポイントケースを確認するには、apidog test-case list --project <projectId> --endpoint <endpointId> を実行します。
4. 類似のケースがある場合は、list を使用してから、そのケースを 1 つ get してテンプレートにします。
5. test-case-create スキーマを取得して検証します。
6. 完全な JSON ペイロードを作成します。name／endpointId のみを含む空のひな形は作成しないでください。
7. 作成後、すぐに test-case get <caseId> を実行し、保存されたバックエンド構造を確認します。
8. ローカルの JSON レポートを使って一度実行し、requestBody、プロセッサー、アサーション、スクリプトがランナーで動作することを確認します。
9. レポートをアップロードする場合は、現在の CLI ヘルプに従って test-report を使用します。レポートの詳細が不足している場合は、ローカル／クラウドのレポートの範囲について apidog-test-automation を使用してください。

categoryId はクライアントでの表示に必要な重要フィールドであり、通常の任意カテゴリではありません。無効な categoryId を指定すると、CLI の get/list ではケースが表示されても、クライアントのカテゴリ一覧には表示されない、または使用できない場合があります。ケースを作成する前に、必ず test-case category で有効な ID を取得してください。

標準的な更新フロー

更新する前に、必ず元の構造を get で取得し、その完全な構造を変更してください。その後、既存のステップ、アサーション、変数抽出器、プロセッサーが失われないよう、test-case-update スキーマに照らして検証してください。update は JSON Patch ではなく、配列要素を ID でマージすることもありません。

test-case-create および test-case-update スキーマには、プロセッサー、アサーション、抽出器、列挙値に関するドキュメントが含まれています。初めてプロセッサーを記述するときは、まずスキーマを読んでください。フィールド名、列挙値、レガシー形式を推測してはいけません。現在の test-case-update は、プロセッサーの data を type に基づいて検証します。たとえば、extractor は variableType/subject/shareScope を、assertion は subject/comparison を検証し、delay では数値の data が必要です。

test-case get は、method に空文字列を返すことがあります。これは、クライアントが HTTP メソッドを誤って表示しているという意味ではありません。通常、クライアントはバインドされたエンドポイントから HTTP メソッドを表示します。現在の test-case-update スキーマは、この読み戻し構造を受け入れます。ユーザーがバインドされたエンドポイントまたはリクエストメソッドの変更を明示的に依頼しない限り、メソッドを推測して書き換えないでください。

テストステップの表示ルール

ユーザーがクライアントでの表示を重視する場合は、以下をすべて確認してください。

1. 作成または更新後に test-case get を実行します。
2. ステップ、アサーション、抽出器、プロセッサーがバックエンドに保存されていることを確認します。
3. フィールドが空の配列や空のオブジェクトになっていないこと、誤った階層に書き込まれていないことを確認します。
4. CLI が成功を返してもクライアントにデータが表示されない場合は、apidog-cli-checkup に切り替え、まずプロジェクト、ブランチ、エンドポイント、categoryId、読み戻し構造を確認します。

コンテンツとプロセッサーの構造

• requestBody.data は文字列である必要があります。JSON Body をオブジェクトとして記述しないでください。
• 複数行の JSON Body、pre-scripts、post-scripts は \n で整形してください。これにより、実行時の動作を変えずにクライアントで読みやすくなります。
• preProcessors と postProcessors はフラットな構造 { id, type, data, defaultEnable, enable } を使用します。レガシーのネスト構造 { type, config } は使用しないでください。
• プロセッサーには、特に assertion、extractor、customScript で安定した id 値を使用してください。ID がなくても検証は通る場合がありますが、ランナーやクライアントのパーサーで問題が起きることがあります。
• グローバル変数を抽出する場合は、data.variableType: "globals" を使用します。スコープが必要な場合は、data.shareScope: "PROJECT" を優先してください。TEAM はチーム全体に適用され、有料機能に依存する場合があります。明示的に依頼されない限り、デフォルトで使用しないでください。
• 書き込み前に必ず cli-schema validate を実行し、書き込み後に test-case get を実行してください。

例：

{
  "requestBody": {
    "type": "application/json",
    "data": "{\n  \"name\": \"Demo\",\n  \"description\": \"Readable in client\"\n}"
  },
  "postProcessors": [
    {
      "id": "postProcessors.0.customScript",
      "type": "customScript",
      "data": "pm.test('returns id', function () {\n  var body = pm.response.json();\n  pm.expect(body.data.id).to.exist;\n});",
      "defaultEnable": true,
      "enable": true
    },
    {
      "id": "postProcessors.1.extractor",
      "type": "extractor",
      "data": {
        "variableName": "project_pet_name",
        "variableType": "globals",
        "shareScope": "PROJECT",
        "subject": "responseJson",
        "expression": "$.name"
      },
      "defaultEnable": true,
      "enable": true
    }
  ]
}

実行と検証

• 実行時の動作が重要な場合は、書き込み後にケースを実行してください。
• 再現性を確保するため、明示的に --environment を指定してください。
• ランナーの動作を診断する場合は、ローカル JSON レポートを生成してください。
• クライアントでの表示が成功したことを、実行が成功したことと同一視しないでください。必要に応じて、保存された構造と実行結果の両方を検証してください。

よくある問題からの復旧

症状	対処法
ケースは作成されたが、クライアントに表示されない	プロジェクト、ブランチ、エンドポイント、有効な categoryId を確認します
更新後にステップがなくなった	get の完全な出力から再構築します。update は配列をパッチしません
アサーションが実行されない	プロセッサーの type、data、enable、生成されたレポートを確認します
抽出した変数が空である	subject、JSONPath、レスポンスの形状、variableType、shareScope を確認します
新しい CLI パラメーターが見つからない	apidog-cli-checkup を使用してバージョンとヘルプを確認します