Cypress (E2E + コンポーネントテスト)

概要

Cypress はブラウザ自動化を第一級のネットワーク制御、タイムトラベルデバッグ、強力なローカル開発ワークフローで実行します。重要なパスの E2E テストや、ブラウザレベルのレンダリングが重要な場合のコンポーネントテストに使用します。

クイックスタート

インストールと起動

npm i -D cypress
npx cypress open

最小限のスペック

// cypress/e2e/health.cy.ts
describe("health", () => {
  it("loads", () => {
    cy.visit("/");
    cy.contains("Hello").should("be.visible");
  });
});

コアパターン

1) 安定したセレクタ

セレクタには data-testid (または data-cy) 属性を使用してください。重要なインタラクションでは、脆い CSS チェーンやテキストのみのセレクタは避けてください。

<button data-testid="save-user">Save</button>

cy.get('[data-testid="save-user"]').click();

2) 決定論的な待機 (固定スリープの回避)

cy.wait(1000) ではなく、アプリケーションで見える条件またはネットワークエイリアスで待機してください。

cy.intercept("GET", "/api/users/*").as("getUser");
cy.visit("/users/1");
cy.wait("@getUser");
cy.get('[data-testid="user-email"]').should("not.be.empty");

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

テストの決定性と速度のためにレスポンスをスタブします。「実バックエンド」のスモークテストは小さなセットで分けて保つようにしてください。

cy.intercept("GET", "/api/users/1", {
  statusCode: 200,
  body: { id: "1", email: "a@example.com" },
}).as("getUser");

4) 認証戦略

速度と安定性のために cy.session を使用してログインをキャッシュすることをお勧めします。

// cypress/support/commands.ts
Cypress.Commands.add("login", () => {
  cy.session("user", () => {
    cy.request("POST", "/api/auth/login", {
      email: "test@example.com",
      password: "password",
    });
  });
});

// e2e spec
beforeEach(() => {
  cy.login();
});

コンポーネントテスト

ブラウザレンダリングを保持しながら、UI 動作を単独で検証するコンポーネントテストを実行します。

npx cypress open --component

// cypress/component/Button.cy.tsx
import React from "react";
import Button from "../../src/Button";

describe("<Button />", () => {
  it("clicks", () => {
    cy.mount(<Button onClick={cy.stub().as("onClick")}>Save</Button>);
    cy.contains("Save").click();
    cy.get("@onClick").should("have.been.calledOnce");
  });
});

CI パターン

アーティファクト (ビデオ/スクリーンショット)

失敗した実行のアーティファクトを保存し、ストレージを削減するためビデオはオプションのままにします。

// cypress.config.ts
import { defineConfig } from "cypress";

export default defineConfig({
  video: false,
  screenshotOnRunFailure: true,
  retries: { runMode: 2, openMode: 0 },
});

並列化 (Cypress Cloud)

実行時がフィードバックループの支配的な場合、Cypress Cloud を経由して長い E2E スイートを並列化します。

アンチパターン

• cy.wait(1000) を同期メカニズムとして使用する。
• 深い CSS パスで要素を選択する。
• 同じスペック内で大量のネットワークスタブと「実バックエンド」のアサーションを混ぜる。
• テスト順序に依存する。cy.session とテストごとのセットアップで状態を分離する。

トラブルシューティング

症状: クリックが不安定、または要素が見つからない

対応:

• 要素に data-testid フックを追加する。
• インタラクション前に可視性をアサートする (should("be.visible"))。
• 要素をレンダリングするデータのネットワークエイリアスで待機する。

症状: テストが CI でのみ失敗する

対応:

• 実行モードの再試行を増やし、失敗時にスクリーンショットを記録する。
• ビューポートと baseUrl の設定が CI 環境と一致することを確認する。
• ローカルのみのシードデータへの依存を排除し、API 呼び出しでデータを作成する。

リソース

• Cypress ドキュメント: https://docs.cypress.io/
• ベストプラクティス: https://docs.cypress.io/guides/references/best-practices