分片

簡介

預設情況下，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:
    # 在 playwright-tests 後合併報告，即使某些分片失敗也要執行
    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 報告並將它們合併為單一報告。

當合併來自不同作業系統的報告時，您需要提供明確的合併組態設定來消除歧義，說明應該使用哪個目錄作為測試根目錄。

支援的選項：

--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