シャーディング

はじめに

デフォルトでは、Playwright はテストファイルを並列で実行し、お使いのマシン上のCPUコアを最適に利用するように努めます。さらに並列化を進めるには、複数のマシンで同時にテストを実行することで、Playwright のテスト実行をさらにスケールアップできます。この操作モードを「シャーディング」と呼びます。Playwright におけるシャーディングとは、テストを「シャード」と呼ばれる小さな部分に分割することを意味します。各シャードは独立して実行できる個別のジョブのようなものです。その目的は、テストの実行時間を短縮するためにテストを分割することです。

テストをシャーディングすると、各シャードはそれぞれ利用可能なCPUコアを活用して独自に実行できます。これにより、タスクを同時に実行することでテストプロセスを高速化できます。

CI パイプラインでは、各シャードは個別のジョブとして実行でき、CI パイプラインで利用可能な CPU コアなどのハードウェアリソースを利用して、テストをより速く実行できます。

複数のマシン間でのテストのシャーディング

テストスイートをシャーディングするには、--shard=x/yをコマンドラインに渡します。例えば、スイートを4つのシャードに分割し、それぞれがテストの4分の1を実行する場合です。

npx playwright test --shard=1/4
npx playwright test --shard=2/4
npx playwright test --shard=3/4
npx playwright test --shard=4/4

これで、これらのシャードを異なるジョブで並列に実行すると、テストスイートは4倍速く完了します。

Playwright は並列実行可能なテストのみをシャーディングできることに注意してください。デフォルトでは、これは Playwright がテストファイルをシャーディングすることを意味します。並列処理ガイドで他のオプションについて学習してください。

シャードのバランス調整

シャーディングは、testProject.fullyParallelオプションを使用するかどうかに応じて、2つの粒度レベルで行うことができます。これは、テストがシャード間でどのようにバランスされるかに影響します。

fullyParallel を使用したシャーディング

fullyParallel: trueを有効にすると、Playwright テストは複数のシャード間で個々のテストを並列実行し、各シャードが均等にテストを分散して受け取るようにします。これによりテストレベルの粒度が可能になり、各シャードは実行する個々のテストの数をバランスさせようとします。これは、シャーディング時に均等な負荷分散を確実にするための推奨モードであり、Playwright はテストの総数に基づいてシャードの実行を最適化できます。

fullyParallel を使用しないシャーディング

fullyParallel 設定がない場合、Playwright テストはデフォルトでファイルレベルの粒度になります。つまり、テストファイル全体がシャードに割り当てられます（同じファイルが異なるプロジェクト間で異なるシャードに割り当てられる場合があることに注意してください）。この場合、ファイルごとのテスト数がシャードの分散に大きく影響する可能性があります。テストファイルのサイズが均一でない場合（つまり、一部のファイルに他のファイルよりも多くのテストが含まれている場合）、特定のシャードは大幅に多くのテストを実行することになり、他のシャードはより少ないテストしか実行しないか、まったく実行しないことになります。

重要なポイント

fullyParallel: true の場合: テストは個々のテストレベルで分割され、よりバランスの取れたシャード実行につながります。
fullyParallel なしの場合: テストはファイルレベルで分割されるため、シャードのバランスを取るには、テストファイルを小さく、均一なサイズに保つことが重要です。
シャーディングを最も効果的に利用するには、特に CI 環境において、fullyParallel: trueを使用してシャード間のバランスの取れた分散を目指すことをお勧めします。そうしないと、不均衡を避けるためにテストファイルを手動で整理する必要がある場合があります。

複数のシャードからのレポートのマージ

前の例では、各テストシャードは独自のテストレポートを持っています。すべてのシャードからのすべてのテスト結果を示す結合されたレポートを作成したい場合は、それらをマージできます。

CI で実行する場合、設定にblobレポーターを追加することから始めます。

playwright.config.ts
export default defineConfig({
  testDir: './tests',
  reporter: process.env.CI ? 'blob' : 'html',
});

BLOB レポートには、実行されたすべてのテストに関する情報とその結果、およびトレースやスクリーンショットの差分などのすべてのテストアタッチメントが含まれます。BLOB レポートはマージして、他の Playwright レポートに変換できます。デフォルトでは、BLOB レポートはblob-reportディレクトリに生成されます。

複数のシャードからのレポートをマージするには、BLOB レポートファイルを1つのディレクトリ、例えばall-blob-reportsに置きます。BLOB レポート名にはシャード番号が含まれているため、競合しません。

その後、npx playwright merge-reportsコマンドを実行します。

npx playwright merge-reports --reporter html ./all-blob-reports

これにより、標準の HTML レポートがplaywright-reportディレクトリに出力されます。

GitHub Actions の例

GitHub Actions は、複数のジョブ間でのテストのシャーディングを、jobs.<job_id>.strategy.matrixオプションを使用してサポートしています。matrixオプションは、指定されたオプションの考えられるすべての組み合わせに対して個別のジョブを実行します。

以下の例は、4つのマシンでテストを並列実行し、その後レポートを1つのレポートにマージするようにジョブを設定する方法を示しています。reporter: process.env.CI ? 'blob' : 'html',を、上記の例のようにplaywright.config.tsファイルに追加することを忘れないでください。

まず、ジョブ設定にmatrixオプションを追加し、作成したいシャードの総数を含むshardTotal: [4]オプションと、シャード番号の配列であるshardIndex: [1, 2, 3, 4]を追加します。
次に、Playwright テストを--shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}オプションを指定して実行します。これにより、各シャードに対してテストコマンドが実行されます。
最後に、BLOB レポートを GitHub Actions Artifacts にアップロードします。これにより、BLOB レポートがワークフロー内の他のジョブで利用可能になります。

.github/workflows/playwright.yml
name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  playwright-tests:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright browsers
      run: npx playwright install --with-deps

    - name: Run Playwright tests
      run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}

    - name: Upload blob report to GitHub Actions Artifacts
      if: ${{ !cancelled() }}
      uses: actions/upload-artifact@v4
      with:
        name: blob-report-${{ matrix.shardIndex }}
        path: blob-report
        retention-days: 1

すべてのシャードが完了した後、レポートをマージして結合されたHTML レポートを生成する別のジョブを実行できます。実行順序を確実にするため、merge-reportsジョブを、シャーディングされたplaywright-testsジョブにneeds: [playwright-tests]を追加することで依存させます。

.github/workflows/playwright.yml
jobs:
...
  merge-reports:
    # Merge reports after playwright-tests, even if some shards have failed
    if: ${{ !cancelled() }}
    needs: [playwright-tests]

    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci

    - name: Download blob reports from GitHub Actions Artifacts
      uses: actions/download-artifact@v4
      with:
        path: all-blob-reports
        pattern: blob-report-*
        merge-multiple: true

    - name: Merge into HTML Report
      run: npx playwright merge-reports --reporter html ./all-blob-reports

    - name: Upload HTML report
      uses: actions/upload-artifact@v4
      with:
        name: html-report--attempt-${{ github.run_attempt }}
        path: playwright-report
        retention-days: 14

これで、レポートがマージされ、結合された HTML レポートが GitHub Actions の Artifacts タブで利用できるようになったことがわかります。

レポートマージ CLI

npx playwright merge-reports path/to/blob-reports-dirは、指定されたディレクトリからすべての BLOB レポートを読み込み、それらを1つのレポートにマージします。

異なる OS からのレポートをマージする場合、どのディレクトリをテストルートとして使用するかを明確にするために、明示的なマージ設定を提供する必要があります。

サポートされているオプション

--reporter レポーター使用

生成するレポート。コンマで区切られた複数のレポーターを指定できます。

例
```
npx playwright merge-reports --reporter=html,github ./blob-reports
```
--config 設定ファイルのパス

出力レポーターを含む Playwright 設定ファイルを指定します。このオプションを使用して、出力レポーターに追加の設定を渡します。この設定ファイルは、BLOB レポートの作成時に使用されたものと異なる場合があります。

例
```
npx playwright merge-reports --config=merge.config.ts ./blob-reports
```
merge.config.ts
```
export default {
  testDir: 'e2e',
  reporter: [['html', { open: 'never' }]],
};
```

はじめに​

複数のマシン間でのテストのシャーディング​

シャードのバランス調整​

複数のシャードからのレポートのマージ​

GitHub Actions の例​

レポートマージ CLI​