Next.js × Playwright × GitHub Actions でE2EテストのCI/CDを構築する

この記事でわかること

• PlaywrightをNext.jsプロジェクトに導入する方法
• GitHub ActionsでPlaywrightのE2Eテストを自動実行する方法
• CI上でNext.jsアプリを起動してテストするためのYAML設定
• よくあるエラーとその対処法

対象読者

• Next.jsでWebアプリを開発している方
• Playwrightを使ったE2Eテストに興味がある方
• GitHub ActionsでCI/CDを構築したい方

---

1. Playwrightを導入する

まず、Next.js プロジェクトに Playwright をインストールします。

npx playwright install

初回実行で自動的に playwright.config.ts が生成され、以下のような構成になります。

my-app/
├── tests/             # テストコードを置くディレクトリ
│   └── example.spec.ts
├── playwright.config.ts
└── package.json

サンプルテスト

tests/example.spec.ts

import { test, expect } from '@playwright/test';

test('トップページのタイトルを検証', async ({ page }) => {
  await page.goto('http://localhost:3000');
  await expect(page).toHaveTitle(/MyApp/);
});

2. GitHub ActionsでPlaywrightを動かす

.github/workflows/playwright.yml を作成して、次のように記述します。

.github/workflows/playwright.yml

name: Playwright Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    timeout-minutes: 10
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Build Next.js app
        run: npm run build

      - name: Start Next.js app
        run: npm run start &
        env:
          PORT: 3000

      - name: Wait for app to be ready
        run: npx wait-on http://localhost:3000

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test

      - name: Upload HTML report (on failure)
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: playwright-report

補足
• npm run start & でアプリをバックグラウンドで起動
• wait-on を使ってアプリの起動完了を待つ
• --with-deps はCI環境でブラウザを動かすために必要

3. playwright.config.ts を調整する

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30 * 1000,
  retries: 1,
  use: {
    headless: true,
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    baseURL: 'http://localhost:3000',
  },
  reporter: [['html', { outputFolder: 'playwright-report' }]],
});

•screenshot や video は失敗時のデバッグに有効
• baseURL を設定しておくと page.goto('/') のように書ける

4. テスト結果をレポートとして保存する

PlaywrightはHTML形式のレポートを出力できます。

CIでは、失敗時のみレポートをアップロードするように設定しています。

      - name: Upload HTML report (on failure)
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: playwright-report

GitHub Actions の「Artifacts」からダウンロードして確認できます。

⸻

5. トラブルシューティング

chromium not found

Playwrightはブラウザのバイナリが必要です。CI環境では以下を必ず実行してください。

npx playwright install --with-deps

No tests found

• テストファイルの命名が .spec.ts になっているか確認
• playwright.config.ts の testDir のパスが合っているか確認

アプリが起動前にテストが始まってしまう

• npx wait-on http://localhost:3000 を必ず挿入する

6. Preview環境でのE2E実行（応用）

VercelのPreview URLやステージング環境でテストしたい場合は、以下のように baseURL を指定します。

npx playwright test --project=chromium --base-url=https://preview.example.com

playwright.config.ts 側で環境変数を読み込むようにしておくと柔軟に対応できます。

おわりに

PlaywrightとGitHub Actionsを組み合わせることで、E2Eテスト付きのCI/CDパイプラインを構築できます。

ユニットテストでは見つけにくい、ページ遷移、フォーム入力、バリデーションなどの不具合も検出でき、プロダクトの品質向上に繋がります。

自動でE2Eが実行される安心感、ぜひ体感してみてください。