mcpField
C
cypress-cloud-cli

cypress-cloud-cli

github.com/cypress-ioテスト・品質471.8k 回インストール5 日前に更新
リポジトリ

cypress-cloud-cli について

cypress-cloud-cli は、Cypress Cloud のデータを調査するためのコマンドラインスキルです。プロジェクト、実行、テスト試行、Test Replay の検索に加え、認証、キャッシュ、リクエスト制限への対処も扱います。

主な機能

  1. 01`cy-cloud` による Cypress Cloud の照会
  2. 02実行、spec、テスト、試行の確認
  3. 03Test Replay のタイムライン調査
  4. 04コマンドスキーマに基づく JSON の解析
  5. 05リプレイキャッシュとリクエスト制限の管理

活用シーン

  1. 01Cloud URL から実行やテストを特定
  2. 02テスト試行と失敗の詳細を確認
  3. 03テストのリプレイタイムラインを調査
  4. 04コマンドラインで Cloud の結果を調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cypress-io/ai-toolkit --skill cypress-cloud-cli

インストール後、Claude Code で/cypress-cloud-cliを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
diagnosis.md
investigation.md
replay-view.md
test-replay.md

詳細

Cypress Cloud CLI

Cypress Cloud を調査するには、cy-cloud を直接使用します。コマンドを実行して JSON を調べ、返されたデータに基づいて結論を報告してください。CLI で回答できる質問について、ユーザーを Cloud UI に誘導しないでください。

安全に開始する

公開されているバイナリを使用するには、Node.js 22.21.0 以降が必要です。

次の確認は、初回の使用時、環境が不明な場合、またはインストールや認証でエラーが発生した後にのみ実行してください。このセッションですでに cy-cloud が正常に動作している場合は、設定を再確認するために別のターンを費やさず、調査コマンドを直接実行してください。

node --version
cy-cloud status
cy-cloud --help

cy-cloud はすでにインストールされ、PATH から利用できるものとします。ユーザーの現在のワークスペースから実行してください。cloud-cli のソースリポジトリを探したり、クローンしたり、ビルドしたり、それに依存したりしないでください。コマンドを利用できない場合は、停止して不足している前提条件を報告してください。ユーザーは次の方法でインストールできます。

npm install -g @cypress/cloud

認証されていない場合は、ユーザーに認証方法を選んでもらってください。

cy-cloud login                 # interactive OAuth
cy-cloud login --token "$PAT"  # persist a Personal Access Token

CI または既存の環境では、CYPRESS_CLOUD_TOKEN が保存済みの認証情報より優先され、認証情報ファイルは書き込まれません。

トークンを表示、エコー、読み戻し、またはコミットしないでください。~/.config/cy-cloud/auth.json や cypress.env.json を調べず、cy-cloud status を使用してください。

組織では Cypress Cloud CLI 統合を有効にする必要があります。有効になっていないという応答が返された場合は、組織の管理者による対応が必要です。別の CLI コマンドでは解決できません。

推測せずに確認する

すべてのコマンドで、次を使用できます。

cy-cloud --help
cy-cloud <command> --help
cy-cloud <command> --schema

利用可能なコマンドについては cy-cloud --help を、コマンドごとの引数については各コマンドの --help を、応答の契約については --schema を正としてください。コマンド、フラグ、フィールドが不確かな場合は、クエリを組み立てる前にこれらを確認してください。このスキルに記載されたコマンド一覧を暗記しないでください。インストールされている CLI は、この手順より新しい場合も古い場合もあります。実際の応答も検証してください。run get は小数の duration を返すことがあり、スキーマでは整数と定義されていても、replay info.failedAt は小数のエポック値を返すことがあります。これらの値は数値として扱い、重要な場合はスキーマとの不一致を報告してください。データを破棄したり、丸めたりしないでください。

データ取得に成功したコマンドは、JSON を stdout に書き込みます。その JSON を直接解析してください。このスキルを実行するために JSON ツールをインストールしないでください。リプレイのダウンロード進捗は stderr に書き込まれるため、JSON を解析する前に stderr と stdout を結合しないでください。

cy-cloud replay timeline --testId <uuid> --attempt <failedAttemptNumber> 2>/dev/null

コマンドが失敗した場合は、stderr を抑制せずに再実行してください。引数の検証エラーは stdout に、コマンド実行エラーは stderr に出力されることがあります。どちらも終了ステータスは 1 です。

ローカルコマンド（status など）が成功しても、セキュリティサンドボックスによって Cloud へのデータ取得がブロックされることがあります。Cloud データ取得コマンドは、ネットワークアクセスを許可して実行してください。サンドボックスまたはネットワークによる拒否で取得に失敗した場合は、CLI、認証、または Cloud の問題と判断する前に、同じコマンドをより広いネットワーク権限で再試行してください。

リプレイのダウンロードデータはディスクにキャッシュされます。cy-cloud cache info（.location）で場所を確認し、そのディレクトリに書き込み可能で、セッション中も存在し続けるように Cloud コマンドを実行してください。キャッシュを永続化できない一時的なサンドボックスでは、再度リプレイデータがダウンロードされたり、キャッシュの検証に失敗したりします。通常はローカルで実行できるコマンドでも同様です。キャッシュをユーザーのプロジェクト内に移動しないでください。

Cloud API の呼び出しはユーザーごとにレート制限されています。慎重かつ計画的にリクエストしてください。URL や以前の応答にすでに含まれている識別子を再利用し、ID が分かっている場合は組織やプロジェクトの検索を省略し、質問への回答に必要な範囲を超えてページを取得しないでください。テストのリプレイを初めてダウンロードした後は、replay info と replay timeline はローカルキャッシュに対して実行されるため、この制限の対象にはなりません。そのため、これらの後続クエリは複数回実行できます。レート制限超過が報告された場合は、Cloud へのリクエストを停止して制限を報告してください。短い間隔で再試行しないでください。

識別子とページネーション

projectId には、Cloud URL にすでに含まれているプロジェクト識別子を使用します。プロジェクトや実行の検索、および実行に紐づく仕様／テストの一覧取得では、短いスラッグとプロジェクト UUID のどちらも使用できます。UUID をスラッグに置き換える目的だけで、組織やプロジェクトの検索を行わないでください。runNumber はプロジェクトごとの実行番号です。specId と testId は UUID です。試行番号は 1 から始まり、Cypress Cloud と一致します。

Cloud の一覧レスポンスには .pagination が含まれます。質問が最初のページに限定されていない場合は、追加のページをリクエストしてください。

タスクに応じた参照先

現在のタスクに必要な参照だけを読み込んでください。

  • 組織、プロジェクト、実行、仕様、テストを検索する場合、または Cloud URL を開く場合：
    investigation.md を読んでください。
  • 試行、フレーク、失敗時のスクリーンショットを調べる場合：
    investigation.md を読んでください。
  • Test Replay をクエリする場合： investigation.md と test-replay.md を読んでください。
  • テスト中のある時点でアプリ自体（DOM、ARIA、計算済みスタイル、ライブスクリーンショット）を調べる場合、またはどのコマンドが要素を変更したかを特定する場合： replay-view.md を読んでください。
  • 記録されたテストが失敗した理由を診断する場合： investigation.md、 test-replay.md、タイムラインだけでは症状を説明できない場合は replay-view.md、および diagnosis.md を読んでください。

キャッシュと一般的な復旧方法

cy-cloud cache info
cy-cloud cache cleanup
cy-cloud cache clear

通常のメンテナンスには cache cleanup を使用してください。リプレイの解決結果が古い、または破損しているように見える場合に限り、今後のリプレイのダウンロードを強制する cache clear を使用してください。コマンドのたびにリプレイが再ダウンロードされる場合、キャッシュディレクトリが永続化されていません。cache info で報告された場所に書き込み可能なサンドボックスで再試行してください。

よくある結果：

  • 予想されるフィールドがない：そのコマンドの --schema を確認してください。
  • JSON の解析に失敗する：標準エラー出力が標準出力にマージされていないことを確認してください。
  • サンドボックスからキャッシュの検証エラーまたは書き込みエラーが発生する：キャッシュディレクトリが書き込み可能で永続化されるようにして再試行してください。キャッシュをプロジェクトにコピーしないでください。
  • cy-cloud version が "status": "Unknown" を返しても、それだけでインストールが壊れている、または古くなっていることを意味するわけではありません。version と latestVersion を比較し、これらの値または明示的な互換性エラーが示す場合にのみアップグレードしてください。
  • レート制限を超過した：Cloud を利用するリクエストを停止し、制限を報告してください。ループで再試行しないでください。ダウンロードが成功した後のキャッシュ済みリプレイクエリは対象外です。
  • リプレイ固有のエラー：test-replay.md を読んでください。

コメント

Markdown 対応