跳到主要内容

TestConfig

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

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

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

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

属性

build

添加于:v1.35 testConfig.build

Playwright 转译器配置。

用法

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

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

类型

  • Object
    • external 数组<字符串> (可选)

      要从转译中排除的路径列表,以 glob 模式表示。通常,您的测试所使用的庞大 JS bundle 会在此列出。


captureGitInfo

添加于:v1.51 testConfig.captureGitInfo

这些设置控制是否捕获 git 信息并将其存储在配置的 testConfig.metadata 中。

用法

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

export default defineConfig({
captureGitInfo: { commit: true, diff: true }
});

类型

  • Object
    • commit 布尔值 (可选)

      是否捕获 commit 和 pull request 信息,例如哈希、作者、时间戳。

    • diff 布尔值 (可选)

      是否捕获 commit diff。

详情

  • 捕获 commit 信息有助于在 HTML(或第三方)报告中查看它。
  • 捕获 diff 信息有助于通过实际的源 diff 来丰富报告。此信息可用于提供关于如何修复测试的智能建议。
注意

这些设置的默认值取决于环境。当测试作为 CI 的一部分运行且可以安全获取 git 信息时,默认值为 true,否则为 false

注意

git commit 元数据的结构可能会发生变化。


expect

添加于:v1.10 testConfig.expect

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

用法

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

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

类型


failOnFlakyTests

添加于:v1.52 testConfig.failOnFlakyTests

如果任何测试被标记为不稳定 (flaky),是否以错误退出。在 CI 上很有用。

也可通过 命令行--fail-on-flaky-tests 选项使用。

用法

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

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

类型


forbidOnly

添加于: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,
});

类型


fullyParallel

添加于:v1.20 testConfig.fullyParallel

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

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

用法

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

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

类型


globalSetup

添加于:v1.10 testConfig.globalSetup

全局 setup 文件的路径。此文件将在所有测试之前被引入并运行。它必须导出一个接受 FullConfig 参数的函数。传递路径数组以指定多个全局 setup 文件。

了解更多关于全局 setup 和 teardown 的信息。

用法

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

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

类型


globalTeardown

添加于:v1.10 testConfig.globalTeardown

全局 teardown 文件的路径。此文件将在所有测试之后被引入并运行。它必须导出一个函数。另请参见 testConfig.globalSetup。传递路径数组以指定多个全局 teardown 文件。

了解更多关于全局 setup 和 teardown 的信息。

用法

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

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

类型


globalTimeout

添加于:v1.10 testConfig.globalTimeout

整个测试套件允许运行的最大时间(毫秒)。超时时间为零(默认)将禁用此行为。在 CI 上非常有用,可以防止损坏的 setup 运行时间过长并浪费资源。了解更多关于各种超时的信息。

用法

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/,
});

类型


ignoreSnapshots

添加于: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,
});

类型


maxFailures

添加于:v1.10 testConfig.maxFailures

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

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

用法

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

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

类型


metadata

添加于:v1.10 testConfig.metadata

Metadata 包含要包含在报告中的键值对。例如,HTML 报告将显示为键值对,JSON 报告将包含序列化为 json 的 metadata。

用法

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

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

类型


name

添加于:v1.10 testConfig.name

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

用法

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

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

类型


outputDir

添加于: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.outputDirtestInfo.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');
});

preserveOutput

添加于: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"

projects

添加于: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'] }
]
});

类型


quiet

添加于:v1.10 testConfig.quiet

是否抑制测试的 stdio 和 stderr 输出。

用法

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

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

类型


repeatEach

添加于:v1.10 testConfig.repeatEach

重复运行每个测试的次数,对于调试不稳定 (flaky) 测试很有用。

用法

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

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

类型


reportSlowTests

添加于:v1.10 testConfig.reportSlowTests

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

用法

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

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

类型

  • null | 对象
    • max 数字

      要报告的最大慢速测试文件数量。默认为 5

    • threshold 数字

      被视为慢速的测试文件持续时间(毫秒)。默认为 5 分钟。

详情

运行时间超过 threshold 毫秒的测试文件被视为慢速,并将报告其中最慢的文件,数量不超过 max。将 max 设置为零将报告所有超出阈值的测试文件。


reporter

添加于:v1.10 testConfig.reporter

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

  • 一个内置报告器名称,例如 'list''json'
  • 一个模块名称,例如 'my-awesome-reporter'
  • 报告器的相对路径,例如 './reporters/my-awesome-reporter.js'

您可以通过元组(tuple)形式将选项传递给报告器,例如 ['json', { outputFile: './report.json' }]

更多信息请参见报告器指南

用法

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

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

类型

  • 字符串 | 数组<对象> | "list" | "dot" | "line" | "github" | "json" | "junit" | "null" | "html"
    • 0 字符串

      报告器名称、模块或文件路径

    • 1 对象

      包含报告器选项的对象(如果有)


respectGitIgnore

添加于:v1.45 testConfig.respectGitIgnore

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

用法

testConfig.respectGitIgnore

类型


retries

添加于:v1.10 testConfig.retries

失败测试的最大重试次数。默认情况下,失败的测试不会重试。了解更多关于测试重试的信息。

用法

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

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

类型


shard

添加于:v1.10 testConfig.shard

分片测试并仅执行选定的分片。使用从 1 开始的格式指定,例如 { total: 5, current: 2 }

了解更多关于 Playwright Test 中的并行和分片的信息。

用法

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

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

类型


snapshotPathTemplate

添加于:v1.28 testConfig.snapshotPathTemplate

此选项配置一个模板,用于控制 expect(page).toHaveScreenshot()expect(locator).toMatchAriaSnapshot()expect(value).toMatchSnapshot() 生成的快照位置。

您可以在 testConfig.expect 中分别为每个断言配置模板。

用法

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

export default defineConfig({
testDir: './tests',

// Single template for all assertions
snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',

// Assertion-specific templates
expect: {
toHaveScreenshot: {
pathTemplate: '{testDir}/__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
},
toMatchAriaSnapshot: {
pathTemplate: '{testDir}/__snapshots__/{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()toMatchAriaSnapshot()toMatchSnapshot() 的参数;如果调用时不带参数,这将是一个自动生成的快照名称。
    • 值: foo/bar/baz
  • {ext} - 快照扩展名(带开头的点)。
    • 值: .png
  • {platform} - process.platform 的值。
  • {projectName} - 项目的文件系统安全名称(如果有)。
    • 值: ''(空字符串)。
  • {snapshotDir} - 项目的 testProject.snapshotDir
    • 值: /home/playwright/tests(因为配置中未提供 snapshotDir,所以默认为 testDir
  • {testDir} - 项目的 testProject.testDir
    • 值: /home/playwright/tests(绝对路径,因为 testDir 是相对于包含配置文件的目录解析的)
  • {testFileDir} - 从 testDir测试文件的相对路径中的目录。
    • 值: page
  • {testFileName} - 带扩展名的测试文件名。
    • 值: page-click.spec.ts
  • {testFilePath} - 从 testDir测试文件的相对路径。
    • 值: page/page-click.spec.ts
  • {testName} - 文件系统安全处理过的测试标题,包括父 describes 但不包括文件名。
    • 值: 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' } },
],
});

在此配置中

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

testDir

添加于:v1.10 testConfig.testDir

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

用法

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

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

类型


testIgnore

添加于:v1.10 testConfig.testIgnore

匹配其中一个模式的文件不会被作为测试文件执行。匹配是针对绝对文件路径进行的。字符串被视为 glob 模式。

例如,'**/test-assets/**' 将忽略 test-assets 目录中的任何文件。

用法

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

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

类型


testMatch

添加于:v1.10 testConfig.testMatch

只有匹配其中一个模式的文件才会被作为测试文件执行。匹配是针对绝对文件路径进行的。字符串被视为 glob 模式。

默认情况下,Playwright 会查找匹配以下 glob 模式的文件:**/*.@(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/,
});

类型


timeout

添加于:v1.10 testConfig.timeout

每个测试的超时时间(毫秒)。默认为 30 秒。

这是所有测试的基础超时时间。此外,每个测试可以通过 test.setTimeout() 配置自己的超时时间。了解更多关于各种超时的信息。

用法

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

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

类型


tsconfig

添加于:v1.49 testConfig.tsconfig

适用于所有导入文件的单个 tsconfig 路径。默认情况下,每个导入文件的 tsconfig 会单独查找。请注意,在加载配置文件或其任何依赖项时,tsconfig 属性不起作用。指定 --tsconfig 命令行选项时将忽略此设置。

用法

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

export default defineConfig({
tsconfig: './tsconfig.test.json',
});

类型


updateSnapshots

添加于:v1.10 testConfig.updateSnapshots

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

  • 'all' - 所有执行的测试都将更新快照。
  • 'changed' - 所有执行的测试都将更新不匹配的快照。匹配的快照不会更新。
  • 'missing' - 创建缺失的快照,例如在编写新测试并首次运行时。这是默认值。
  • 'none' - 不更新任何快照。

了解更多关于快照(snapshots)的信息。

用法

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

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

类型

  • "all" | "changed" | "missing" | "none"

updateSourceMethod

添加于:v1.50 testConfig.updateSourceMethod

定义如何在源代码中更新快照。

  • 'patch' - 创建一个统一的 diff 文件,稍后可用于更新源代码。这是默认值。
  • '3way' - 在源代码中生成合并冲突标记。这允许用户手动挑选相关的更改,就像他们在 IDE 中解决合并冲突一样。
  • 'overwrite' - 用新的快照值覆盖源代码。

用法

testConfig.updateSourceMethod

类型

  • "overwrite" | "3way" | "patch"

use

添加于:v1.10 testConfig.use

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

用法

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

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

类型


webServer

添加于:v1.10 testConfig.webServer

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

用法

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

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

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

test('test', async ({ page }) => {
// This will result in http://localhost: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://localhost:3000',
name: 'Frontend',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
},
{
command: 'npm run backend',
url: 'http://localhost:3333',
name: 'Backend',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
}
],
use: {
baseURL: 'http://localhost:3000',
},
});

类型

  • Object | Array<Object>
    • command string

      要启动的 Shell 命令。例如 npm run start..

    • cwd string (可选)

      衍生进程的当前工作目录,默认为配置文件所在的目录。

    • env Object<string, string> (可选)

      为命令设置的环境变量,默认为 process.env

    • gracefulShutdown Object (可选)

      • signal "SIGINT" | "SIGTERM"

      • timeout number

      如何关闭进程。如果未指定,则进程组将被强制 SIGKILL 终止。如果设置为 { signal: 'SIGTERM', timeout: 500 },则向进程组发送 SIGTERM 信号,如果在 500ms 内未退出,则强制 SIGKILL。您也可以使用 SIGINT 作为信号。超时设置为 0 意味着不会发送 SIGKILL。Windows 不支持 SIGTERMSIGINT 信号,因此此选项在 Windows 上被忽略。请注意,关闭 Docker 容器需要 SIGTERM

    • ignoreHTTPSErrors boolean (可选)

      获取 url 时是否忽略 HTTPS 错误。默认为 false

    • name string (可选)

      指定 Web 服务器的自定义名称。此名称将作为日志消息的前缀。默认为 [WebServer]

    • port number (可选)

      期望 http 服务器监听的端口。它会等待直到接受连接。porturl 必须指定其中一个。

    • reuseExistingServer boolean (可选)

      如果为 true,则在 porturl 可用时重用现有服务器。如果 porturl 上没有运行服务器,则会运行命令启动新服务器。如果为 false,则当现有进程监听 porturl 时会抛出错误。通常应将其设置为 !process.env.CI,以便在本地运行测试时允许使用本地开发服务器。

    • stderr "pipe" | "ignore" (可选)

      是否将命令的 stderr 通过管道输出到进程的 stderr 或忽略它。默认为 "pipe"

    • stdout "pipe" | "ignore" (可选)

      如果为 "pipe",则将命令的 stdout 通过管道输出到进程的 stdout。如果为 "ignore",则忽略命令的 stdout。默认为 "ignore"

    • timeout 数字 (可选)

      等待进程启动并可用的时长(毫秒)。默认为 60000。

    • url string (可选)

      http 服务器上期望在服务器准备好接受连接时返回 2xx、3xx、400、401、402 或 403 状态码的 url。会跟随重定向(3xx 状态码)并检查新位置。porturl 必须指定其中一个。

详情

如果指定了 port,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。例如,port 8080 会生成等同于 http://localhost:8080baseURL。如果 webServer 被指定为一个数组,您必须显式配置 baseURL(即使数组中只有一个条目)。

注意

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


workers

添加于:v1.10 testConfig.workers

用于并行运行测试的最大并发 worker 进程数。也可以设置为逻辑 CPU 核心数的百分比,例如 '50%'

Playwright Test 使用 worker 进程来运行测试。总是至少有一个 worker 进程,但可以使用更多进程来加快测试执行速度。

默认为逻辑 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.snapshotDirtestInfo.snapshotPath() 访问每个测试的目录。

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