cypress-tap

cypress tap による Cypress の操作

cypress tap は、すでに実行中の cypress open セッションを操作します。これを使って、GUI を操作せずに spec を繰り返し実行し、レポーターとコマンドログを調べ、テスト対象のアプリを読み取れます。1 回限りのヘッドレスバッチには、代わりに cypress run を使ってください。

基本的なループ

npx cypress tap sessions                    # confirm a session; note pid if several exist
npx cypress tap status                      # baseline startedAt + spec
npx cypress tap run cypress/e2e/foo.cy.ts   # async — returns immediately
# poll status until passed|failed for your spec with a changed startedAt
npx cypress tap reporter
npx cypress tap reporter --test-id r3       # one test: log, network, stubs, error

run は非同期です。古い判定結果と新しい判定結果は、startedAt 以外のすべてのフィールドが一致する場合があります。また、選択中の spec に対するウォッチャーの再実行によって、対象のファイルを実行せずに startedAt が更新されることがあります。startedAt、spec、および終了状態を条件にしてください。running の状態を確認するまで待たないでください。短時間で終わる spec は、ポーリングの合間に完了する場合があります。コピーして貼り付けられるポーラーについては、session-lifecycle.md を参照してください。JSON フィールドのヘルパーについては、json-recipes.md を参照してください。

ポーリングループでは、プロジェクトで Cypress のバージョンが固定されている場合、npx cypress tap … より ./node_modules/.bin/cypress tap … を優先してください。

前提条件

• パッケージメタデータまたはロックファイルで、解決された Cypress が 15.21.0 以降であり、tap を含んでいることを確認してください。古いバージョンかどうかわからない場合は、確認のために tap --help を使わないでください。バージョンの下限を下回るプレリリースでは、ヘルプを表示する代わりにセッションの検出を試みることがあります。
• セッションでは Electron、Chrome、Chromium、または Edge を使う必要があります。Firefox と WebKit はサポートされていません。
• cypress open と、設定されている場合は baseUrl の開発サーバーが、すでに実行中である必要があります。
• cwd によって、Cypress バイナリと自動選択されるセッションの両方が決まります。対象のプロジェクトで古い Cypress のバージョンが固定されている場合は、互換性のあるチェックアウトから tap を実行し、毎回 --session <pid> を渡してください。

タスクに応じた参照先

• セッションの開始、選択、またはポーリング： session-lifecycle.md を参照してください。
• spec の実行または結果の確認： session-lifecycle.md と reading-results.md を参照してください。
• spec の作成または確認： recipes.md と reading-the-app.md を参照してください。
• 失敗の診断： recipes.md、reading-results.md、および reading-the-app.md を参照してください。
• コマンドの失敗、ハング、誤ったプロジェクト、または予期しない出力： troubleshooting.md を参照してください。
• --json の解析またはポーリングのスクリプト化： json-recipes.md を参照してください。
• 対話なしの単発バッチ： tap ではなく cypress run を使ってください。

現在のタスクに必要なリファレンスだけを読んでください。

基本コマンド

• sessions：アクセス可能なセッション、プロジェクトルート、テストタイプ、ブラウザーを表示します。JSON ではサポート状況とレンダラーの健全性も追加されます。
• status：ライフサイクルの段階、選択中の spec、実行 ID、件数、ビルドエラー、アクティブなピンを表示します。
• specs：セッションのテストタイプで実行可能な、プロジェクト相対の spec パスを表示します。
• run <spec>：spec の実行を開始し、すぐに戻ります。
• reporter：spec の概要とテスト ID を表示します。--test-id を指定すると、該当するテスト実行の詳細を表示します。
• command：ネットワークデータ、スナップショット、コンソールのプロパティを含む、コマンドログの 1 行を表示します。
• pin：コマンドのスナップショットにアプリのフレームを巻き戻します。
• dom、aria、inspect：安定した状態のアプリ、または現在ピン留めされているスナップショットを読み取ります。

すべてのコマンドで --session <pid>、--json、および --timeout <ms> を指定できます。対応が確認されたビルドでは、コマンド固有のフラグを確認するために npx cypress tap <command> --help を使ってください。ヘルプは実行中のセッションの仕様から生成されます。このスキルの内容とヘルプが異なる場合は、ヘルプに従ってください。

絶対に守る判定ルール

run はディスパッチを確認するものであり、実行を確認するものではありません。また、新しい実行が始まる前に返ります。この間、 status とアプリの読み取りでは、前回の実行のもっともらしい判定やページが返されることがあります。

明示的に実行する場合は、必ず次の手順に従ってください。

1. 現在の startedAt を読み取ります。
2. spec を1つだけディスパッチします。
3. status --json の応答を一度に1つずつポーリングします。
4. 期待する spec に対する passed または failed のみを受け入れます。また、startedAt が空でなく、かつ変更されている必要があります。startedAt が null になるのは、そのセッションでその spec の実行が一度も開始されていない場合のみです。つまり、初回選択時のビルド失敗です。再実行時やウォッチャーによる再ビルド時にビルドが失敗した場合も、startedAt は更新されるため、通常の手順に従います。null のフォールバック（観測可能なベースラインの変化、または直前に観測された loading／running）は、初回選択時に限って使用します。
5. ループに上限を設け、一致する新しい判定が得られなければ失敗とします。

アクティブな spec を保存すると、ウォッチャーが自動実行を開始します。編集後は、その実行を利用するか、ベースラインを取得して別の実行をディスパッチする前に完了するまで待ってください。意図的に2つの実行を同時に進行させてはいけません。

status 呼び出しが成功しても、一時的に空または部分的なペイロードが返されることがあります。フィールドが欠けている場合は、状態が変化したと見なさず、「待機を続ける」として扱ってください。status の終了コードが0以外の場合は、部分的な読み取りではなくコマンドの失敗です。ポーリングを停止して、その失敗を報告してください。

判定は passed と failed のみです。ビルド失敗は failed となり、テストがまだ存在しない場合でも、診断情報は status.error に含まれます。この診断情報を持つのは status だけです。reporter では、ビルド失敗は空の spec として表示されます。

正確性に関する重要なルール

1. 意図したセッションを対象にします。 複数のセッションがある場合、または自動選択が不自然な動作をする場合は、sessions を確認し、すべての呼び出しで --session <pid> を指定してください。自動選択では、別のプロジェクトや応答しないセッションが選ばれることがあります。E2e テストとコンポーネントテストでは別々のセッションを使用します。projectRoot を共有していても、公開される specs の一覧は異なる場合があり、どのセッションが応答したかを示すのは status だけです。他のコマンドの出力には pid が含まれません。
2. バイナリの場所を維持します。 Cwd は、呼び出しごとの npx の解決先を制御します。プロジェクトが古いバージョンの Cypress に固定されている場合は、互換性のあるチェックアウトからコマンドを実行し、--session <pid> を指定してください。
3. 失敗したコマンドを解析しないでください。 JSON を解析する前に終了コードを確認してください。サポート対象ビルドでの失敗は通常 stderr を使用しますが、古いバージョンとの互換性に関する失敗では stdout が使われる場合があります。曖昧なセレクターは意図された例外で、終了コード 1 で終了し、stdout に一致項目を一覧表示します。
4. 互換性の確認時に、ディスパッチの stdout を破棄しないでください。 古いバージョンの Cypress では、Unknown command "tap" と使い方の説明が stdout に出力されることがあります。リダイレクトすると原因が見えなくなります。
5. 大きくなる可能性のある JSON はリダイレクトしてください。 reporter --test-id --json と command --json の出力は数百キロバイトになることがあります。ファイルに保存してから解析してください。
6. 不在と判断する前に、出力が切り詰められていないか確認してください。 dom と aria の出力には上限があります。(output truncated) が表示された場合は、セレクターを絞り込むか上限を引き上げてください。
7. 不在と判断する前に、ライブフレームの状態を確認してください。 最後に保留中またはスキップされたテストがあると、アプリの読み取りが終了コード 0 を返していても、実行が落ち着いた後のランナーが空のプレースホルダー上に残ることがあります。アプリ内の既知のアンカーを確認してください。フレームが空の場合は、最後の実際のコマンドのスナップショットをピン留めし、その状態を読み取ってください。
8. spec を編集または削除する前に結果を読み取ってください。 結果とスナップショットは Cypress アプリのメモリ内にあり、再実行、再起動、名前の変更、削除によって失われることがあります。
9. ピン留めを解除してください。 コマンドのスナップショットを確認した後は、pin --clear を実行してください。解除しないと、その後のアプリの読み取りも引き続き過去にピン留めした状態を示します。終了コードが 0 で cleared:false の結果は、人間向けの出力に FAILED TO CLEAR PIN と表示されていても、問題のない処理なしの結果です。
10. ライブ状態には適切な読み取りコマンドを使用してください。 現在のフォームコントロールの値には aria を使用してください。dom と inspect には初期 HTML の value 属性が表示されることがあり、inspect ではアクセシビリティの値が省略される場合があります。ライブリージョン、トースト、ステータス、ラベルの正確なテキストには dom を使用してください。aria では子孫要素のテキストが省略されることがあります。
11. 広範なセレクターのプローブは && ではなく ; で連結してください。 dom／aria／inspect では、一致件数が 0 の場合は終了コード 0、曖昧な場合は終了コード 1 で終了します。一致項目を列挙する広範なプローブは有用な結果です。&& を使うと、最初のセレクターが曖昧だった場合、その後のコマンドがすべて実行されません。
12. 合格判定だけでは、完全な検証にはなりません。 合格後、reporter --test-id の結果を読み取り、インターセプトの一致数、スタブの使用状況、そして確認したいリクエストがスタブ化されていることを確認してください。reading-results.md と json-recipes.md を参照してください。

出力契約

• 人間向けの出力は読みやすさを重視します。--json は解析用で、より多くのデータを含む場合があります。単発のデバッグでは、通常はデフォルトのレンダリングのほうが適しています。コードフレームがインラインで表示され、ネットワークイベントがログ順に挿入されます。
• 終了コード 0 は、目的が達成されたことを意味しません。 tap は Cypress を起動しません。セッションがない場合、終了コード 0 でも status は not connected となり、sessions は JSON ではなくガイダンスを表示します。セレクターが見つからない場合、specs が空の場合、未知の --session pid の場合も、終了コード 0 で終わることがあります。無出力ではなく、フィールドに基づいて分岐してください。
• status は、not connected を含む既知のライフサイクル段階では終了コード 0 で終わります。検出、互換性、未サポートのブラウザー、レンダラーの各エラーは終了コード 1 で終わり、標準出力がないこともあります。ポーラーでは、この非ゼロ終了コードを受けたら即座に失敗させてください。
• dom、aria、inspect では、選択された要素がちょうど1つ必要です。候補セレクターを示して、曖昧さがあると終了コード 1 で終わります。見つからなくても CLI の失敗ではありません。dom と inspect は found:false を返します。aria は、見つからない場合も、アクセシビリティノードを持たない要素の場合も、空のツリーを返します。
• エラーは安定したエラーコードを持たない文章です。メッセージのテキストではなく、終了ステータスに基づいて分岐してください。

パフォーマンスのデフォルト設定

• 行ごとに command を呼び出すより、reporter --test-id で一度に読み取る方法を優先してください。
• 最新の判定を取得し、ライブフレームの整合性を確認した後は、互いに独立したアプリの読み取りを並行して実行できます。
• 制限付きのステータスのポーリングに失敗した場合は、sessions で rendererResponsive: false を確認してください。--timeout を延長するのではなく、応答しなくなったレンダラーを再起動してください。

症状別の参照先

症状	参照先
ポーリングが停止する、または判定が自分のものか不明	session-lifecycle.md
ファイルを編集したが、何が再実行されたか不明	session-lifecycle.md（ファイルウォッチャー）
JSON キーが空、または推測が間違っていた	json-recipes.md
列／e 行／テスト ID の意味	reading-results.md
テスト数が想定される it の数と異なる	reading-results.md、recipes.md（コンポーネント）
失敗のトリアージ、またはピンの位置が違うように見える	recipes.md、reading-the-app.md
出力は問題なさそうなのに終了コードが 1	troubleshooting.md