分片

簡介

預設情況下，Playwright 會以平行方式執行測試檔案，並力求最佳化您機器上 CPU 核心的利用率。為了實現更高的平行化，您可以透過在多部機器上同時執行測試來進一步擴展 Playwright 測試執行。我們將此操作模式稱為「分片」。Playwright 中的分片意味著將您的測試分割成稱為「分片」的較小部分。每個分片都像一個可以獨立運行的單獨作業。整個目的是分割您的測試以加速測試運行時間。

當您對測試進行分片時，每個分片都可以自行運行，從而利用可用的 CPU 核心。這有助於透過同時執行任務來加速測試過程。

在 CI 管道中，每個分片都可以作為一個單獨的作業運行，從而利用 CI 管道中可用的硬體資源（如 CPU 核心）來更快地運行測試。

在多部機器之間分片測試

若要對測試套件進行分片，請將 --shard=x/y 傳遞至命令列。例如，若要將套件分割成四個分片，每個分片運行四分之一的測試

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

現在，如果您在不同作業上平行運行這些分片，您的測試套件完成速度將快四倍。

請注意，Playwright 只能對可以平行運行的測試進行分片。預設情況下，這表示 Playwright 將對測試檔案進行分片。在平行處理指南中了解其他選項。

平衡分片

分片可以在兩個粒度層級完成，具體取決於您是否使用 testProject.fullyParallel 選項。這會影響測試在分片之間的平衡方式。

使用 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',
});

Blob 報告包含有關所有已運行測試及其結果的資訊，以及所有測試附件，例如追蹤和螢幕截圖差異。Blob 報告可以合併並轉換為任何其他 Playwright 報告。預設情況下，blob 報告將產生到 blob-report 目錄中。

若要合併來自多個分片的報告，請將 blob 報告檔案放入單一目錄中，例如 all-blob-reports。Blob 報告名稱包含分片編號，因此它們不會衝突。

之後，運行 npx playwright merge-reports 命令

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

這將在 playwright-report 目錄中產生標準 HTML 報告。

GitHub Actions 範例

GitHub Actions 支援使用在多個作業之間分片測試，方法是使用 jobs.<job_id>.strategy.matrix 選項。matrix 選項將為提供的選項的每個可能組合運行一個單獨的作業。

以下範例說明如何設定作業以在四部機器上平行運行測試，然後將報告合併為單一報告。別忘了將 reporter: process.env.CI ? 'blob' : 'html', 新增至您的 playwright.config.ts 檔案，如上述範例所示。

首先，我們將 matrix 選項新增至我們的作業設定，其中 shardTotal: [4] 選項包含我們要建立的分片總數，而 shardIndex: [1, 2, 3, 4] 包含分片編號陣列。
然後，我們使用 --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} 選項運行 Playwright 測試。這將為每個分片運行我們的測試命令。
最後，我們將我們的 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 報告。為了確保執行順序，我們透過新增 needs: [playwright-tests]，使 merge-reports 作業依賴於我們的分片 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 標籤中使用。

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' }]],
};
```

簡介​

在多部機器之間分片測試​

平衡分片​

合併來自多個分片的報告​

GitHub Actions 範例​

Merge-reports CLI​

簡介

在多部機器之間分片測試

平衡分片

合併來自多個分片的報告

GitHub Actions 範例

Merge-reports CLI