cypress

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: "[email protected]" },
}).as("getUser");

4) 認証戦略

速度と安定性のために、ログインをキャッシュできる cy.session を優先してください。

// cypress/support/commands.ts
Cypress.Commands.add("login", () => {
  cy.session("user", () => {
    cy.request("POST", "/api/auth/login", {
      email: "[email protected]",
      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 でのみテストが失敗する

対処法：

• run モードのリトライ回数を増やし、失敗時にスクリーンショットを記録します。
• ビューポートと baseUrl の設定が CI 環境と一致していることを確認します。
• ローカル限定のシードデータへの依存をなくし、API 呼び出しでデータを作成します。

リソース

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