持续集成

介绍

🌐 Introduction

Playwright 测试可以在 CI 环境中执行。我们已经为常见的 CI 提供商创建了示例配置。

🌐 Playwright tests can be executed in CI environments. We have created sample configurations for common CI providers.

在 CI 上运行测试的 3 个步骤：

1. 确保 CI 代理能够运行浏览器：在 Linux 代理中使用 我们的 Docker 镜像，或使用 CLI 安装你的依赖。

2. 安装 Playwright：

   # Install NPM packages
   npm ci
   
   # Install Playwright browsers and dependencies
   npx playwright install --with-deps

3. 运行你的测试：

   npx playwright test

工作进程

🌐 Workers

我们建议在 CI 环境中将 workers 设置为“1”，以优先考虑稳定性和可重复性。顺序运行测试可以确保每个测试获得完整的系统资源，从而避免潜在的冲突。但是，如果你有一台强大的自建 CI 系统，你可以启用 parallel 测试。为了实现更广泛的并行化，可以考虑 sharding —— 将测试分配到多个 CI 任务中。

🌐 We recommend setting workers to "1" in CI environments to prioritize stability and reproducibility. Running tests sequentially ensures each test gets the full system resources, avoiding potential conflicts. However, if you have a powerful self-hosted CI system, you may enable parallel tests. For wider parallelization, consider sharding - distributing tests across multiple CI jobs.

playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  // Opt out of parallel tests on CI.
  workers: process.env.CI ? 1 : undefined,
});

CI 配置

🌐 CI configurations

命令行工具 可用于在持续集成中安装所有操作系统依赖。

🌐 The Command line tools can be used to install all operating system dependencies in CI.

GitHub 操作

🌐 GitHub Actions

在推/拉请求时

🌐 On push/pull_request

测试将在 main/master 分支上的 push 或 pull request 时运行。工作流 将安装所有依赖、安装 Playwright 然后运行测试。它还会生成 HTML 报告。

🌐 Tests will run on push or pull request on branches main/master. The workflow will install all dependencies, install Playwright and then run the tests. It will also create the HTML report.

.github/workflows/playwright.yml

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-node@v6
      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
    - uses: actions/upload-artifact@v5
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

在 push/pull_request 上（分片）

🌐 On push/pull_request (sharded)

GitHub Actions 支持在多个作业之间分片测试。查看我们的分片文档以了解更多关于分片的信息，并查看一个GitHub Actions 示例，了解如何配置作业在多台机器上运行测试，以及如何合并 HTML 报告。

🌐 GitHub Actions supports sharding tests between multiple jobs. Check out our sharding doc to learn more about sharding and to see a GitHub actions example of how to configure a job to run your tests on multiple machines as well as how to merge the HTML reports.

通过容器

🌐 Via Containers

GitHub Actions 支持通过使用 jobs.<job_id>.container 选项在容器中运行作业。这有助于避免在主机环境中引入依赖，并在不同操作系统上进行截图/视觉回归测试时保持一致的环境。

.github/workflows/playwright.yml

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  playwright:
    name: 'Playwright Tests'
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.58.0-noble
      options: --user 1001
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v6
        with:
          node-version: lts/*
      - name: Install dependencies
        run: npm ci
      - name: Run your tests
        run: npx playwright test

部署中

🌐 On deployment

这将在 GitHub 部署 进入 success 状态后开始测试。像 Vercel 这样的服务使用这种模式，以便你可以在其已部署的环境中运行端到端测试。

🌐 This will start the tests after a GitHub Deployment went into the success state. Services like Vercel use this pattern so you can run your end-to-end tests on their deployed environment.

.github/workflows/playwright.yml

name: Playwright Tests
on:
  deployment_status:
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    if: github.event.deployment_status.state == 'success'
    steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-node@v6
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
      env:
        PLAYWRIGHT_TEST_BASE_URL: ${{ github.event.deployment_status.target_url }}

快速失败

🌐 Fail-Fast

大型测试套件可能需要很长时间才能执行。通过使用 --only-changed 标志进行初步测试运行，你可以先运行可能会失败的测试文件。这将为你提供更快的反馈循环，并在处理拉取请求时稍微降低 CI 的消耗。为了检测受你的更改集影响的测试文件，--only-changed 会分析你的测试套件依赖图。这是一种启发式方法，可能会遗漏一些测试，因此在初步测试运行后，始终运行完整的测试套件非常重要。

🌐 Large test suites can take very long to execute. By executing a preliminary test run with the --only-changed flag, you can run test files that are likely to fail first. This will give you a faster feedback loop and slightly lower CI consumption while working on Pull Requests. To detect test files affected by your changeset, --only-changed analyses your suites' dependency graph. This is a heuristic and might miss tests, so it's important that you always run the full test suite after the preliminary test run.

.github/workflows/playwright.yml

name: Playwright Tests
on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v5
      with:
        # Force a non-shallow checkout, so that we can reference $GITHUB_BASE_REF.
        # See https://github.com/actions/checkout for more details.
        fetch-depth: 0
    - uses: actions/setup-node@v6
      with:
        node-version: lts/*
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run changed Playwright tests
      run: npx playwright test --only-changed=$GITHUB_BASE_REF
      if: github.event_name == 'pull_request'
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v5
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

Docker

我们有一个预构建的 Docker 镜像，可以直接使用，也可以作为更新现有 Docker 配置的参考。请确保遵循推荐的 Docker 配置以确保最佳性能。

🌐 We have a pre-built Docker image which can either be used directly or as a reference to update your existing Docker definitions. Make sure to follow the Recommended Docker Configuration to ensure the best performance.

Azure 管道

🌐 Azure Pipelines

对于 Windows 或 macOS 代理，无需额外配置，只需安装 Playwright 并运行测试即可。

🌐 For Windows or macOS agents, no additional configuration is required, just install Playwright and run your tests.

对于 Linux 代理，你可以使用 我们的 Docker 容器 来支持 Azure Pipelines 运行容器化作业。或者，你可以使用 命令行工具 来安装所有必要的依赖。

🌐 For Linux agents, you can use our Docker container with Azure Pipelines support running containerized jobs. Alternatively, you can use Command line tools to install all necessary dependencies.

要运行 Playwright 测试，请使用此管道任务：

🌐 For running the Playwright tests use this pipeline task:

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: UseNode@1
  inputs:
    version: '22'
  displayName: 'Install Node.js'
- script: npm ci
  displayName: 'npm ci'
- script: npx playwright install --with-deps
  displayName: 'Install Playwright browsers'
- script: npx playwright test
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'

使用 Azure Pipelines 上传 Playwright 报告文件夹

🌐 Uploading playwright-report folder with Azure Pipelines

如果任意 Playwright 测试失败，这将导致管道运行失败。如果你还想将测试结果与 Azure DevOps 集成，可以像这样使用任务 PublishTestResults ：

🌐 This will make the pipeline run fail if any of the playwright tests fails. If you also want to integrate the test results with Azure DevOps, use the task PublishTestResults task like so:

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: UseNode@1
  inputs:
    version: '22'
  displayName: 'Install Node.js'

- script: npm ci
  displayName: 'npm ci'
- script: npx playwright install --with-deps
  displayName: 'Install Playwright browsers'
- script: npx playwright test
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'
- task: PublishTestResults@2
  displayName: 'Publish test results'
  inputs:
    searchFolder: 'test-results'
    testResultsFormat: 'JUnit'
    testResultsFiles: 'e2e-junit-results.xml'
    mergeTestResults: true
    failTaskOnFailedTests: true
    testRunTitle: 'My End-To-End Tests'
  condition: succeededOrFailed()
- task: PublishPipelineArtifact@1
  inputs:
    targetPath: playwright-report
    artifact: playwright-report
    publishLocation: 'pipeline'
  condition: succeededOrFailed()

注意：需要通过相应方式配置 JUnit 报告器

🌐 Note: The JUnit reporter needs to be configured accordingly via

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['junit', { outputFile: 'test-results/e2e-junit-results.xml' }]],
});

在 playwright.config.ts 中。

🌐 in playwright.config.ts.

Azure Pipelines（分片）

🌐 Azure Pipelines (sharded)

trigger:
- main

pool:
  vmImage: ubuntu-latest

strategy:
  matrix:
    chromium-1:
      project: chromium
      shard: 1/3
    chromium-2:
      project: chromium
      shard: 2/3
    chromium-3:
      project: chromium
      shard: 3/3
    firefox-1:
      project: firefox
      shard: 1/3
    firefox-2:
      project: firefox
      shard: 2/3
    firefox-3:
      project: firefox
      shard: 3/3
    webkit-1:
      project: webkit
      shard: 1/3
    webkit-2:
      project: webkit
      shard: 2/3
    webkit-3:
      project: webkit
      shard: 3/3
steps:
- task: UseNode@1
  inputs:
    version: '22'
  displayName: 'Install Node.js'

- script: npm ci
  displayName: 'npm ci'
- script: npx playwright install --with-deps
  displayName: 'Install Playwright browsers'
- script: npx playwright test --project=$(project) --shard=$(shard)
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'

Azure Pipelines（容器化）

🌐 Azure Pipelines (containerized)

trigger:
- main

pool:
  vmImage: ubuntu-latest
container: mcr.microsoft.com/playwright:v1.58.0-noble

steps:
- task: UseNode@1
  inputs:
    version: '22'
  displayName: 'Install Node.js'

- script: npm ci
  displayName: 'npm ci'
- script: npx playwright test
  displayName: 'Run Playwright tests'
  env:
    CI: 'true'

CircleCI

在 CircleCI 上运行 Playwright 与在 GitHub Actions 上运行非常相似。为了指定预构建的 Playwright Docker 镜像，只需在配置中将代理定义修改为 docker:，如下所示：

🌐 Running Playwright on CircleCI is very similar to running on GitHub Actions. In order to specify the pre-built Playwright Docker image, simply modify the agent definition with docker: in your config like so:

executors:
  pw-noble-development:
    docker:
      - image: mcr.microsoft.com/playwright:v1.58.0-noble

注意：在使用 Docker 代理定义时，你是在指定 Playwright 运行的资源类别为“中等”等级 这里。Playwright 的默认行为是将工作进程数设置为检测到的核心数（对于中等等级为 2）。将工作进程数设置为超过此数量会导致不必要的超时和失败。

🌐 Note: When using the docker agent definition, you are specifying the resource class of where playwright runs to the 'medium' tier here. The default behavior of Playwright is to set the number of workers to the detected core count (2 in the case of the medium tier). Overriding the number of workers to greater than this number will cause unnecessary timeouts and failures.

CircleCI 中的分片

🌐 Sharding in CircleCI

CircleCI 中的分片从 0 开始索引，这意味着你需要覆盖默认的并行 ENV 变量。以下示例演示了如何通过将 1 添加到 CIRCLE_NODE_INDEX 传递给 --shard CLI 参数，在 CircleCI 并行度为 4 的情况下运行 Playwright。

🌐 Sharding in CircleCI is indexed with 0 which means that you will need to override the default parallelism ENV VARS. The following example demonstrates how to run Playwright with a CircleCI Parallelism of 4 by adding 1 to the CIRCLE_NODE_INDEX to pass into the --shard cli arg.

  playwright-job-name:
    executor: pw-noble-development
    parallelism: 4
    steps:
      - run: SHARD="$((${CIRCLE_NODE_INDEX}+1))"; npx playwright test --shard=${SHARD}/${CIRCLE_NODE_TOTAL}

Jenkins

Jenkins 支持用于管道的 Docker 代理。使用 Playwright Docker 镜像 在 Jenkins 上运行测试。

🌐 Jenkins supports Docker agents for pipelines. Use the Playwright Docker image to run tests on Jenkins.

pipeline {
   agent { docker { image 'mcr.microsoft.com/playwright:v1.58.0-noble' } }
   stages {
      stage('e2e-tests') {
         steps {
            sh 'npm ci'
            sh 'npx playwright test'
         }
      }
   }
}

Bitbucket 管道

🌐 Bitbucket Pipelines

Bitbucket Pipelines 可以使用公共 Docker 镜像作为构建环境。要在 Bitbucket 上运行 Playwright 测试，请使用我们的公共 Docker 镜像（查看 Dockerfile）。

🌐 Bitbucket Pipelines can use public Docker images as build environments. To run Playwright tests on Bitbucket, use our public Docker image (see Dockerfile).

image: mcr.microsoft.com/playwright:v1.58.0-noble

GitLab CI

要在 GitLab 上运行 Playwright 测试，请使用我们的公共 Docker 镜像（查看 Dockerfile）。

🌐 To run Playwright tests on GitLab, use our public Docker image (see Dockerfile).

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.58.0-noble
  script:
  ...

分片

🌐 Sharding

GitLab CI 支持使用 parallel 关键字在多个作业之间分片测试。测试作业将被拆分为多个同时运行的小作业。并行作业的名称按顺序从 job_name 1/N 到 job_name N/N。

🌐 GitLab CI supports sharding tests between multiple jobs using the parallel keyword. The test job will be split into multiple smaller jobs that run in parallel. Parallel jobs are named sequentially from job_name 1/N to job_name N/N.

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.58.0-noble
  parallel: 7
  script:
    - npm ci
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

GitLab CI 还支持使用 parallel:matrix 选项在多个作业之间进行测试分片。测试作业将在单个流水线中并行运行多次，但每个作业实例的变量值不同。在下面的示例中，我们有 2 个 PROJECT 值和 10 个 SHARD 值，总共需要运行 20 个作业。

🌐 GitLab CI also supports sharding tests between multiple jobs using the parallel:matrix option. The test job will run multiple times in parallel in a single pipeline, but with different variable values for each instance of the job. In the example below, we have 2 PROJECT values and 10 SHARD values, resulting in a total of 20 jobs to be run.

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.58.0-noble
  parallel:
    matrix:
      - PROJECT: ['chromium', 'webkit']
        SHARD: ['1/10', '2/10', '3/10', '4/10', '5/10', '6/10', '7/10', '8/10', '9/10', '10/10']
  script:
    - npm ci
    - npx playwright test --project=$PROJECT --shard=$SHARD

谷歌云构建

🌐 Google Cloud Build

要在 Google Cloud Build 上运行 Playwright 测试，可以使用我们的公开 Docker 镜像（[参见 Dockerfile]（./docker.mdx））。

🌐 To run Playwright tests on Google Cloud Build, use our public Docker image (see Dockerfile).

steps:
- name: mcr.microsoft.com/playwright:v1.58.0-noble
  script: 
  ...
  env:
  - 'CI=true'

无人机

🌐 Drone

要在 Drone 上运行 Playwright 测试，请使用我们的公共 Docker 镜像（查看 Dockerfile）。

🌐 To run Playwright tests on Drone, use our public Docker image (see Dockerfile).

kind: pipeline
name: default
type: docker

steps:
  - name: test
    image: mcr.microsoft.com/playwright:v1.58.0-noble
    commands:
      - npx playwright test

缓存浏览器

🌐 Caching browsers

不建议缓存浏览器二进制文件，因为恢复缓存所需的时间与下载二进制文件的时间相当。尤其是在 Linux 系统下，需要安装 操作系统依赖，这些是无法缓存的。

🌐 Caching browser binaries is not recommended, since the amount of time it takes to restore the cache is comparable to the time it takes to download the binaries. Especially under Linux, operating system dependencies need to be installed, which are not cacheable.

如果你仍然希望在 CI 运行之间缓存浏览器二进制文件，请在你的 CI 配置中缓存 这些目录，并使用 Playwright 版本的哈希值。

🌐 If you still want to cache the browser binaries between CI runs, cache these directories in your CI configuration, against a hash of the Playwright version.

调试浏览器启动

🌐 Debugging browser launches

Playwright 支持 DEBUG 环境变量在执行期间输出调试日志。将其设置为 pw:browser 对调试 Error: Failed to launch browser 错误很有帮助。

🌐 Playwright supports the DEBUG environment variable to output debug logs during execution. Setting it to pw:browser is helpful while debugging Error: Failed to launch browser errors.

DEBUG=pw:browser npx playwright test

运行有头

🌐 Running headed

默认情况下，Playwright 会以无头模式启动浏览器。请参阅我们的《运行测试》指南，了解如何以有头模式运行测试。

🌐 By default, Playwright launches browsers in headless mode. See in our Running tests guide how to run tests in headed mode.

在 Linux 代理上，带界面的执行需要安装 Xvfb。我们的 Docker 镜像 和 GitHub Action 已预安装 Xvfb。要在带界面模式下使用 Xvfb 运行浏览器，请在实际命令前添加 xvfb-run。

🌐 On Linux agents, headed execution requires Xvfb to be installed. Our Docker image and GitHub Action have Xvfb pre-installed. To run browsers in headed mode with Xvfb, add xvfb-run before the actual command.

xvfb-run npx playwright test