メインコンテンツにスキップ

シャーディング

はじめに​

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

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

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

主要なポイント

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

複数のシャードからのレポートの結合​

前の例では、各テストシャードには独自のテストレポートがあります。すべてのシャードからのすべてのテスト結果を示す結合レポートが必要な場合は、それらを結合できます。

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

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

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

複数のシャードからのレポートを結合するには、ブロブレポートファイルを 1 つのディレクトリ (例: all-blob-reports) に配置します。ブロブレポート名にはシャード番号が含まれているため、競合しません。

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

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

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

GitHub Actions の例​

GitHub Actions は、jobs..strategy.matrix オプションを使用して、複数のジョブ間でテストをシャード化することをサポートしています。matrix オプションは、提供されたオプションのすべての可能な組み合わせに対して個別のジョブを実行します。

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

  1. まず、ジョブ構成に matrix オプションを追加します。これには、作成するシャードの総数を含む shardTotal: [4] オプションと、シャード番号の配列を含む shardIndex: [1, 2, 3, 4] が含まれます。
  2. 次に、--shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} オプションを使用して Playwright テストを実行します。これにより、各シャードのテストコマンドが実行されます。
  3. 最後に、ブロブレポートを GitHub Actions Artifacts にアップロードします。これにより、ワークフロー内の他のジョブでブロブレポートが利用できるようになります。
.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
  1. すべてのシャードが完了した後、レポートを結合して統合されたHTML レポートを生成する個別のジョブを実行できます。実行順序を確保するために、merge-reports ジョブを、needs: [playwright-tests] を追加することで、シャード化された 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 タブで利用できるようになっていることを確認できます。

image

Merge-reports CLI​

npx playwright merge-reports path/to/blob-reports-dir は、渡されたディレクトリからすべてのブロブレポートを読み取り、それらを単一のレポートに結合します。

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

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

  • --reporter reporter-to-use

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

    例

    npx playwright merge-reports --reporter=html,github ./blob-reports

  • --config path/to/config/file

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

    例

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