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
信息可用于用实际的源差异丰富报告。此信息可用于提供有关如何修复测试的智能建议。
这些设置的默认值取决于环境。当测试作为 CI 的一部分运行时,可以安全地获取 Git 信息,默认值为 true
,否则为 false
。
Git 提交元数据的结构可能会发生变化。
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如果任何测试被标记为不稳定,是否以错误退出。在 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 并行运行测试。为此,它会同时运行多个工作进程。默认情况下,测试文件是并行运行的。单个文件中的测试按顺序在相同的工作进程中运行。
您可以使用此选项将整个测试运行配置为并发执行所有文件中的所有测试。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
fullyParallel: true,
});
类型
globalSetup
新增于: v1.10全局设置文件的路径。此文件将在所有测试之前被要求并运行。它必须导出一个接受 FullConfig 参数的单个函数。传递一个路径数组以指定多个全局设置文件。
了解更多关于 全局设置和拆卸 的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalSetup: './global-setup',
});
类型
globalTeardown
新增于: v1.10全局拆卸文件的路径。此文件将在所有测试之后被要求并运行。它必须导出一个单个函数。另请参阅 testConfig.globalSetup。传递一个路径数组以指定多个全局拆卸文件。
了解更多关于 全局设置和拆卸 的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
globalTeardown: './global-teardown',
});
类型
globalTimeout
新增于: v1.10整个测试套件可以运行的最大时间(毫秒)。零超时(默认)禁用此行为。在 CI 上很有用,以防止损坏的设置运行时间过长并浪费资源。了解更多关于 各种超时 的信息。
用法
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.10元数据包含要包含在报告中的键值对。例如,HTML 报告将显示为键值对,JSON 报告将包含序列化为 JSON 的元数据。
用法
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测试执行期间创建文件的输出目录。默认为
。
用法
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是否抑制测试的标准输出和标准错误输出。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
quiet: !!process.env.CI,
});
类型
repeatEach
新增于: v1.10每个测试的重复次数,对于调试不稳定测试很有用。
用法
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'
。
您可以在元组中向报告器传递选项,例如 ['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分片测试并仅执行选定的分片。以基于一的格式指定,如 { 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
(相对于配置文件的目录解析的绝对路径)
- 值:
{testFileDir}
- 从testDir
到测试文件的相对路径中的目录。- 值:
page
- 值:
{testFileName}
- 带扩展名的测试文件名。- 值:
page-click.spec.ts
- 值:
{testFilePath}
- 从testDir
到测试文件的相对路径。- 值:
page/page-click.spec.ts
- 值:
{testName}
- 文件系统安全测试标题,包括父描述但不包括文件名。- 值:
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' } },
],
});
在此配置中
- 第一个项目没有名称,因此其快照将存储在
中。/__screenshots__/example.spec.ts/... - 第二个项目有名称,因此其快照将存储在
中。/__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'
- 不更新任何快照。
了解更多关于 快照 的信息。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
updateSnapshots: 'missing',
});
类型
- "all" | "changed" | "missing" | "none"
updateSourceMethod
新增于: v1.50定义如何在源代码中更新快照。
'patch'
- 创建一个统一的差异文件,以后可用于更新源代码。这是默认值。'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在测试期间启动一个开发网络服务器(或多个)。
用法
import { defineConfig } from '@playwright/test';
export default defineConfig({
webServer: {
command: 'npm run start',
url: 'https://:3000',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
},
use: {
baseURL: 'https://:3000/',
},
});
现在您可以在导航页面时使用相对路径
import { test } from '@playwright/test';
test('test', async ({ page }) => {
// This will result in https://:3000/foo
await page.goto('/foo');
});
可以启动多个网络服务器(或后台进程)
import { defineConfig } from '@playwright/test';
export default defineConfig({
webServer: [
{
command: 'npm run start',
url: 'https://:3000',
name: 'Frontend',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
},
{
command: 'npm run backend',
url: 'https://:3333',
name: 'Backend',
timeout: 120 * 1000,
reuseExistingServer: !process.env.CI,
}
],
use: {
baseURL: 'https://:3000',
},
});
类型
- 对象 | 数组<对象>
-
command
字符串要启动的 Shell 命令。例如
npm run start
。 -
cwd
字符串 (可选)派生进程的当前工作目录,默认为配置文件的目录。
-
为命令设置的环境变量,默认为
process.env
。 -
gracefulShutdown
对象 (可选)-
signal
"SIGINT" | "SIGTERM" -
timeout
数字
如何关闭进程。如果未指定,进程组将被强制
SIGKILL
。如果设置为{ signal: 'SIGTERM', timeout: 500 }
,则会向进程组发送SIGTERM
信号,如果它在 500 毫秒内未退出,则随后发送SIGKILL
。您也可以使用SIGINT
作为信号。0
超时表示不会发送SIGKILL
。Windows 不支持SIGTERM
和SIGINT
信号,因此此选项在 Windows 上被忽略。请注意,关闭 Docker 容器需要SIGTERM
。 -
-
ignoreHTTPSErrors
布尔值 (可选)获取
url
时是否忽略 HTTPS 错误。默认为false
。 -
name
字符串 (可选)为 Web 服务器指定自定义名称。此名称将作为日志消息的前缀。默认为
[WebServer]
。 -
port
数字 (可选)您的 http 服务器预计出现在哪个端口。它会等到它接受连接。应该指定
port
或url
。 -
reuseExistingServer
布尔值 (可选)如果为 true,它将在可用时重用
port
或url
上的现有服务器。如果没有服务器正在该port
或url
上运行,它将运行命令以启动一个新服务器。如果为false
,则如果现有进程正在侦听port
或url
,它将抛出错误。这通常应设置为!process.env.CI
,以允许在本地运行测试时使用本地开发服务器。 -
stderr
"pipe" | "ignore" (可选)是否将命令的标准错误输出管道到进程标准错误或忽略它。默认为
"pipe"
。 -
stdout
"pipe" | "ignore" (可选)如果为
"pipe"
,它将把命令的标准输出管道到进程标准输出。如果为"ignore"
,它将忽略命令的标准输出。默认为"ignore"
。 -
timeout
数字 (可选)等待进程启动并可用(毫秒)的时间。默认为 60000。
-
url
字符串 (可选)当服务器准备好接受连接时,您的 http 服务器上预计返回 2xx、3xx、400、401、402 或 403 状态码的 url。重定向(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 上不使用现有服务器。要查看标准输出,您可以设置 DEBUG=pw:webserver
环境变量。
port
(但不是 url
)将作为 testOptions.baseURL 传递给 Playwright。例如,端口 8080
生成 baseURL
等于 https://:8080
。如果 webServer
指定为数组,则必须明确配置 baseURL
(即使它只有一个条目)。
还建议在配置中指定 testOptions.baseURL,以便测试可以使用相对 URL。
workers
新增于: v1.10用于并行化测试的并发工作进程的最大数量。也可以设置为逻辑 CPU 核心的百分比,例如 '50%'
。
Playwright Test 使用工作进程来运行测试。始终至少有一个工作进程,但可以使用更多工作进程来加快测试执行。
默认为逻辑 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
。