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

シャーディング

はじめに​

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

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

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

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

テストスイートをシャーディングするには、コマンドラインに --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 で実行する場合は、config に 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 台のマシンで並列にテストを実行し、レポートを単一のレポートにマージするようにジョブを構成する方法を示しています。上記の例のように、reporter: process.env.CI ? 'blob' : 'html', を playwright.config.ts ファイルに追加することを忘れないでください。

  1. 最初に、作成するシャードの総数を含む shardTotal: [4] オプションと、シャード番号の配列を含む shardIndex: [1, 2, 3, 4] を使用して、ジョブ構成に matrix オプションを追加します。
  2. 次に、--shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} オプションを使用して Playwright テストを実行します。これにより、各シャードに対してテストコマンドが実行されます。
  3. 最後に、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
  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 は、渡されたディレクトリからすべての blob レポートを読み取り、それらを単一のレポートにマージします。

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

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

  • --reporter reporter-to-use

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

    例

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

  • --config path/to/config/file

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

    例

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