TestConfig

Playwright 测试提供了许多选项来配置如何收集和执行测试，例如 timeout 或 testDir。这些选项在 TestConfig 对象中进行了描述，该对象位于配置文件中。此类型描述了配置文件的格式，要在运行时访问已解析的配置参数，请使用 FullConfig。

Playwright 测试支持同时运行多个测试项目。项目特定的选项应放在 testConfig.projects 中，但顶级 TestConfig 也可以定义所有项目共享的基本选项。

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

export default defineConfig({
  timeout: 30000,
  globalTimeout: 600000,
  reporter: 'list',
  testDir: './tests',
});

属性

构建

新增于：v1.35

testConfig.build

Playwright 编译器配置。

用法

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

export default defineConfig({
  build: {
    external: ['**/*bundle.js'],
  },
});

类型

对象
- external 数组<字符串> （可选）
  
  要从编译中排除的路径，表示为全局模式列表。通常，您测试中使用的繁重的 JS 包都列在此处。

预期

新增于：v1.10

testConfig.expect

expect 断言库的配置。了解有关各种超时的更多信息。

用法

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

export default defineConfig({
  expect: {
    timeout: 10000,
    toMatchSnapshot: {
      maxDiffPixels: 10,
    },
  },
});

类型

对象
- timeout 数字 （可选）
  
  异步 expect 匹配器的默认超时时间（毫秒），默认为 5000 毫秒。
- toHaveScreenshot 对象 （可选）
  - animations "allow" | "disabled" （可选）
    
    请参阅动画中的 page.screenshot()。默认为 "disabled"。
  - caret "hide" | "initial" （可选）
    
    请参阅插入符号中的 page.screenshot()。默认为 "hide"。
  - maxDiffPixels 数字 （可选）
    
    可以不同的像素数量，默认为未设置。
  - maxDiffPixelRatio 数字 （可选）
    
    不同的像素与像素总数之间的可接受比率，介于 0 和 1 之间，默认为未设置。
  - scale "css" | "device" （可选）
    
    请参阅缩放中的 page.screenshot()。默认为 "css"。
  - stylePath 字符串 | 数组<字符串> （可选）
    
    请参阅样式中的 page.screenshot()。
  - threshold 数字 （可选）
    
    比较图像中相同像素之间可接受的感知颜色差异，范围从 0（严格）到 1（宽松）。"pixelmatch" 比较器计算 YIQ 色彩空间中的颜色差异，并将 threshold 值默认为 0.2。
  expect(page).toHaveScreenshot() 方法的配置。
- toMatchSnapshot 对象 （可选）
  - maxDiffPixels 数字 （可选）
    
    可以不同的像素数量，默认为未设置。
  - maxDiffPixelRatio 数字 （可选）
    
    不同的像素与像素总数之间的可接受比率，介于 0 和 1 之间，默认为未设置。
  - threshold 数字 （可选）
    
    比较图像中相同像素之间可接受的感知颜色差异，范围从 0（严格）到 1（宽松）。"pixelmatch" 比较器计算 YIQ 色彩空间中的颜色差异，并将 threshold 值默认为 0.2。
  expect(value).toMatchSnapshot() 方法的配置。
- toPass 对象 （可选）
  - intervals 数组<数字> （可选）
    
    toPass 方法的探测间隔（毫秒）。
  - timeout 数字 （可选）
    
    toPass 方法的超时时间（毫秒）。
  expect(value).toPass() 方法的配置。

禁止仅

新增于：v1.10

testConfig.forbidOnly

如果任何测试或组被标记为 test.only() 或 test.describe.only()，是否以错误退出。在 CI 上很有用。

用法

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

export default defineConfig({
  forbidOnly: !!process.env.CI,
});

类型

布尔值

完全并行

新增于：v1.20

testConfig.fullyParallel

Playwright 测试并行运行测试。为了实现这一点，它运行多个同时运行的工作进程。默认情况下，测试文件是并行运行的。单个文件中的测试按顺序在同一工作进程中运行。

您可以配置整个测试运行以使用此选项并发执行所有文件中的所有测试。

用法

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

export default defineConfig({
  fullyParallel: true,
});

类型

布尔值

全局设置

新增于：v1.10

testConfig.globalSetup

全局设置文件的路径。此文件将在所有测试之前被加载并运行。它必须导出一个接收 FullConfig 参数的单个函数。

了解有关全局设置和拆卸的更多信息。

用法

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

export default defineConfig({
  globalSetup: './global-setup',
});

类型

字符串

全局拆卸

新增于：v1.10

testConfig.globalTeardown

全局拆卸文件的路径。此文件将在所有测试之后被加载并运行。它必须导出一个单个函数。另请参阅 testConfig.globalSetup。

了解有关全局设置和拆卸的更多信息。

用法

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

export default defineConfig({
  globalTeardown: './global-teardown',
});

类型

字符串

全局超时

新增于：v1.10

testConfig.globalTimeout

整个测试套件可以运行的最长时间（毫秒）。零超时（默认值）禁用此行为。在 CI 上很有用，可以防止损坏的设置运行太长时间并浪费资源。了解有关各种超时的更多信息。

用法

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

export default defineConfig({
  globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
});

类型

数字

grep

新增于：v1.10

testConfig.grep

筛选器，仅运行标题与其中一个模式匹配的测试。例如，传递 grep: /cart/ 应该只运行标题中包含“cart”的测试。还可以在命令行中使用 -g 选项使用。正则表达式将针对由项目名称、测试文件名、test.describe 名称（如果有）、测试名称和测试标签（用空格分隔）组成的字符串进行测试，例如 chromium my-test.spec.ts my-suite my-test。

grep 选项也适用于标记测试。

用法

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

export default defineConfig({
  grep: /smoke/,
});

类型

正则表达式 | 数组<正则表达式>

grepInvert

新增于：v1.10

testConfig.grepInvert

筛选器，仅运行标题不与其中一个模式匹配的测试。这与 testConfig.grep 相反。还可以在命令行中使用 --grep-invert 选项使用。

grepInvert 选项也适用于标记测试。

用法

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

export default defineConfig({
  grepInvert: /manual/,
});

类型

正则表达式 | 数组<正则表达式>

忽略快照

新增于：v1.26

testConfig.ignoreSnapshots

是否跳过快照期望，例如 expect(value).toMatchSnapshot() 和 await expect(page).toHaveScreenshot()。

用法

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

export default defineConfig({
  ignoreSnapshots: !process.env.CI,
});

类型

布尔值

最大失败次数

新增于：v1.10

testConfig.maxFailures

整个测试套件运行的最大测试失败次数。达到此数字后，测试将停止并以错误退出。设置为零（默认值）禁用此行为。

也可以通过命令行使用 --max-failures 和 -x 选项。

用法

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

export default defineConfig({
  maxFailures: process.env.CI ? 1 : 0,
});

类型

数字

元数据

新增于：v1.10

testConfig.metadata

将直接序列化为 JSON 并放入测试报告中的元数据。

用法

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

export default defineConfig({
  metadata: 'acceptance tests',
});

类型

元数据

名称

新增于：v1.10

testConfig.name

配置名称在报告中和测试执行期间可见，除非被 testProject.name 覆盖。

用法

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

export default defineConfig({
  name: 'acceptance tests',
});

类型

字符串

输出目录

新增于：v1.10

testConfig.outputDir

测试执行期间创建的文件的输出目录。默认为 <package.json-directory>/test-results。

用法

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

export default defineConfig({
  outputDir: './test-results',
});

类型

字符串

详情

此目录在开始时会被清空。运行测试时，会在 testConfig.outputDir 内部创建一个唯一的子目录，以确保并行运行的测试不会发生冲突。可以通过 testInfo.outputDir 和 testInfo.outputPath() 访问此目录。

以下是一个使用 testInfo.outputPath() 创建临时文件的示例。

import { test, expect } from '@playwright/test';
import fs from 'fs';

test('example test', async ({}, testInfo) => {
  const file = testInfo.outputPath('temporary-file.txt');
  await fs.promises.writeFile(file, 'Put some data to the file', 'utf8');
});

保留输出

新增于：v1.10

testConfig.preserveOutput

是否保留 testConfig.outputDir 中的测试输出。默认为 'always'。

'always' - 保留所有测试的输出；
'never' - 不保留任何测试的输出；
'failures-only' - 仅保留失败测试的输出。

用法

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

export default defineConfig({
  preserveOutput: 'always',
});

类型

"always" | "never" | "failures-only"

项目

新增于：v1.10

testConfig.projects

Playwright Test 支持同时运行多个测试项目。有关更多信息，请参阅 TestProject。

用法

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

export default defineConfig({
  projects: [
    { name: 'chromium', use: devices['Desktop Chrome'] }
  ]
});

类型

Array<TestProject>

静默

新增于：v1.10

testConfig.quiet

是否抑制测试的标准输入输出和标准错误输出。

用法

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

export default defineConfig({
  quiet: !!process.env.CI,
});

类型

布尔值

重复每个

新增于：v1.10

testConfig.repeatEach

重复每个测试的次数，用于调试不稳定的测试。

用法

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

export default defineConfig({
  repeatEach: 3,
});

类型

数字

报告缓慢测试

新增于：v1.10

testConfig.reportSlowTests

是否报告缓慢的测试文件。传递 null 以禁用此功能。

用法

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

export default defineConfig({
  reportSlowTests: null,
});

类型

null | Object
- max 数字
  
  要报告的缓慢测试文件的最大数量。默认为 5。
- threshold 数字
  
  被视为缓慢的测试持续时间（毫秒）。默认为 15 秒。

详情

持续时间超过 threshold 毫秒的测试文件被视为缓慢，并且会报告最慢的测试文件，最多不超过 max 个。将 max 设为零将报告所有超过阈值的测试文件。

报告程序

新增于：v1.10

testConfig.reporter

要使用的报告程序列表。每个报告程序可以是

一个内置的报告程序名称，例如 'list' 或 'json'。
一个模块名称，例如 'my-awesome-reporter'。
一个到报告程序的相对路径，例如 './reporters/my-awesome-reporter.js'。

可以在元组中将选项传递给报告程序，例如 ['json', { outputFile: './report.json' }]。

在报告程序指南中了解更多信息。

用法

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

export default defineConfig({
  reporter: 'line',
});

类型

字符串 | Array<Object> | "list" | "dot" | "line" | "github" | "json" | "junit" | "null" | "html"
- 0 字符串
  
  报告程序名称或模块或文件路径
- 1 Object
  
  如果存在，则为包含报告程序选项的对象

尊重 Git 忽略

新增于：v1.45

testConfig.respectGitIgnore

在搜索测试文件时是否跳过 .gitignore 中的条目。默认情况下，如果既没有显式指定 testConfig.testDir 也没有显式指定 testProject.testDir，Playwright 将忽略与 .gitignore 条目匹配的任何测试文件。

用法

testConfig.respectGitIgnore

类型

布尔值

重试

新增于：v1.10

testConfig.retries

给失败测试提供的最大重试次数。默认情况下，失败的测试不会重试。详细了解测试重试。

用法

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

export default defineConfig({
  retries: 2,
});

类型

数字

分片

新增于：v1.10

testConfig.shard

对测试进行分片并仅执行选定的分片。以基于一的格式指定，例如 { total: 5, current: 2 }。

详细了解 Playwright Test 的并行处理和分片。

用法

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

export default defineConfig({
  shard: { total: 10, current: 3 },
});

类型

null | Object
- current 数字
  
  要执行的分片的索引，基于一。
- total 数字
  
  分片的总数。

快照路径模板

新增于：v1.28

testConfig.snapshotPathTemplate

此选项配置一个模板，该模板控制由 expect(page).toHaveScreenshot() 和 expect(value).toMatchSnapshot() 生成的快照的位置。

用法

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

export default defineConfig({
  testDir: './tests',
  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
});

类型

字符串

详情

该值可能包含一些“标记”，这些标记将在测试执行期间替换为实际值。

考虑以下文件结构

playwright.config.ts
tests/
└── page/
    └── page-click.spec.ts

以及以下使用 toHaveScreenshot() 调用的 page-click.spec.ts

page-click.spec.ts
import { test, expect } from '@playwright/test';

test.describe('suite', () => {
  test('test should work', async ({ page }) => {
    await expect(page).toHaveScreenshot(['foo', 'bar', 'baz.png']);
  });
});

支持的标记列表

{arg} - 不带扩展名的相对快照路径。这些来自传递给 toHaveScreenshot() 和 toMatchSnapshot() 调用的参数；如果未带参数调用，则将是自动生成的快照名称。
- 值：foo/bar/baz
{ext} - 快照扩展名（带点）
- 值：.png
{platform} - process.platform 的值。
{projectName} - 项目的文件系统清理名称（如果有）。
- 值：''（空字符串）。
{snapshotDir} - 项目的 testConfig.snapshotDir。
- 值：/home/playwright/tests（由于配置中未提供 snapshotDir，因此默认为 testDir）
{testDir} - 项目的 testConfig.testDir。
- 值：/home/playwright/tests（绝对路径是由于 testDir 相对于包含配置文件的目录解析）
{testFileDir} - 从 testDir 到测试文件的相对路径中的目录。
- 值：page
{testFileName} - 带扩展名的测试文件名。
- 值：page-click.spec.ts
{testFilePath} - 从 testDir 到测试文件的相对路径
- 值：page/page-click.spec.ts
{testName} - 文件系统清理的测试标题，包括父级描述但不包括文件名。
- 值：suite-test-should-work

每个标记前面可以有一个字符，该字符仅在该标记具有非空值时使用。

考虑以下配置

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

export default defineConfig({
  snapshotPathTemplate: '__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
  testMatch: 'example.spec.ts',
  projects: [
    { use: { browserName: 'firefox' } },
    { name: 'chromium', use: { browserName: 'chromium' } },
  ],
});

在此配置中

第一个项目没有名称，因此其快照将存储在 <configDir>/__screenshots__/example.spec.ts/... 中。
第二个项目有名称，因此其快照将存储在 <configDir>/__screenshots__/chromium/example.spec.ts/.. 中。
由于 snapshotPathTemplate 解析为相对路径，因此它将相对于 configDir 解析。
正斜杠 "/" 可在任何平台上用作路径分隔符。

测试目录

新增于：v1.10

testConfig.testDir

将递归扫描以查找测试文件的目录。默认为配置文件所在的目录。

用法

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

export default defineConfig({
  testDir: './tests/playwright',
});

类型

字符串

测试忽略

新增于：v1.10

testConfig.testIgnore

与这些模式之一匹配的文件不会作为测试文件执行。匹配针对绝对文件路径执行。字符串被视为全局模式。

例如，'**/test-assets/**' 将忽略 test-assets 目录中的所有文件。

用法

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

export default defineConfig({
  testIgnore: '**/test-assets/**',
});

类型

字符串 | RegExp | Array<字符串 | RegExp>

测试匹配

新增于：v1.10

testConfig.testMatch

仅与这些模式之一匹配的文件才会作为测试文件执行。匹配针对绝对文件路径执行。字符串被视为全局模式。

默认情况下，Playwright 查找与以下全局模式匹配的文件：**/*.@(spec|test).?(c|m)[jt]s?(x)。这意味着具有 ".test" 或 ".spec" 后缀的 JavaScript 或 TypeScript 文件，例如 login-screen.wrong-credentials.spec.ts。

用法

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

export default defineConfig({
  testMatch: /.*\.e2e\.js/,
});

类型

字符串 | RegExp | Array<字符串 | RegExp>

超时

新增于：v1.10

testConfig.timeout

每个测试的超时时间（毫秒）。默认为 30 秒。

这是所有测试的基本超时时间。此外，每个测试都可以使用 test.setTimeout() 配置其自己的超时时间。详细了解各种超时时间。

用法

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

export default defineConfig({
  timeout: 5 * 60 * 1000,
});

类型

数字

更新快照

新增于：v1.10

testConfig.updateSnapshots

是否使用测试运行生成的实际结果更新预期的快照。默认为 'missing'。

'all' - 执行的所有测试都将更新不匹配的快照。匹配的快照将不会更新。
'none' - 没有快照被更新。
'missing' - 创建缺失的快照，例如在编写新测试并首次运行它时。这是默认设置。

详细了解快照。

用法

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

export default defineConfig({
  updateSnapshots: 'missing',
});

类型

"all" | "none" | "missing"

使用

新增于：v1.10

testConfig.use

所有测试的全局选项，例如 testOptions.browserName。了解更多关于配置并查看可用选项。

用法

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

export default defineConfig({
  use: {
    browserName: 'chromium',
  },
});

类型

TestOptions

webServer

新增于：v1.10

testConfig.webServer

在测试期间启动一个（或多个）开发 Web 服务器。

用法

playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
  webServer: {
    command: 'npm run start',
    url: 'http://127.0.0.1:3000',
    timeout: 120 * 1000,
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: 'https://127.0.0.1:3000/',
  },
});

现在您可以在导航页面时使用相对路径。

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

test('test', async ({ page }) => {
  // This will result in https://127.0.0.1:3000/foo
  await page.goto('/foo');
});

可以启动多个 Web 服务器（或后台进程）。

playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
  webServer: [
    {
      command: 'npm run start',
      url: 'http://127.0.0.1:3000',
      timeout: 120 * 1000,
      reuseExistingServer: !process.env.CI,
    },
    {
      command: 'npm run backend',
      url: 'http://127.0.0.1:3333',
      timeout: 120 * 1000,
      reuseExistingServer: !process.env.CI,
    }
  ],
  use: {
    baseURL: 'http://127.0.0.1:3000',
  },
});

类型

对象 | 数组<对象>
- command 字符串
  
  启动的 Shell 命令，例如 npm run start。
- cwd 字符串 (可选)
  
  生成进程的当前工作目录，默认为配置文件所在的目录。
- env 对象<字符串, 字符串> (可选)
  
  要为命令设置的环境变量，默认情况下为 process.env。
- ignoreHTTPSErrors 布尔值 (可选)
  
  是否在获取 url 时忽略 HTTPS 错误。默认为 false。
- port 数字 (可选)
  
  您期望 http 服务器出现在的端口。它会等待直到它接受连接。应指定 port 或 url 之一。
- reuseExistingServer 布尔值 (可选)
  
  如果为真，则在可用时将重用 port 或 url 上的现有服务器。如果在该 port 或 url 上没有服务器正在运行，它将运行命令以启动一个新服务器。如果为 false，则如果现有进程正在侦听 port 或 url，它将抛出错误。这通常应该设置为 !process.env.CI 以在本地运行测试时允许本地开发服务器。
- stdout "pipe" | "ignore" (可选)
  
  如果为 "pipe"，它将命令的 stdout 管道到进程 stdout。如果为 "ignore"，它将忽略命令的 stdout。默认为 "ignore"。
- stderr "pipe" | "ignore" (可选)
  
  是否将命令的 stderr 管道到进程 stderr 或忽略它。默认为 "pipe"。
- timeout 数字 （可选）
  
  等待进程启动并在毫秒内可用的时间长度。默认为 60000。
- url 字符串 (可选)
  
  您期望 http 服务器上的 URL 在服务器准备好接受连接时返回 2xx、3xx、400、401、402 或 403 状态代码。重定向 (3xx 状态代码) 将被跟踪，并检查新位置。应指定 port 或 url 之一。

详情

如果指定了端口，Playwright Test 将等待它在 127.0.0.1 或 ::1 上可用，然后再运行测试。如果指定了 url，Playwright Test 将等待 URL 返回 2xx、3xx、400、401、402 或 403 状态代码，然后再运行测试。

对于持续集成，您可能希望使用 reuseExistingServer: !process.env.CI 选项，该选项不会在 CI 上使用现有服务器。要查看 stdout，您可以设置 DEBUG=pw:webserver 环境变量。

port（但不是 url）将作为 testOptions.baseURL 传递给 Playwright。例如，端口 8080 生成的 baseURL 等于 https://127.0.0.1:8080。如果 webServer 指定为数组，则必须显式配置 baseURL（即使它只有一个条目）。

注意

建议在配置中指定 testOptions.baseURL，以便测试可以使用相对 URL。

workers

新增于：v1.10

testConfig.workers

用于并行化测试的并发工作进程的最大数量。也可以设置为逻辑 CPU 内核的百分比，例如 '50%'。

Playwright Test 使用工作进程来运行测试。始终至少有一个工作进程，但可以使用更多进程来加快测试执行速度。

默认为逻辑 CPU 内核数量的一半。了解更多关于 Playwright Test 的并行处理和分片。

用法

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

export default defineConfig({
  workers: 3,
});

类型

数字 | 字符串

已弃用

snapshotDir

新增于：v1.10

testConfig.snapshotDir

不建议使用

使用 testConfig.snapshotPathTemplate 配置快照路径。

相对于配置文件的基目录，用于使用 toMatchSnapshot 创建的快照文件。默认为 testConfig.testDir。

用法

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

export default defineConfig({
  snapshotDir: './snapshots',
});

类型

字符串

详情

每个测试的目录可以通过 testInfo.snapshotDir 和 testInfo.snapshotPath() 访问。

此路径将作为每个测试文件快照目录的基目录。将 snapshotDir 设置为 'snapshots'，testInfo.snapshotDir 将解析为 snapshots/a.spec.js-snapshots。

属性​

构建​

预期​

禁止仅​

完全并行​

全局设置​

全局拆卸​

全局超时​

grep​

grepInvert​

忽略快照​

最大失败次数​

元数据​

名称​

输出目录​

保留输出​

项目​

静默​

重复每个​

报告缓慢测试​

报告程序​

尊重 Git 忽略​

重试​

分片​

快照路径模板​

测试目录​

测试忽略​

测试匹配​

超时​

更新快照​

使用​

webServer​

workers​

已弃用​

snapshotDir​

属性

构建

预期

禁止仅

完全并行

全局设置

全局拆卸

全局超时

grep

grepInvert

忽略快照

最大失败次数

元数据

名称

输出目录

保留输出

项目

静默

重复每个

报告缓慢测试

报告程序

尊重 Git 忽略

重试

分片

快照路径模板

测试目录

测试忽略

测试匹配

超时

更新快照

使用

webServer

workers

已弃用

snapshotDir