playwright-e2e-init

Playwright E2E テストの初期設定

Next.js および React アプリケーションでエンドツーエンドテストを行うための Playwright をセットアップします。

使用するタイミング

• Next.js プロジェクトに E2E テストを追加するとき
• ブラウザー自動化テストをセットアップするとき
• 重要なユーザーフローのテストを作成するとき
• E2E テストを CI/CD パイプラインに統合するとき

実行する内容

1. Playwright とブラウザーをインストールします
2. 設定ファイルを作成します（playwright.config.ts）
3. テストディレクトリをセットアップします（e2e/）
4. 一般的なフローのテスト例を作成します
5. テスト実行用の Bun スクリプトを追加します
6. CI/CD を更新して E2E テストを実行します

クイックスタート

プロンプトの例：

Add Playwright E2E tests to this project

または、具体的に指定します：

Set up E2E tests for the authentication flow

インストール

bun add -D @playwright/test
bunx playwright install chromium

設定

playwright.config.ts

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [["html", { open: "never" }], ["list"]],
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
  ],
  webServer: {
    command: "bun run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120 * 1000,
  },
});

テスト構成

e2e/
├── home.spec.ts          # Homepage tests
├── auth.spec.ts          # Authentication flow
├── navigation.spec.ts    # Navigation tests
└── fixtures/
    └── test-data.ts      # Shared test data

テスト例

コードベース内の実際のルートに合わせて、プロジェクト固有のテストを生成します。標準的な Playwright のテストパターン（ナビゲーション、認証フロー、フォーム送信、フィクスチャ）については、https://playwright.dev/docs/writing-tests に詳しい説明があります。インラインのテストでは一般的な例ではなく、プロジェクト固有のページや重要なユーザーフローに焦点を当ててください。

Bun スクリプト

package.json に追加します：

{
  "scripts": {
    "e2e": "playwright test",
    "e2e:ui": "playwright test --ui",
    "e2e:headed": "playwright test --headed",
    "e2e:debug": "playwright test --debug",
    "e2e:report": "playwright show-report"
  }
}

CI/CD との統合

GitHub Actions

CI ワークフローに追加します：

- name: Install Playwright Browsers
  run: bunx playwright install --with-deps chromium

- name: Run E2E tests
  run: bun run e2e
  env:
    CI: true

- name: Upload Playwright Report
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: playwright-report
    path: playwright-report/
    retention-days: 7

ベストプラクティス

• 認証、主要機能、支払い／チェックアウト、エラー処理など、重要なユーザーフローに E2E テストの対象を絞ります。
• セレクターには data-testid 属性を使用し、CSS クラスやテキストコンテンツには依存しないでください。
• 再利用可能なページ操作には、ページオブジェクトモデルを使用します（e2e/pages/）。
• 各テストが独立するようにします。それぞれのテストで、状態のセットアップとクリーンアップを行います。
• 共通のセットアップ（認証済みセッション、シードデータ）には、test.extend のフィクスチャを使用します。

トラブルシューティング

テストがタイムアウトする

設定ファイルでタイムアウトを延長します：

timeout: 60000, // 60 seconds

要素が見つからない

waitFor を使用します：

await page.waitForSelector('[data-testid="element"]');

不安定なテスト

リトライを追加して toPass を使用します：

await expect(async () => {
  await expect(page.locator("text=Success")).toBeVisible();
}).toPass({ timeout: 10000 });

他のスキルとの統合

スキル	統合
testing-cicd-init	先に単体テストをセットアップします
testing-expert	テストパターンを提供します
debug	不安定なテストや失敗するブラウザーフローを調査します