跳至主要内容

分片

简介​

默认情况下，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

This will produce a standard HTML report into playwright-report directory.

GitHub Actions 示例​

GitHub Actions 支持使用 jobs..strategy.matrix 选项在多个任务之间分片测试。matrix 选项将为提供的每个可能选项组合运行一个单独的任务。

The following example shows you how to configure a job to run your tests on four machines in parallel and then merge the reports into a single report. Don't forget to add reporter: process.env.CI ? 'blob' : 'html', to your playwright.config.ts file as in the example above.

  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@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. After all shards have completed, you can run a separate job that will merge the reports and produce a combined HTML report. To ensure the execution order, we make the merge-reports job depend on our sharded playwright-tests job by adding 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@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

You can now see the reports have been merged and a combined HTML report is available in the GitHub Actions Artifacts tab.

image

合并报告命令行界面​

npx playwright merge-reports path/to/blob-reports-dir 从指定目录读取所有blob报告并将它们合并为单个报告。

当合并来自不同操作系统的报告时，您需要提供一个明确的合并配置来消除歧义，确定哪个目录应作为测试根目录使用。

支持的选项：

  • --reporter reporter-to-use

    Which report to produce. Can be multiple reporters separated by comma.

    Example:

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

  • --config path/to/config/file

    Specifies the Playwright configuration file with output reporters. Use this option to pass additional configuration to the output reporter. This configuration file can differ from the one used during the creation of blob reports.

    Example:

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