跳转到主要内容

分片

简介​

默认情况下，Playwright 会以并行方式运行测试文件，并努力最大限度地利用您机器上的 CPU 核心。为了实现更大的并行化，您可以通过同时在多台机器上运行测试来进一步扩展 Playwright 测试的执行。我们将这种操作模式称为“分片”（sharding）。Playwright 中的分片意味着将您的测试分成更小的部分，称为“分片”（shards）。每个分片就像一个可以独立运行的单独作业。这样做的目的就是分割您的测试以加快测试运行时间。

当您对测试进行分片时，每个分片都可以独立运行，利用可用的 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 报告选项的信息。

要合并来自多个分片的报告，请将 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 选项将为提供的选项的每个可能组合运行一个单独的作业。

以下示例向您展示了如何配置一个作业，以在四台机器上并行运行测试，然后将报告合并为单个报告。别忘了在 playwright.config.ts 文件中像上面示例中那样添加 reporter: process.env.CI ? 'blob' : 'html',。

  1. 首先，我们在作业配置中添加一个 matrix 选项，其中包含我们想要创建的分片总数的 shardTotal: [4] 选项，以及分片编号数组 shardIndex: [1, 2, 3, 4]。
  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@v5
    - uses: actions/setup-node@v5
      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 作业依赖于我们的分片 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@v5
    - uses: actions/setup-node@v5
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci

    - name: Download blob reports from GitHub Actions Artifacts
      uses: actions/download-artifact@v5
      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

合并来自多个环境的报告​

如果您想在多个环境中运行相同的测试，而不是将测试分片到多台机器上，您需要区分这些环境。

在这种情况下，指定 testConfig.tag 属性来标记所有带有环境名称的测试会很有用。此标签将自动被 blob 报告和后来的合并工具拾取。

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: process.env.CI ? 'blob' : 'html',
  tag: process.env.CI_ENVIRONMENT_NAME,  // for example "@APIv2"
});

Merge-reports CLI​

npx playwright merge-reports path/to/blob-reports-dir 从传入的目录中读取所有 blob 报告并将它们合并到单个报告中。

当合并来自不同操作系统的报告时，您需要提供一个明确的合并配置来区分应将哪个目录用作测试根目录。

支持的选项

  • --reporter 要使用的报告器。可以是多个用逗号分隔的报告器。

    要生成的报告。可以是多个用逗号分隔的报告器。

    示例

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