apidog-cli-checkup

CLI の使用状況確認とバージョンの確認

前提条件：まず ../apidog-cli/SKILL.md を読んでください。安定版のエントリースキルとこのスキルの内容が矛盾する場合は、現在の apidog <command> --help とこのスキルを正としてください。その後、リソースの種類に応じたドメインスキルを読んでください。

このスキルは、公開 CLI のトラブルシューティングを対象としており、内部 API や内部コードには依存しません。コマンド、プロジェクト、ブランチ、環境、リソース ID、レポートの場所、CLI バージョンを確認してから、ドメインスキルに戻ってリソース構造を修正することを目的としています。エージェントは、現在のヘルプ、スキーマ検証、get による読み戻し、agentHints で問題を解決してください。要約テキストだけを信頼しないでください。

使用するタイミング

• CLI は成功を返すものの、Apidog クライアントにリソースが表示されない、または不完全に表示される場合。
• 作成後に list/get でリソースが見つからない場合。
• テストケース、テストシナリオ、テストスイートの実行に失敗する場合。
• ローカルまたはクラウドのレポートが見つからない、またはステップの詳細がない場合。
• agentHints、ヘルプ、使用例、実際のコマンドの動作が矛盾する場合。
• パラメーターが不足している、またはコマンドが不明であるとユーザーやテスターが報告し、CLI のバージョン確認が必要な場合。

最初に確認する5項目

1. 元のコマンド、projectId、branch、resourceId、environmentId、ファイルパス、および --api-base-url が使われたかどうかを記録します。
2. apidog --version を実行してローカル CLI のバージョンを確認します。パラメーターが不足している場合は、更新が必要かどうかを確認します。
3. 対応する apidog <command> --help を実行します。古いドキュメントや記憶ではなく、現在の公開ヘルプを使用してください。
4. 対応する list/get コマンドでリソースを読み戻し、プロジェクト、ブランチ、モジュール、フォルダー、カテゴリを確認します。
5. 実行やレポートの問題では、ローカルレポートとクラウドレポートを区別します。--upload-report を指定していない場合、ローカル実行がクラウドのレポート一覧に含まれることは期待しないでください。

バージョンの確認

まずバージョンとコマンドのヘルプを確認します。

apidog --version
apidog import --help
apidog test-case category --help

必要な新しいパラメーターがヘルプにない場合は、まず CLI を更新します。

apidog update

非対話型環境または直接更新を確認済みの場合：

apidog update --yes

自動更新のプロンプトが診断の妨げになる場合は、シェル設定で毎日のチェックを無効にできます。手動の apidog update は無効になりません。

export APIDOG_CLI_DISABLE_UPDATE_CHECK=1

バージョン診断には、現在の apidog --version、which apidog などのコマンドパス、不足しているパラメーター名、および推奨する更新方法を含めてください。

ヘルプとヒントが矛盾する場合

• 公開ドキュメント、agentHints、過去の使用例、実際の動作が矛盾する場合は、現在の apidog <command> --help と実際のテストを優先してください。
• ヘルプで公開されていない非表示のエイリアスを積極的に推奨しないでください。
• success=false の場合、成功したかのような要約ではなく、実際の success フィールドと終了コードを信頼してください。
• ヒントが次の手順を示していても、そのパラメーターが存在しない場合は、CLI のヒントに関する問題として記録し、ヘルプに記載された公開の代替手段を使用してください。

クライアントにリソースが表示されない場合

まず、次の項目を確認してください。

• 正しいプロジェクトかどうか。
• --branch が正しいかどうか。
• リソースが AI ブランチにあり、クライアントでは別のブランチを表示していないかどうか。
• 想定されるモジュールまたはフォルダー。
• テストケースに有効な categoryId が指定されているかどうか。
• ネイティブ形式で2回目のインポートを行った場合、モジュールのインポート戦略によってリソースが新しいモジュールに配置されていないかどうか。

読み戻しに役立つコマンド：

apidog endpoint list --project <projectId> --branch <branchName>
apidog test-case list --project <projectId> --endpoint <endpointId> --branch <branchName>
apidog test-scenario get <scenarioId> --project <projectId> --branch <branchName> --with-case-detail

get/list でリソースを確認できるのにクライアントでは確認できない場合は、まずクライアントのフィルター、ブランチ、モジュール、フォルダー、カテゴリを確認してください。すぐにリソースを再作成しないでください。

テストケースの診断

• 作成前に、apidog test-case category --project <projectId> を実行して有効な categoryId を取得します。
• 現在の test-case category は --endpoint をサポートしていません。エンドポイントのケースを表示するには、test-case list --endpoint <endpointId> を使用してください。
• test-case get で構造を確認できても、それは保存されたことを示すだけです。requestBody、アサーション、抽出器、スクリプトが実行可能であることの証明にはなりません。
• 実行に失敗した場合は、環境、変数、リクエストボディ、前処理／後処理スクリプト、アサーション、レポートの詳細を確認してください。

テストシナリオの診断

• test-scenario create ではシナリオのメタデータのみが作成されます。複雑なステップには、後続の import-steps、add-ref、または update --file が必要です。
• 作成または更新後、test-scenario get --with-case-detail を実行し、ステップツリーと HTTP の詳細が正しく展開されることを確認します。
• ステップ間の変数が空の場合は、シナリオ全体の実行、ステップ番号、レスポンスパス、抽出器、選択した環境を確認します。
• test-case の構造を test-scenario のステップとして直接記述しないでください。

実行とレポートの診断

• --environment が指定されていない場合、サーバーはプロジェクトのデフォルト設定を使用することがあります。再現性のある診断には、環境を明示的に指定してください。
• ローカルレポートは --out-dir と --out-file で制御します。
• クラウドの test-report list/get/download で実行を確認できるのは、--upload-report を指定して実行した場合のみです。
• レポートにステップの詳細がない場合は、まずローカルの JSON とクラウドレポートを比較します。ローカルの詳細も欠落している場合は、実行対象とリソース構造を調べます。
• 副作用を伴うテストを、デフォルトで本番環境に対して実行しないでください。

よくある原因の切り分け

症状	対応
新しいパラメーターが認識されない	apidog --version、which apidog を確認し、必要であれば apidog update --yes で更新します
作成に成功したが、クライアントに表示されない	プロジェクト、ブランチ、モジュール、フォルダー、カテゴリ、クライアントのフィルターを確認します
テストケースがクライアントに表示されない	categoryId、エンドポイント、ブランチを確認し、test-case list --endpoint で読み戻します
シナリオのステップが表示されない	test-scenario get --with-case-detail を実行し、作成後にステップが書き込まれたことを確認します
クラウドレポートが見つからない	実行時に --upload-report が指定されていたことを確認します