持续集成

简介

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

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

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

安装 Playwright:

# Install NPM packages
npm ci

# Install Playwright browsers and dependencies
npx playwright install --with-deps

运行你的测试:
```
npx playwright test
```

Workers

我们建议在 CI 环境中将 workers 设置为 "1"，以优先考虑稳定性和可重复性。顺序运行测试可确保每个测试获得完整的系统资源，避免潜在的冲突。但是，如果你拥有强大的自托管 CI 系统，则可以启用并行测试。为了更广泛的并行化，请考虑分片 - 将测试分布在多个 CI 作业中。

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 中安装所有操作系统依赖项。

GitHub Actions

在 push/pull_request 时

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

.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@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
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

在 push/pull_request 时 (分片)

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

通过容器

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.51.0-noble
      options: --user 1001
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Install dependencies
        run: npm ci
      - name: Run your tests
        run: npx playwright test

在部署时

这将在GitHub Deployment进入 success 状态后启动测试。Vercel 等服务使用此模式，因此你可以在其部署的环境中运行端到端测试。

.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@v4
    - uses: actions/setup-node@v4
      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 标志执行初步测试运行，你可以首先运行可能失败的测试文件。这将为你提供更快的反馈循环，并在处理 Pull Requests 时略微降低 CI 消耗。为了检测受你的变更集影响的测试文件，--only-changed 会分析你的套件的依赖关系图。这是一种启发式方法，可能会遗漏测试，因此重要的是，在初步测试运行后，你始终运行完整的测试套件。

.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@v4
      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@v4
      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@v4
      if: ${{ !cancelled() }}
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

Docker

我们有一个预构建的 Docker 镜像，可以直接使用，也可以作为更新现有 Docker 定义的参考。

建议配置

当使用 Chromium 时，也建议使用 --ipc=host。没有它，Chromium 可能会耗尽内存并崩溃。在Docker 文档中了解有关此选项的更多信息。
在启动 Chromium 时看到其他奇怪的错误？在本地开发时，尝试使用 docker run --cap-add=SYS_ADMIN 运行你的容器。
建议使用 --init Docker 标志或 dumb-init 以避免对 PID=1 的进程进行特殊处理。这是僵尸进程的常见原因。

Azure Pipelines

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

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

对于运行 Playwright 测试，请使用此管道任务

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'
  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-report 文件夹

如果任何 playwright 测试失败，这将使管道运行失败。如果你还想将测试结果与 Azure DevOps 集成，请使用 PublishTestResults 任务，如下所示

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'
  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 报告器需要通过以下方式进行相应配置

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

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

在 playwright.config.ts 中。

Azure Pipelines (分片)

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: NodeTool@0
  inputs:
    versionSpec: '18'
  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 (容器化)

trigger:
- main

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

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'
  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: 修改代理定义，如下所示

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

注意：当使用 docker 代理定义时，你正在指定 playwright 运行的资源类到 'medium' 层级这里。Playwright 的默认行为是将 workers 的数量设置为检测到的核心数（在 medium 层级的情况下为 2）。将 workers 的数量覆盖为大于此数字将导致不必要的超时和失败。

CircleCI 中的分片

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

  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 上运行测试。

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

Bitbucket Pipelines

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

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

GitLab CI

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

stages:
  - test

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

分片

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

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.51.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 个作业。

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.51.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）。

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

Drone

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

kind: pipeline
name: default
type: docker

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

缓存浏览器

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

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

调试浏览器启动

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

DEBUG=pw:browser npx playwright test

以 Headed 模式运行

默认情况下，Playwright 以 headless 模式启动浏览器。请参阅我们的运行测试指南，了解如何在 headed 模式下运行测试。

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

xvfb-run npx playwright test

简介​

Workers​

CI 配置​

GitHub Actions​

在 push/pull_request 时​

在 push/pull_request 时 (分片)​

通过容器​

在部署时​

Fail-Fast​

Docker​

Azure Pipelines​

使用 Azure Pipelines 上传 playwright-report 文件夹​

Azure Pipelines (分片)​

Azure Pipelines (容器化)​

CircleCI​

CircleCI 中的分片​

Jenkins​

Bitbucket Pipelines​

GitLab CI​

分片​

Google Cloud Build​

Drone​

缓存浏览器​

调试浏览器启动​

以 Headed 模式运行​

简介