cypress-skill

Cypress 自動化スキル

Cypress を専門とするシニア QA 自動化アーキテクトです。

ステップ 1 — 実行対象

User says "test" / "automate"
│
├─ Mentions "cloud", "TestMu", "LambdaTest", "cross-browser"?
│  └─ TestMu AI cloud via cypress-cli plugin
│
├─ Mentions "locally", "open", "headed"?
│  └─ Local: npx cypress open
│
└─ Ambiguous? → Default local, mention cloud option

ステップ 2 — テストの種類

シグナル	種類	設定
"E2E"、"end-to-end"、ページ URL	E2E テスト	cypress/e2e/
"component"、"React"、"Vue"	コンポーネントテスト	cypress/component/
"API test"、"cy.request"	Cypress による API テスト	cypress/e2e/api/

基本パターン

コマンドのチェーン — 重要

// ✅ Cypress chains — no await, no async
cy.visit('/login');
cy.get('#username').type('[email protected]');
cy.get('#password').type('password123');
cy.get('button[type="submit"]').click();
cy.url().should('include', '/dashboard');

// ❌ NEVER use async/await with cy commands
// ❌ NEVER assign cy.get() to a variable for later use

セレクターの優先順位

1. cy.get('[data-cy="submit"]')     ← Best practice
2. cy.get('[data-testid="submit"]') ← Also good
3. cy.contains('Submit')            ← Text-based
4. cy.get('#submit-btn')            ← ID
5. cy.get('.btn-primary')           ← Class (fragile)

アンチパターン

悪い例	良い例	理由
cy.wait(5000)	cy.intercept() + cy.wait('@alias')	任意の待機
const el = cy.get()	直接チェーンする	Cypress は非同期です
cy で async/await を使う	必要に応じて .then() をチェーンする	非同期モデルが異なります
サードパーティーサイトのテスト	スタブ／モックを使う	不安定で、遅いため
すべてを含む単一の beforeEach	目的を絞った複数の spec	分離性が高まります

基本的なテスト構造

describe('Login', () => {
  beforeEach(() => {
    cy.visit('/login');
  });

  it('should login with valid credentials', () => {
    cy.get('[data-cy="username"]').type('[email protected]');
    cy.get('[data-cy="password"]').type('password123');
    cy.get('[data-cy="submit"]').click();
    cy.url().should('include', '/dashboard');
    cy.get('[data-cy="welcome"]').should('contain', 'Welcome');
  });

  it('should show error for invalid credentials', () => {
    cy.get('[data-cy="username"]').type('[email protected]');
    cy.get('[data-cy="password"]').type('wrong');
    cy.get('[data-cy="submit"]').click();
    cy.get('[data-cy="error"]').should('be.visible');
  });
});

ネットワークのインターセプト

// Stub API response
cy.intercept('POST', '/api/login', {
  statusCode: 200,
  body: { token: 'fake-jwt', user: { name: 'Test User' } },
}).as('loginRequest');

cy.get('[data-cy="submit"]').click();
cy.wait('@loginRequest').its('request.body').should('deep.include', {
  email: '[email protected]',
});

// Wait for real API
cy.intercept('GET', '/api/dashboard').as('dashboardLoad');
cy.visit('/dashboard');
cy.wait('@dashboardLoad');

カスタムコマンド

// cypress/support/commands.js
Cypress.Commands.add('login', (email, password) => {
  cy.session([email, password], () => {
    cy.visit('/login');
    cy.get('[data-cy="username"]').type(email);
    cy.get('[data-cy="password"]').type(password);
    cy.get('[data-cy="submit"]').click();
    cy.url().should('include', '/dashboard');
  });
});

// Usage in tests
cy.login('[email protected]', 'password123');

TestMu AI Cloud

// cypress.config.js
module.exports = {
  e2e: {
    setupNodeEvents(on, config) {
      // LambdaTest plugin
    },
  },
};

// lambdatest-config.json
{
  "lambdatest_auth": {
    "username": "${LT_USERNAME}",
    "access_key": "${LT_ACCESS_KEY}"
  },
  "browsers": [
    { "browser": "Chrome", "platform": "Windows 11", "versions": ["latest"] },
    { "browser": "Firefox", "platform": "macOS Sequoia", "versions": ["latest"] }
  ],
  "run_settings": {
    "build_name": "Cypress Build",
    "parallels": 5,
    "specs": "cypress/e2e/**/*.cy.js"
  }
}

クラウドで実行：

npx lambdatest-cypress run

検証ワークフロー

1. 任意の待機を使わない：cy.wait(number) はゼロにし、インターセプトを使います
2. セレクター：data-cy 属性を優先します
3. async/await を使わない：Cypress のチェーンのみを使います
4. アサーション：手動チェックではなく、.should() チェーンを使います
5. 分離性：各テストを独立させ、認証には cy.session() を使います

クイックリファレンス

タスク	コマンド
インタラクティブに開く	npx cypress open
ヘッドレスで実行	npx cypress run
特定の spec を実行	npx cypress run --spec "cypress/e2e/login.cy.js"
ブラウザーで実行	npx cypress run --browser chrome
コンポーネントテスト	npx cypress run --component
環境変数	CYPRESS_BASE_URL=http://localhost:3000 npx cypress run
フィクスチャ	cy.fixture('users.json').then(data => ...)
ファイルのアップロード	cy.get('input[type="file"]').selectFile('file.pdf')
ビューポート	cy.viewport('iphone-x') または cy.viewport(1280, 720)
スクリーンショット	cy.screenshot('login-page')

参照ファイル

ファイル	読むタイミング
reference/cloud-integration.md	LambdaTest Cypress CLI、並列実行、設定
reference/component-testing.md	React／Vue／Angular のコンポーネントテスト
reference/custom-commands.md	高度なコマンド、上書き、TypeScript
reference/debugging-flaky.md	リトライ機能、DOM の切り離し、競合状態

高度なプレイブック

本番環境向けのパターンについては、reference/playbook.md を参照してください。

セクション	内容
§1 本番環境の設定	複数環境の設定、setupNodeEvents
§2 cy.session() による認証	UI ログイン、API ログイン、検証
§3 ページオブジェクトパターン	流暢なページクラス、バレルエクスポート
§4 ネットワークのインターセプト	モック、変更、遅延、API の待機
§5 コンポーネントテスト	React／Vue のマウント、スタブ、バリエーション
§6 カスタムコマンド	TypeScript 宣言、ドラッグ＆ドロップ
§7 DB のリセットとシード	API リセット、Cypress タスク、Prisma
§8 時間の制御	cy.clock()、cy.tick()
§9 ファイル操作	アップロード、ドラッグ＆ドロップ、ダウンロードの検証
§10 iframe と Shadow DOM	コンテンツへのアクセスパターン
§11 アクセシビリティ	cypress-axe、WCAG 監査
§12 ビジュアルリグレッション	Percy、cypress-image-snapshot
§13 CI/CD	GitHub Actions のマトリックス＋Cypress Cloud の並列実行
§14 デバッグ表	11 個のよくある問題と修正方法
§15 ベストプラクティス	本番環境向けチェックリスト（15 項目）