持續整合

簡介

Playwright 測試可以在 CI 環境中執行。我們已經為常見的 CI 提供者建立了範例配置。

3 步驟讓你的測試在 CI 上執行:

確保 CI 代理可以執行瀏覽器: 使用我們的 Docker 映像在 Linux 代理中或使用 CLI 安裝你的相依套件。

安裝 Playwright:

# 安裝 NPM 套件
npm ci

# 安裝 Playwright 瀏覽器和相依套件
npx playwright install --with-deps

執行你的測試:
```
npx playwright test
```

Workers

我們建議在 CI 環境中將 workers 設定為 "1" 以優先考慮穩定性和可重現性。順序執行測試可確保每個測試獲得完整的系統資源，避免潛在的衝突。然而，如果您有強大的自託管 CI 系統，您可以啟用 parallel 測試。對於更廣泛的平行化，考慮 sharding - 將測試分佈在多個 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 configurations

命令列工具可以用來在 CI 中安裝所有作業系統相依套件。

GitHub Actions

在 push/pull_request

測試將在推送或拉取請求至 main/master 分支時執行。工作流程會安裝所有相依套件，安裝 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: 18
    - 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

On push/pull_request (sharded)

GitHub Actions 支援在多個工作之間分片測試。查看我們的分片文件以了解更多關於分片的資訊，並查看如何配置工作以在多台機器上執行測試以及如何合併 HTML 報告的GitHub actions 範例。

通過容器

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.47.0-jammy
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - name: Install dependencies
        run: npm ci
      - name: Run your tests
        run: npx playwright test
        env:
          HOME: /root

部署

這將在 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: 18
    - 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 }}

快速失敗

大型測試套件可能需要很長時間才能執行。通過使用 --only-changed 旗標執行初步測試運行，你可以先執行可能會失敗的測試文件。這將為你提供更快的反饋迴圈，並在處理 Pull Requests 時略微降低 CI 消耗。為了檢測受你的更改集影響的測試文件，--only-changed 會分析你的套件的相依圖。這是一種啟發式方法，可能會漏掉一些測試，因此在初步測試運行後，始終執行完整的測試套件是很重要的。

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: 18
    - 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 docs。
啟動 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 reporter 需要通過以下方式進行相應配置

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

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

在 playwright.config.ts。

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: 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 (containerized)

trigger:
- main

pool:
  vmImage: ubuntu-latest
container: mcr.microsoft.com/playwright:v1.47.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

執行 Playwright 在 CircleCI 上與在 GitHub Actions 上非常相似。為了指定預建的 Playwright Docker image，只需在你的配置中用 docker: 修改代理定義，如下所示:

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

注意: 當使用 docker 代理定義時，你正在將 Playwright 執行的資源類別指定為 'medium' 級別此處。Playwright 的預設行為是將工作者數量設置為檢測到的核心數量（在 medium 級別的情況下為 2）。將工作者數量覆蓋設定為大於這個數字將導致不必要的超時和失敗。

在 CircleCI 中分片

在 CircleCI 中的分片是從 0 開始索引的，這意味著你需要覆寫預設的平行處理環境變數。以下範例展示了如何通過將 CIRCLE_NODE_INDEX 加 1 來傳遞到 --shard cli 參數，以 4 的 CircleCI 平行處理執行 Playwright。

  playwright-job-name:
    executor: pw-jammy-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.47.0-noble' } }
   stages {
      stage('e2e-tests') {
         steps {
            sh 'npm ci'
            sh 'npx playwright test'
         }
      }
   }
}

Bitbucket Pipelines

Bitbucket Pipelines 可以使用公共 Docker images as build environments。要在 Bitbucket 上執行 Playwright 測試，請使用我們的公共 Docker image (see Dockerfile)。

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

GitLab CI

要在 GitLab 上執行 Playwright 測試，請使用我們的公共 Docker 映像(see Dockerfile)。

stages:
  - test

tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.47.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.47.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.47.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 映像(see Dockerfile)。

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

Drone

要在 Drone 上執行 Playwright 測試，請使用我們的公開 Docker 映像檔(see Dockerfile)。

kind: pipeline
name: default
type: docker

steps:
  - name: test
    image: mcr.microsoft.com/playwright:v1.47.0-jammy
    commands:
      - npx playwright test

快取瀏覽器

快取瀏覽器二進位檔案並不建議，因為還原快取所需的時間與下載二進位檔案所需的時間相當。特別是在 Linux 下，需要安裝作業系統相依套件，這些是無法快取的。

如果你仍然想在 CI 執行之間快取瀏覽器二進位檔，請在你的 CI 設定中，根據 Playwright 版本的雜湊值快取這些目錄。

偵錯瀏覽器啟動

Playwright 支援 DEBUG 環境變數來在執行期間輸出除錯日誌。將其設置為 pw:browser 在除錯 Error: Failed to launch browser 錯誤時非常有幫助。

DEBUG=pw:browser npx playwright test

執行有頭瀏覽器 (Running headed)

預設情況下，Playwright 會在無頭模式下啟動瀏覽器。請參閱我們的執行測試指南，了解如何在有頭模式下執行測試。

在 Linux 代理上，帶頭執行需要安裝 Xvfb。我們的 Docker image 和 GitHub Action 已經預先安裝了 Xvfb。要在帶頭模式下使用 Xvfb 執行瀏覽器，請在實際命令前添加 xvfb-run。

xvfb-run npx playwright test

簡介​

Workers​

CI configurations​

GitHub Actions​

在 push/pull_request​

On push/pull_request (sharded)​

通過容器​

部署​

快速失敗​

Docker​

Azure Pipelines​

使用 Azure Pipelines 上傳 playwright-report 資料夾​

Azure Pipelines (sharded)​

Azure Pipelines (containerized)​

CircleCI​

在 CircleCI 中分片​

Jenkins​

Bitbucket Pipelines​

GitLab CI​

分片​

Google Cloud Build​

Drone​

快取瀏覽器​

偵錯瀏覽器啟動​

執行有頭瀏覽器 (Running headed)​

簡介