cypress-automation

TypeScript による本番品質の Cypress テストスイートです。防止できる失敗：Cypress コマンドが同期的に実行されるかのように書かれたテスト（`cy.get()` を変数に代入する、`await cy.click()` を使うなど）や、ネットワークエイリアスの代わりに `cy.wait(3000)` を使って待機するために不安定になるテストです。このスキルでは、基本的な考え方（コマンドキュー、再試行可能性）、プロジェクト構成、カスタムコマンド、`cy.intercept` によるネットワーク制御、コンポーネントテスト、`cy.origin` によるクロスオリジン認証、Cypress Cloud と CI の統合について説明します。

目的別の案内

必要な作業	参照先
E2E の spec を作成する（読み込み、インターセプト、アサーション）	基本原則 + references/intercept-patterns.md
型付きカスタムコマンド／cy.session によるログインを追加する	カスタムコマンド + references/config-and-commands.md
単一のコンポーネントをマウントしてテストする	コンポーネントテスト + references/component-and-fixtures.md
cypress.config.ts／プロジェクトのレイアウトを作成する	プロジェクト構成 + references/config-and-commands.md
API のスタブ、スパイ、エラーのシミュレーション、ポーリングを行う	cy.intercept パターン + references/intercept-patterns.md
CI で実行する／Cypress Cloud で並列化する	CI 統合 + references/ci-recipes.md
SSO／OAuth リダイレクトに対応する	クロスオリジンフロー + references/intercept-patterns.md

---

確認事項

まず .agents/qa-project-context.md を確認してください。ファイルが存在する場合はその内容を使い、すでに回答されている質問はスキップします。

1. コンポーネントテスト、E2E、または両方ですか？ コンポーネントテストでは個々のコンポーネントを分離してマウントし、E2E ではブラウザーを通じてアプリ全体をテストします。ほとんどのプロジェクトでは両方が必要です。コンポーネントテストには、フレームワーク固有のマウント機能（React、Vue、Angular、Svelte）が必要です。
2. Cypress Cloud を使いますか？ Cloud では、並列化、フレーク検出、分析、Test Replay、AI アドオンを利用できます。チームで使用する場合は、projectId と記録キーを設定してください。使用しない場合は、Cloud なしでローカルまたは CI 上で実行できます。
3. TypeScript を使いますか？ 強く推奨されます。ここでのデフォルトでもあります。Cypress は TypeScript をネイティブにサポートします。すべての例で TypeScript を使用しています。
4. フレームワークとバンドラーは何ですか？ React + Vite、Next.js + Webpack、Vue + Vite、Angular などです。コンポーネントテストの設定はこれらによって異なります。
5. クロスオリジン認証はありますか？ ログイン時に別のドメイン（SSO、OAuth プロバイダー）へリダイレクトする場合は、cy.origin が必要です。ログインコマンドをその用途に合わせて構築できるよう、事前に確認してください。
6. 既存のテストスイートがありますか、それとも新規に始めますか？ 移行する場合は、一度にすべてを書き換えるのではなく、不安定さが最も大きいテストや最も重要なテストから始めてください（test-migration を参照）。

---

基本原則

1. コマンドはすぐに実行されず、キューに追加される

最も重要な概念です。Cypress コマンド（cy.get、cy.click、cy.type）は呼び出された時点では実行されず、キューに追加されて非同期に順番に実行されます。Cypress コマンドでは async/await を使えず、戻り値を変数に格納することもできません。

// WRONG -- this looks synchronous but is not
const button = cy.get('[data-testid="submit"]'); // button is a Chainable, not an element
button.click(); // works only by accident, via chaining

// CORRECT -- chain commands; use .then() when you need a value
cy.get('[data-testid="submit"]').click();

cy.get('[data-testid="price"]').invoke('text').then((text) => {
  const price = parseFloat(text.replace('$', ''));
  expect(price).to.be.greaterThan(0);
});

2. 再試行可能性は組み込み（クエリのみ。アクションは対象外）

Cypress は、クエリ（cy.get、cy.find、cy.contains）とアサーションを、成功するかタイムアウトするまで自動的に再試行します。アクション（cy.click、cy.type、cy.select）は再試行しません。

• cy.get('.loading').should('not.exist') はインジケーターが消えるまで待機します
• cy.get('.item').should('have.length', 5) は 5 個の項目が表示されるまで待機します
• cy.click() は一度だけ実行されます。要素が操作可能でない場合は失敗します

3. cy.intercept によるネットワーク制御

cy.intercept はネットワーク層で HTTP リクエストをインターセプトし、レスポンスのスタブ、リクエストの完了待ち、リクエスト本文へのアサーションを可能にします。これを習得することが、不安定なテストと安定したテストを分ける鍵です。固定の cy.wait(ms) ではなく、必ずネットワークエイリアスまたは DOM アサーションを使って待機してください。

4. 分離：各テストはクリーンな状態から開始する

各 it() は新しいブラウザー状態で実行されます。Cypress はデフォルトで、テスト間に Cookie、localStorage、sessionStorage を消去します。テストが他のテストの状態や実行順序に依存しないようにしてください。共通のセットアップには beforeEach を使い、テスト間の依存関係を作らないでください。

5. テストセレクター用のデータ属性

data-testid、data-cy、または data-test を使用します。これらは CSS のリファクタリング、クラス名の変更、ローカライズの影響を受けません。優先する属性は cypress.config.ts で設定します。

---

プロジェクト構成と設定

標準的な構成では、e2e/、component/、fixtures/、support/ を分け、ルートにある cypress.config.ts で両方のランナーを設定します。主な設定項目は、環境変数から取得する baseUrl（CI 用にハードコードしないでください）、明示的なビューポート、CI 用の retries.runMode: 2、および component.devServer に指定するフレームワークとバンドラーの組み合わせです。コンポーネントのスペックは cypress/component/**/*.cy.tsx に配置します。

ディレクトリツリー、完全な cypress.config.ts、および tsconfig.json への追加項目については、references/config-and-commands.md を参照してください。

---

カスタムコマンド

カスタムコマンドを使うと、繰り返し行う操作を、すっきりとした型付き API にまとめられます。よく使われるコマンドには、（UI ではなく cy.session と API を使う）login、getByTestId セレクターのショートカット、shouldShowToast などのアサーションヘルパーがあります。オートコンプリートとコンパイル時チェックを有効にするには、JSDoc の @example を付けて cypress/support/index.d.ts に宣言します（declare namespace Cypress { interface Chainable { ... } }）。

cy.session には validate() コールバックが必要です。 cy.session は Cookie、localStorage、sessionStorage を自動的にキャッシュしますが、validate() がないと、キャッシュされたセッションは再検証されません。期限切れや古くなったトークンが、無効なセッションを気付かれないまま再利用します。認証が必要なエンドポイントにアクセスする validate() を必ず渡してください（例：cy.request('/api/me').its('status').should('eq', 200)）。

再試行可能な検索には Cypress.Commands.addQuery() を使い、コールバックはアロー関数ではない function () {} にする必要があります。Cypress はコマンドのタイムアウトを適用するために this をバインドするため、アロー関数を使うと再試行可能な動作が気付かれないまま壊れます。（インターセプトハンドラーは逆で、this を使わないため (req) => {} で問題ありません。）

完全なコマンド定義、validate() コールバック、addQuery の例、TypeScript の宣言については、references/config-and-commands.md を参照してください。

---

cy.intercept のパターン

cy.intercept は、ネットワーク制御のあらゆる用途に対応します。

• レスポンスをスタブする — { statusCode, body } で固定データを返し、その後 cy.wait('@alias') を実行します。
• スタブせずにスパイする — cy.intercept('POST', '/api/orders').as('createOrder') を設定し、その後 interception.request.body と interception.response?.statusCode をアサートします。
• 条件付きレスポンス — callCount を使ってクロージャを制御し、ポーリング（202 → 200）をシミュレートします。ここではハンドラーにアロー関数 (req) => { ... } を使います。
• ネットワークエラー — { statusCode: 500 }、{ forceNetworkError: true }、または遅いレスポンス用の req.reply({ delay }) を使います。
• 実際のレスポンスを変更する — req.continue((res) => { ...; res.send(); }) を使います。
• フィクスチャを使う — { fixture: 'api-responses/checkout-success.json' } を使います。

リクエストを発生させる操作の前にインターセプトを登録してください。そうしないと、エイリアスが一致しません。

実行可能な各パターンのコードと、クロスオリジンのフローについては、references/intercept-patterns.md を参照してください。

---

コンポーネントテスト

コンポーネントテストでは、アプリ全体を実行せずに、実際のブラウザーで単一のコンポーネントをマウントします。E2E より高速で、ユニットテストより視覚的なフィードバックが得られます。cy.mount(<Component .../>) を使い、コールバックには cy.stub()／cy.spy() を渡して、E2E で使うものと同じ cy.contains／cy.get のチェーンでアサートします。コンポーネントテストでは cy.visit を使わないでください。Vue の場合は cy.mount(Component, { props: { ... } }) を使います。

React の ProductCard コンポーネントテストスイート全体については、references/component-and-fixtures.md を参照してください。

---

フィクスチャを使ったデータ駆動テスト

データの取得元に応じて、次の3つの方法があります。

• 静的フィクスチャ — 変更頻度の低い JSON には cy.fixture('users').as('users') を使います。beforeEach(function () { ... }) 内で this.users を使って読み込みます。
• cy.task を使った動的データ — ブラウザー外で実行する必要のある API 呼び出しや DB シーディングには、setupNodeEvents に Node 側のタスクを登録します（タスク本体は Node で実行されるため、そこでの fetch は Cypress API ではなく、Node のグローバル fetch です）。
• 環境固有の設定 — setupNodeEvents で環境ごとの baseUrl マップをマージし、--env ENVIRONMENT=... で選択します。

フィクスチャ、cy.task を使ったシーディング、環境設定のコードについては、references/component-and-fixtures.md を参照してください。

---

クロスオリジンフロー

別ドメインへの正規のリダイレクト（SSO、OAuth プロバイダー、別の認証ホストなど）では、別のオリジンで実行するコマンドを cy.origin で囲みます。これは、以前の回避策である chromeWebSecurity: false／experimentalSessionAndOrigin に代わるものです。リダイレクトへの対処としてウェブセキュリティを無効にしないでください。これは、cy.intercept でスタブし、内部にアクセスしないサードパーティの決済 iframe（Stripe／PayPal）とは異なります。

cy.origin の例については、references/intercept-patterns.md（クロスオリジンフロー）を参照してください。

---

CI 連携

アクションのバージョン： cypress-io/github-action@v7 に固定してください（最新は 7.2.0、2026年5月）。v7 は Node 24 で実行される現行のメジャーバージョンです。Node 20 のランナーでは、レガシーブランチの @v6 のみを使用してください。

Cypress／Node のサポート： 現行の Cypress 15.x は、Node 20、22、24 をサポートしています（Node 18 と 23 のサポートは終了しました）。Node 20 のサポート終了は、Cypress 15 で実施されたものではなく、Node 20 の EOL（2026-04-30）に伴う今後の Cypress 16／action-v7.2 の検討事項です。

• Cypress Cloud を使用する場合： projectId を設定し、npx cypress run --record --key $CYPRESS_RECORD_KEY を実行します。コンテナのマトリックス（fail-fast: false）で並列化し、不安定なテストの検出、Test Replay、分析を行います。
• Cloud を使用しない場合： build／start／wait-on とともに cypress-io/github-action@v7 を使用し、失敗時には cypress/screenshots と cypress/videos をアーティファクトとしてアップロードします。

完全な GitHub Actions ワークフローについては、references/ci-recipes.md を参照してください。

Cypress AI（有料の Cloud アドオン、2026年に GA） には、Auto Heal（セレクターの自己修復）、AI Test Generation、AI Bug Triage が含まれます。現在 GA となり、知っておく価値のある機能として、cy.prompt（英語からテストを作成し、実行時に自己修復）と Cloud MCP（2026年5月に GA、すべての Cloud プランで無料）があります。Cloud MCP は、記録された実行のエラー、スタックトレース、Test Replay のリンクを AI アシスタントに提供する MCP サーバーです。これは test-reliability（セレクターの修復）、ai-bug-triage（失敗のクラスタリング）、ai-test-generation（テスト作成）と機能が重複します。チームがすでに Cypress Cloud を利用している場合、同等の機能を構築するよりアドオンを購入するほうが安く済む可能性があります。フレームワークの選定時に検討してください。

---

アンチパターン

1. 同期のための cy.wait(milliseconds)

// BAD
cy.get('[data-testid="submit"]').click();
cy.wait(3000);

// GOOD -- wait for network
cy.intercept('POST', '/api/submit').as('submit');
cy.get('[data-testid="submit"]').click();
cy.wait('@submit');

スロットル／デバウンスのテストでのみ使用できます。それ以外はすべて、ネットワークエイリアスまたは DOM アサーションを待機します。

2. DOM の状態に基づく条件付きテスト

$body.find(selector).length > 0 を確認して条件付きで処理しないでください。条件付き要素を制御する API をスタブし、状態を確定的に制御します。

3. データ属性より CSS セレクターを優先する

cy.get('.btn.btn-primary > span') は、CSS のリファクタリングのたびに壊れます。cy.getByTestId('submit') または cy.contains('button', 'Place Order') を使ってください。

4. テスト間で状態を共有する

ある it() で設定したモジュールレベルの let orderId を別の it() で読み込むと、実行順に依存し、並列実行に安全でないテストになります。各テストは beforeEach で cy.request または cy.task を使い、独自のデータをセットアップしてください。

5. サードパーティの iframe をテストする

Stripe／PayPal の iframe 内部にアクセスしないでください。cy.intercept で決済 API をモックし、自分たちの UI をアサートしてください。

6. ログインに cy.session() を使用しない（または validate() を省略する）

すべてのテストで UI ログインを行うと、時間がかかり、不安定になります。cy.session を使って API 経由で一度認証し、キャッシュしてください。その際、期限切れのトークンで無効なセッションがそのまま再利用されないよう、validate() コールバックを指定します。

7. addQuery でのアロー関数

addQuery('name', (arg) => { ... }) のように記述したカスタムクエリでは、Cypress が this を必要とするため、リトライのタイムアウトが暗黙のうちに失われます。function (arg) { ... } を使用してください。

8. CI ですべてのテストを逐次実行する

テストスイートの実行時間が 5 分を超えたら並列化してください。Cypress Cloud、cypress-split、または CI マトリックスを使った手動のシャーディングを利用できます。

---

失敗時の症状と対処法

症状	考えられる原因	対処法
element is detached from the DOM	再レンダリング後に取得済みの要素を再利用した	古い参照を保持するのではなく、.should／.then の内側で再取得する
cy.intercept に一致しない／エイリアスが解決されない	メソッドまたは glob が誤っている、あるいはアクション後にインターセプトを登録した	トリガーとなるコマンドより前にインターセプトを登録し、メソッドと URL の glob を確認する
リダイレクト時に cross origin エラーが発生する	ログインまたはフローが別のドメインに移動する	別オリジンでのコマンドを cy.origin で囲み、chromeWebSecurity は無効にしない
セッションが再利用されたが、ユーザーはログアウト状態になっている	cy.session に validate() がなく、トークンの有効期限が切れた	認証済みエンドポイントにアクセスする validate() コールバックを追加する
カスタムクエリがタイムアウトせず、無限にリトライする	addQuery のコールバックがアロー関数である	Cypress が this をバインドできるよう、function () {} に変換する

---

検証

完了とする前に、テストスイートが実行できることを確認してください。

• npx cypress verify — Cypress バイナリがインストールされ、実行可能であることを確認します。
• npx cypress run --spec "cypress/e2e/<file>.cy.ts" — 終了コード 0 で終了する必要があります（ヘッドレス、CI モード）。
• npx cypress run --component --spec "cypress/component/<File>.cy.tsx" — コンポーネントの spec が終了コード 0 で終了します。
• npx tsc --noEmit — index.d.ts のカスタムコマンド宣言がテストファイルに対してコンパイルされます。

---

完了条件

• cypress.config.ts が存在し、環境変数から取得する baseUrl（CI でハードコードされた localhost を使用しない）と、明示的な viewportWidth／viewportHeight が設定されている。npx cypress verify が成功する。
• カスタムコマンドが cypress/support/commands.ts に切り出され、TypeScript 宣言が cypress/support/index.d.ts に記述されている。npx tsc --noEmit が終了コード 0 で終了する。
• login コマンドが validate() コールバック付きで cy.session を使用している。
• スイート内の同期処理に cy.wait(<number>) を使用していない（grep -rn "cy.wait([0-9]" cypress/ の結果が、ドキュメント化されたスロットル／デバウンスのケースを除いて空である）。
• コンポーネントの spec が cypress/component/**/*.cy.tsx にあり、npx cypress run --component が終了コード 0 で終了する。
• E2E の spec が CI で成功する（npx cypress run が終了コード 0 で終了する）。並列実行の場合は Cypress Cloud に記録された実行結果があり、そうでない場合は失敗時にローカルの動画／スクリーンショットの成果物がアップロードされる。

参照ファイル（references/ 内）

• config-and-commands.md — プロジェクトのディレクトリツリー、cypress.config.ts 全体、カスタムコマンド（cy.session + validate()、アロー関数ではない addQuery）と TypeScript 宣言。
• intercept-patterns.md — cy.intercept のすべてのレシピ（スタブ、スパイ、条件付き／ポーリング、エラーのシミュレーション、レスポンスの変更、fixture を使った方法）と、cy.origin を使ったクロスオリジンフロー。
• component-and-fixtures.md — React コンポーネントのテストスイートと、データ駆動テスト（静的 fixture、cy.task によるシード、環境固有の設定）。
• ci-recipes.md — Cypress Cloud を使用する場合と使用しない場合の、並列化と成果物のアップロードに対応した GitHub Actions ワークフロー（@v7）。

関連スキル

• playwright-automation — テストスイートが Cypress ではなく Playwright を使用している場合は、このスキルの代わりにこちらを使用してください。E2E の目標は同じですが、ランナーと API が異なります。
• test-reliability — 実行時のテストごとのフレーク修復、自己修復ロケーター、隔離については、こちらを参照してください。このスキルは安定したテストを作成し、こちらのスキルは失敗したテストを修復します。
• selector-drift-recovery — UI のリファクタリングや再設計後に壊れたセレクターを一括で再生成します。このスキルはテストの作成向けであり、大規模な修復向けではありません。
• test-migration — Selenium などのテストスイートを Cypress に移行します。
• ci-cd-integration — GitHub Actions／GitLab CI で Cypress を実行するためのパイプラインテンプレート、並列化、アーティファクト管理を扱います。
• visual-testing — Cypress の機能テストを補完するビジュアルリグレッションテストを扱います。Cypress にはピクセル比較機能が組み込まれていません。
• unit-testing — ブラウザーを必要としないロジックには Jest／Vitest を使用します。Cypress のコンポーネントテストは、ユニットテストと E2E の間のギャップを埋めます。
• test-data-management — Cypress テストで使用するテストデータのシード、管理、クリーンアップを行います。
• qa-project-context — フレームワークの選択、CI プラットフォーム、規約を記録したプロジェクトコンテキストファイルです。