测试配置

简介

Playwright 提供了多种选项来配置测试的运行方式。你可以在配置文件中指定这些选项。请注意，测试运行器的选项是顶级配置，不要将它们放在 use 部分中。

基础配置

以下是一些最常用的配置选项。

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

export default defineConfig({
  // 在相对于此配置文件的"tests"目录中查找测试文件
  testDir: 'tests',

  // 并行运行所有测试
  fullyParallel: true,

  // 如果在CI环境中意外遗留了test.only，则构建失败
  forbidOnly: !!process.env.CI,

  // 仅在CI环境中重试
  retries: process.env.CI ? 2 : 0,

  // 在CI环境中禁用并行测试
  workers: process.env.CI ? 1 : undefined,

  // 使用的报告器
  reporter: 'html',

  use: {
    // 在类似`await page.goto('/')`的操作中使用的基础URL
    baseURL: 'http://localhost:3000',

    // 在重试失败测试时收集追踪信息
    trace: 'on-first-retry',
  },
  // 为主要浏览器配置项目
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
  // 在开始测试前运行本地开发服务器
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

选项	描述
testConfig.forbidOnly	如果存在标记为`test.only`的测试是否报错退出。在CI环境中很有用。
testConfig.fullyParallel	让所有文件中的所有测试并行运行。详见并行测试和分片测试。
testConfig.projects	在多种配置或多个浏览器中运行测试
testConfig.reporter	使用的报告器。查看测试报告器了解可用报告器。
testConfig.retries	每个测试的最大重试次数。详见测试重试。
testConfig.testDir	包含测试文件的目录。
testConfig.use	使用`use{}`的选项
testConfig.webServer	要在测试期间启动服务器，使用`webServer`选项
testConfig.workers	用于并行化测试的最大并发工作进程数。也可以设置为逻辑CPU核心数的百分比，例如`'50%'`。详见并行测试和分片测试。

测试过滤

通过 glob 模式或正则表达式过滤测试用例。

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

export default defineConfig({
  // 用于忽略测试文件的 glob 模式或正则表达式
  testIgnore: '*test-assets',

  // 匹配测试文件的 glob 模式或正则表达式
  testMatch: '*todo-tests/*.spec.ts',
});

选项	描述
testConfig.testIgnore	在查找测试文件时应忽略的 glob 模式或正则表达式。例如 `'*test-assets'`
testConfig.testMatch	匹配测试文件的 glob 模式或正则表达式。例如 `'todo-tests/.spec.ts'`。默认情况下，Playwright 会运行 `.*(test\|spec).(js\|ts\|mjs)` 文件。

高级配置

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

export default defineConfig({
  // 测试产物（如截图、视频、追踪记录等）的存放目录
  outputDir: 'test-results',

  // 全局设置文件的路径
  globalSetup: require.resolve('./global-setup'),

  // 全局清理文件的路径
  globalTeardown: require.resolve('./global-teardown'),

  // 每个测试用例的超时时间为30秒
  timeout: 30000,

});

选项	描述
testConfig.globalSetup	全局设置文件的路径。该文件会在所有测试前被加载并执行，必须导出一个单独的函数。
testConfig.globalTeardown	全局清理文件的路径。该文件会在所有测试后被加载并执行，必须导出一个单独的函数。
testConfig.outputDir	测试产物（如截图、视频、追踪记录等）的存放目录。
testConfig.timeout	Playwright 为每个测试强制设置超时时间，默认为30秒。测试函数、测试夹具和 beforeEach 钩子消耗的时间都计入测试超时。

Expect 选项

expect 断言库的配置选项。

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

export default defineConfig({
  expect: {
    // expect() 等待条件满足的最大时间
    timeout: 5000,

    toHaveScreenshot: {
      // 允许存在差异的像素数量，默认未设置
      maxDiffPixels: 10,
    },

    toMatchSnapshot: {
      // 允许存在差异的像素比例，范围在0到1之间
      maxDiffPixelRatio: 0.1,
    },
  },

});

选项	描述
testConfig.expect	默认情况下，类似 `expect(locator).toHaveText()` 这样的 Web优先断言有单独的5秒超时时间。这是 `expect()` 等待条件满足的最大时间。了解更多关于测试和expect超时以及如何为单个测试设置它们的信息。
expect(page).toHaveScreenshot()	`expect(locator).toHaveScreenshot()` 方法的配置选项。
expect(value).toMatchSnapshot()	`expect(locator).toMatchSnapshot()` 方法的配置选项。

简介​

基础配置​

测试过滤​

高级配置​

Expect 选项​

简介

基础配置

测试过滤

高级配置

Expect 选项