Playwright on GitHub Actionsを高速化する実装ガイド

結論：キャッシングと環境最適化で80%の時間短縮が可能

GitHub ActionsでPlaywrightテストを実行する際、デフォルトでは毎回ブラウザのダウンロードと環境構築に 5〜10分 かかります。actions/cacheを活用した依存関係キャッシング、ブラウザキャッシング、ワーカー数の最適化を組み合わせることで、1〜2分まで短縮 できます。大規模プロジェクトでは月間数時間の時間削減になります。

なぜPlaywrightのセットアップは遅いのか

主な遅延原因

1. ブラウザバイナリのダウンロード — Chromium、Firefox、WebKitを初回ダウンロード時に100～300MB
2. node_modulesの構築時間 — 毎回npm installまたはyarn installを実行する場合、30秒～2分
3. 依存関係の解決 — Playwrightの周辺パッケージ（テストランナー、アサーション、レポーターなど）の依存解決時間
4. OSレベルの依存関係 — Ubuntu/Debianベースのランナーでシステムパッケージ更新が発生する場合

デフォルト実行時の流れ

# ❌ 遅いパターン
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
  - run: npm install
  - run: npm run test:e2e  # ←ここでブラウザ再ダウンロード

毎回ゼロから環境を作り直すため、並列実行しても各ジョブが同じ重い処理を繰り返します。

実装：高速セットアップの4つのステップ

1. node_modulesキャッシング

Package-lockファイルが変わらなければ、依存関係はキャッシュから復元します。

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # ← package-lock.jsonをキーにしたキャッシング

効果： 初回30秒～2分かかるnpm installを3秒～10秒に短縮

2. Playwrightブラウザキャッシング

Playwrightが管理するブラウザバイナリを明示的にキャッシュします。

- uses: actions/cache@v3
  with:
    path: |
      ~/.cache/ms-playwright
      ~/Library/Caches/ms-playwright
      %APPDATA%\ms-playwright
    key: playwright-browsers-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      playwright-browsers-

重要ポイント：

• Linux（Ubuntu）の場合：~/.cache/ms-playwright
• macOS（M1/M2含む）の場合：~/Library/Caches/ms-playwright
• Windows の場合：%APPDATA%\ms-playwright
• hashFiles('**/package-lock.json')で、Playwright バージョン変更時に自動的に新しいキャッシュを作成

効果： ブラウザ再ダウンロード（100～300MB、3～5分）をスキップ

3. 並列実行の活用

Playwrightの--workersオプションと GitHub Actions の matrix を組み合わせ、複数ジョブで分散実行します。

strategy:
  matrix:
    shard: [1, 2, 3, 4]

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'
  - run: npm install
  - run: npm run build  # テスト前にアプリケーション構築
  - name: Run Playwright tests
    run: npx playwright test --shard=${{ matrix.shard }}/4

Playwright設定ファイル例（playwright.config.ts）：

export default defineConfig({
  testDir: './tests',
  workers: 4,  // 1ジョブ内での並列ワーカー数
  fullyParallel: true,  // 全テストケースを並列実行
  retries: 1,  // CI環境での不安定性対策（ローカルでは0推奨）
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',  // 失敗時のみトレース記録（ストレージ削減）
  },
});

効果： 4ジョブに分散で最大4倍高速化（CI環境での待機時間も短縮）

4. システム依存関係の最適化

Playwrightは実行時にOSレベルのライブラリが必要です。事前インストール時に最新化することで、毎回の更新を避けます。

- name: Install Playwright system dependencies
  run: npx playwright install-deps

- uses: actions/cache@v3
  with:
    path: ~/.cache/ms-playwright
    key: playwright-browsers-${{ hashFiles('**/package-lock.json') }}

Ubuntu 22.04上での必要なライブラリ： libgtk-3-0、libgbm1、libnss3、libxss1、libatk-bridge2.0-0など（playwright install-depsで自動処理）

完全なワークフロー例

name: Playwright Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  test:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci  # npm installではなくnpm ciを使用（再現性向上）
      
      - name: Install Playwright browsers
        run: npx playwright install --with-deps
      
      - name: Build application
        run: npm run build
      
      - name: Run Playwright tests (shard ${{ matrix.shard }}/4)
        run: npx playwright test --shard=${{ matrix.shard }}/4
      
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report-${{ matrix.shard }}
          path: playwright-report/
          retention-days: 7

実測値：セットアップ時間の削減

シナリオ別の実行時間比較

よくある落とし穴と対策

キャッシュキー設定を間違える

❌ 間違い： キーに日付を含める

key: playwright-${{ github.run_id }}
# →毎回新しいキャッシュが作られるため、キャッシュヒット率0%

✅ 正解： バージョン管理ファイルをキーにする

key: playwright-browsers-${{ hashFiles('**/package-lock.json') }}

ブラウザのダウンロード設定を忘れる

❌ キャッシングしても、playwright installを実行しない場合

- run: npm ci
- run: npm test  # ←ブラウザが無いと実行時にダウンロード

✅ 事前にブラウザをキャッシュに含める

- run: npm ci
- run: npx playwright install --with-deps
- uses: actions/cache@v3
  with:
    path: ~/.cache/ms-playwright
    key: playwright-browsers-...

npm installとnpm ciの選択ミス

• npm install：package.jsonから依存関係を再計算（遅い、CI向けではない）
• npm ci（CI向け推奨）：package-lock.jsonを厳密に再現（高速、再現性向上）

マトリックス分割時のシャード数の最適化

• シャード数が少ない（1～2） → テストが並列化されず、時間短縮効果が薄い
• シャード数が多い（8以上） → GitHub Actionsのビルド数が増え、待機時間が長くなる
• 推奨値：4～6シャード → テスト数 100～200個の場合、各ジョブ 30秒～2分が目安

不安定なテストによるリトライ多発

retries: 1を設定すると、初回失敗時に再実行されます。不安定なテストが多いと、リトライによる時間が加算されます。

# CI環境での推奨設定
retries: process.env.CI ? 1 : 0,

さらに高速化：S3キャッシュバックエンド

大規模プロジェクトでGitHub Actionsのキャッシュ容量（5GB）を超える場合、AWS S3連携を検討します。

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v2
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: ap-northeast-1

- name: Cache to S3
  uses: actions/cache@v3
  with:
    path: ~/.cache/ms-playwright
    key: playwright-s3-${{ hashFiles('**/package-lock.json') }}
    lookup-only: false

効果： CDN経由でブラウザキャッシュを高速復元（5秒程度）

まとめと次のステップ

実装優先順

1. 即実装（5分） → cache: 'npm'をactions/setup-nodeに追加
2. 次に実装（10分） → Playwrightブラウザキャッシュを追加
3. テスト数が多い場合（20分） → マトリックスで並列実行設定
4. 余裕があれば（30分） → S3キャッシュ連携

検証方法

GitHub Actions実行画面で「Restore cache」「Save cache」ステップをチェック。キャッシュヒット（cache hit）が表示されていれば設定が正しく機能しています。

ポイント — セットアップの高速化がチーム全体に及ぼす効果は見過ごされやすいですが、1日10回のテスト実行があれば月間2〜3時間の削減になります。開発体験の向上と同時にCI/CDコストも低下させます。