TestConfig
Playwright Test 提供了许多选项来配置测试的收集和执行方式,例如 timeout
或 testDir
。这些选项在配置文件中的 TestConfig 对象中进行了描述。此类型描述了配置文件的格式,要在运行时访问已解析的配置参数,请使用 FullConfig。
Playwright Test 支持同时运行多个测试项目。项目特定的选项应放在 testConfig.projects 中,但顶级的 TestConfig 也可以定义所有项目共享的基础选项。
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 30000,
globalTimeout: 600000,
reporter: 'list',
testDir: './tests',
});
属性
build
添加于:v1.35Playwright 转译器配置。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
build: {
external: ['**/*bundle.js'],
},
});
类型
captureGitInfo
添加于:v1.51这些设置控制是否捕获 git 信息并将其存储在配置的 testConfig.metadata 中。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
captureGitInfo: { commit: true, diff: true }
});
类型
详情
- 捕获
commit
信息有助于在 HTML(或第三方)报告中查看它。 - 捕获
diff
信息有助于通过实际的源 diff 来丰富报告。此信息可用于提供关于如何修复测试的智能建议。
这些设置的默认值取决于环境。当测试作为 CI 的一部分运行且可以安全获取 git 信息时,默认值为 true
,否则为 false
。
git commit 元数据的结构可能会发生变化。
expect
添加于:v1.10expect
断言库的配置。了解更多关于各种超时的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
timeout: 10000,
toMatchSnapshot: {
maxDiffPixels: 10,
},
},
});
类型
- Object
-
timeout
数字 (可选)异步 expect 匹配器的默认超时时间(毫秒),默认为 5000 毫秒。
-
toHaveScreenshot
对象 (可选)-
animations
"allow" | "disabled" (可选)参见 page.screenshot() 中的 animations。默认为
"disabled"
。 -
caret
"hide" | "initial" (可选)参见 page.screenshot() 中的 caret。默认为
"hide"
。 -
maxDiffPixels
数字 (可选)可接受的像素差异数量,默认未设置。
-
maxDiffPixelRatio
数字 (可选)可接受的差异像素与总像素的比例,介于
0
和1
之间,默认未设置。 -
scale
"css" | "device" (可选)参见 page.screenshot() 中的 scale。默认为
"css"
。 -
参见 page.screenshot() 中的 style。
-
threshold
数字 (可选)可接受的比较图像中同一像素的感知颜色差异,范围从
0
(严格)到1
(宽松)。"pixelmatch"
比较器计算 YIQ 颜色空间中的颜色差异,并将threshold
值默认为0.2
。 -
pathTemplate
字符串 (可选)控制截图位置的模板。详见 testConfig.snapshotPathTemplate。
-
-
toMatchAriaSnapshot
对象 (可选)-
pathTemplate
字符串 (可选)控制 aria 快照位置的模板。详见 testConfig.snapshotPathTemplate。
-
-
toMatchSnapshot
对象 (可选) -
toPass
对象 (可选)expect(value).toPass() 方法的配置。
-
failOnFlakyTests
添加于:v1.52如果任何测试被标记为不稳定 (flaky),是否以错误退出。在 CI 上很有用。
也可通过 命令行 的 --fail-on-flaky-tests
选项使用。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
failOnFlakyTests: !!process.env.CI,
});
类型
forbidOnly
添加于:v1.10如果任何测试或组被标记为 test.only() 或 test.describe.only(),是否以错误退出。在 CI 上很有用。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
forbidOnly: !!process.env.CI,
});
类型
fullyParallel
添加于:v1.20Playwright Test 并行运行测试。为了实现这一点,它会同时运行多个 worker 进程。默认情况下,测试文件是并行运行的。单个文件中的测试会按顺序在同一个 worker 进程中运行。
您可以使用此选项配置整个测试运行,以同时执行所有文件中的所有测试。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
fullyParallel: true,
});
类型
globalSetup
添加于:v1.10全局 setup 文件的路径。此文件将在所有测试之前被引入并运行。它必须导出一个接受 FullConfig 参数的函数。传递路径数组以指定多个全局 setup 文件。
了解更多关于全局 setup 和 teardown 的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalSetup: './global-setup',
});
类型
globalTeardown
添加于:v1.10全局 teardown 文件的路径。此文件将在所有测试之后被引入并运行。它必须导出一个函数。另请参见 testConfig.globalSetup。传递路径数组以指定多个全局 teardown 文件。
了解更多关于全局 setup 和 teardown 的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalTeardown: './global-teardown',
});
类型
globalTimeout
添加于:v1.10整个测试套件允许运行的最大时间(毫秒)。超时时间为零(默认)将禁用此行为。在 CI 上非常有用,可以防止损坏的 setup 运行时间过长并浪费资源。了解更多关于各种超时的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
});
类型
grep
添加于:v1.10过滤器,仅运行标题匹配其中一个模式的测试。例如,传入 grep: /cart/
应仅运行标题中包含 "cart" 的测试。也可通过 命令行 的 -g
选项使用。正则表达式将与由项目名称、测试文件名、test.describe
名称(如果有)、测试名称和测试标签组成的字符串进行匹配,例如 chromium my-test.spec.ts my-suite my-test
。
grep
选项也适用于标记测试。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
grep: /smoke/,
});
类型
grepInvert
添加于:v1.10过滤器,仅运行标题**不**匹配其中一个模式的测试。这与 testConfig.grep 相反。也可通过 命令行 的 --grep-invert
选项使用。
grepInvert
选项也适用于标记测试。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
grepInvert: /manual/,
});
类型
ignoreSnapshots
添加于:v1.26是否跳过快照断言,例如 expect(value).toMatchSnapshot()
和 await expect(page).toHaveScreenshot()
。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
ignoreSnapshots: !process.env.CI,
});
类型
maxFailures
添加于:v1.10整个测试套件运行的最大失败次数。达到此次数后,测试将停止并以错误退出。设置为零(默认)将禁用此行为。
也可通过 命令行 的 --max-failures
和 -x
选项使用。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
maxFailures: process.env.CI ? 1 : 0,
});
类型
metadata
添加于:v1.10Metadata 包含要包含在报告中的键值对。例如,HTML 报告将显示为键值对,JSON 报告将包含序列化为 json 的 metadata。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
metadata: { title: 'acceptance tests' },
});
类型
name
添加于:v1.10配置名称在报告中和测试执行期间可见,除非被 testProject.name 覆盖。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
name: 'acceptance tests',
});
类型
outputDir
添加于:v1.10测试执行期间创建文件的输出目录。默认为 <package.json-directory>/test-results
。
用法
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');
});
preserveOutput
添加于:v1.10是否保留测试输出在 testConfig.outputDir 中。默认为 'always'
。
'always'
- 保留所有测试的输出;'never'
- 不保留任何测试的输出;'failures-only'
- 仅保留失败测试的输出。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
preserveOutput: 'always',
});
类型
- "always" | "never" | "failures-only"
projects
添加于:v1.10Playwright Test 支持同时运行多个测试项目。有关详细信息,请参阅 TestProject。
用法
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{ name: 'chromium', use: devices['Desktop Chrome'] }
]
});
类型
quiet
添加于:v1.10是否抑制测试的 stdio 和 stderr 输出。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
quiet: !!process.env.CI,
});
类型
repeatEach
添加于:v1.10重复运行每个测试的次数,对于调试不稳定 (flaky) 测试很有用。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
repeatEach: 3,
});
类型
reportSlowTests
添加于:v1.10是否报告慢速测试文件。传递 null
以禁用此功能。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
reportSlowTests: null,
});
类型
详情
运行时间超过 threshold
毫秒的测试文件被视为慢速,并将报告其中最慢的文件,数量不超过 max
。将 max
设置为零将报告所有超出阈值的测试文件。
reporter
添加于:v1.10要使用的报告器列表。每个报告器可以是
- 一个内置报告器名称,例如
'list'
或'json'
。 - 一个模块名称,例如
'my-awesome-reporter'
。 - 报告器的相对路径,例如
'./reporters/my-awesome-reporter.js'
。
您可以通过元组(tuple)形式将选项传递给报告器,例如 ['json', { outputFile: './report.json' }]
。
更多信息请参见报告器指南。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: 'line',
});
类型
respectGitIgnore
添加于:v1.45搜索测试文件时,是否跳过 .gitignore
中的条目。默认情况下,如果既没有明确指定 testConfig.testDir 也没有明确指定 testProject.testDir,Playwright 将忽略任何匹配 .gitignore
条目的测试文件。
用法
testConfig.respectGitIgnore
类型
retries
添加于:v1.10失败测试的最大重试次数。默认情况下,失败的测试不会重试。了解更多关于测试重试的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 2,
});
类型
shard
添加于:v1.10分片测试并仅执行选定的分片。使用从 1 开始的格式指定,例如 { total: 5, current: 2 }
。
了解更多关于 Playwright Test 中的并行和分片的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
shard: { total: 10, current: 3 },
});
类型
snapshotPathTemplate
添加于:v1.28此选项配置一个模板,用于控制 expect(page).toHaveScreenshot()、expect(locator).toMatchAriaSnapshot() 和 expect(value).toMatchSnapshot() 生成的快照位置。
您可以在 testConfig.expect 中分别为每个断言配置模板。
用法
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
文件
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
- 值:
每个标记前面可以有一个字符,该字符**仅当**此标记具有非空值时才会被使用。
考虑以下配置
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
解析。 - 正斜杠
"/"
可在任何平台上用作路径分隔符。
testDir
添加于:v1.10将递归扫描以查找测试文件的目录。默认为配置文件的目录。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests/playwright',
});
类型
testIgnore
添加于:v1.10匹配其中一个模式的文件不会被作为测试文件执行。匹配是针对绝对文件路径进行的。字符串被视为 glob 模式。
例如,'**/test-assets/**'
将忽略 test-assets
目录中的任何文件。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
testIgnore: '**/test-assets/**',
});
类型
testMatch
添加于:v1.10只有匹配其中一个模式的文件才会被作为测试文件执行。匹配是针对绝对文件路径进行的。字符串被视为 glob 模式。
默认情况下,Playwright 会查找匹配以下 glob 模式的文件:**/*.@(spec|test).?(c|m)[jt]s?(x)
。这意味着带有 ".test"
或 ".spec"
后缀的 JavaScript 或 TypeScript 文件,例如 login-screen.wrong-credentials.spec.ts
。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
testMatch: /.*\.e2e\.js/,
});
类型
timeout
添加于:v1.10每个测试的超时时间(毫秒)。默认为 30 秒。
这是所有测试的基础超时时间。此外,每个测试可以通过 test.setTimeout() 配置自己的超时时间。了解更多关于各种超时的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
timeout: 5 * 60 * 1000,
});
类型
tsconfig
添加于:v1.49适用于所有导入文件的单个 tsconfig
路径。默认情况下,每个导入文件的 tsconfig
会单独查找。请注意,在加载配置文件或其任何依赖项时,tsconfig
属性不起作用。指定 --tsconfig
命令行选项时将忽略此设置。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
tsconfig: './tsconfig.test.json',
});
类型
updateSnapshots
添加于:v1.10是否使用测试运行产生的实际结果更新预期的快照。默认为 'missing'
。
'all'
- 所有执行的测试都将更新快照。'changed'
- 所有执行的测试都将更新不匹配的快照。匹配的快照不会更新。'missing'
- 创建缺失的快照,例如在编写新测试并首次运行时。这是默认值。'none'
- 不更新任何快照。
了解更多关于快照(snapshots)的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
updateSnapshots: 'missing',
});
类型
- "all" | "changed" | "missing" | "none"
updateSourceMethod
添加于:v1.50定义如何在源代码中更新快照。
'patch'
- 创建一个统一的 diff 文件,稍后可用于更新源代码。这是默认值。'3way'
- 在源代码中生成合并冲突标记。这允许用户手动挑选相关的更改,就像他们在 IDE 中解决合并冲突一样。'overwrite'
- 用新的快照值覆盖源代码。
用法
testConfig.updateSourceMethod
类型
- "overwrite" | "3way" | "patch"
use
添加于:v1.10所有测试的全局选项,例如 testOptions.browserName。了解更多关于配置的信息并查看可用选项。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
browserName: 'chromium',
},
});
类型
webServer
添加于:v1.10在测试期间启动一个(或多个)开发 Web 服务器。
用法
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/',
},
});
现在导航页面时可以使用相对路径
import { test } from '@playwright/test';
test('test', async ({ page }) => {
// This will result in http://localhost:3000/foo
await page.goto('/foo');
});
可以启动多个 Web 服务器(或后台进程)
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 不支持SIGTERM
和SIGINT
信号,因此此选项在 Windows 上被忽略。请注意,关闭 Docker 容器需要SIGTERM
。 -
-
ignoreHTTPSErrors
boolean (可选)获取
url
时是否忽略 HTTPS 错误。默认为false
。 -
name
string (可选)指定 Web 服务器的自定义名称。此名称将作为日志消息的前缀。默认为
[WebServer]
。 -
port
number (可选)期望 http 服务器监听的端口。它会等待直到接受连接。
port
或url
必须指定其中一个。 -
reuseExistingServer
boolean (可选)如果为 true,则在
port
或url
可用时重用现有服务器。如果port
或url
上没有运行服务器,则会运行命令启动新服务器。如果为 false,则当现有进程监听port
或url
时会抛出错误。通常应将其设置为!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 状态码)并检查新位置。
port
或url
必须指定其中一个。
-
详情
如果指定了 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:8080
的 baseURL
。如果 webServer
被指定为一个数组,您必须显式配置 baseURL
(即使数组中只有一个条目)。
还建议在配置中指定 testOptions.baseURL,以便测试可以使用相对 url。
workers
添加于:v1.10用于并行运行测试的最大并发 worker 进程数。也可以设置为逻辑 CPU 核心数的百分比,例如 '50%'
。
Playwright Test 使用 worker 进程来运行测试。总是至少有一个 worker 进程,但可以使用更多进程来加快测试执行速度。
默认为逻辑 CPU 核心数的一半。了解更多关于 Playwright Test 的并行执行和分片的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
workers: 3,
});
类型
已废弃
snapshotDir
添加于:v1.10使用 testConfig.snapshotPathTemplate 配置快照路径。
相对于配置文件的基础目录,用于 toMatchSnapshot
创建的快照文件。默认为 testConfig.testDir。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
snapshotDir: './snapshots',
});
类型
详情
可以通过 testInfo.snapshotDir 和 testInfo.snapshotPath() 访问每个测试的目录。
此路径将作为每个测试文件快照目录的基础目录。将 snapshotDir
设置为 'snapshots'
,testInfo.snapshotDir
将解析为 snapshots/a.spec.js-snapshots
。