跳转到主要内容

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 包会在此处列出。


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 布尔值 (可选)

      是否捕获提交和拉取请求信息,例如哈希值、作者、时间戳。

    • diff 布尔值 (可选)

      是否捕获提交差异。

详情

  • 捕获 commit 信息在您希望在 HTML(或第三方)报告中查看时很有用。
  • 捕获 diff 信息可用于用实际的源差异丰富报告。此信息可用于提供有关如何修复测试的智能建议。
注意

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

注意

Git 提交元数据的结构可能会发生变化。


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

如果任何测试被标记为不稳定,是否以错误退出。在 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 并行运行测试。为此,它会同时运行多个工作进程。默认情况下,测试文件是并行运行的。单个文件中的测试按顺序在相同的工作进程中运行。

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

用法

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

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

类型


globalSetup

新增于: v1.10 testConfig.globalSetup

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

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

用法

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

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

类型


globalTeardown

新增于: v1.10 testConfig.globalTeardown

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

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

用法

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

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

类型


globalTimeout

新增于: 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/,
});

类型


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

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

用法

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

测试执行期间创建文件的输出目录。默认为 /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

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

用法

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

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

类型


repeatEach

新增于: v1.10 testConfig.repeatEach

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

用法

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'

您可以在元组中向报告器传递选项,例如 ['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

分片测试并仅执行选定的分片。以基于一的格式指定,如 { 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(相对于配置文件的目录解析的绝对路径)
  • {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' } },
],
});

在此配置中

  1. 第一个项目没有名称,因此其快照将存储在 /__screenshots__/example.spec.ts/... 中。
  2. 第二个项目名称,因此其快照将存储在 /__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' - 不更新任何快照。

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

用法

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

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

类型

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

updateSourceMethod

新增于: v1.50 testConfig.updateSourceMethod

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

  • 'patch' - 创建一个统一的差异文件,以后可用于更新源代码。这是默认值。
  • '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

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

用法

playwright.config.ts
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/',
},
});

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

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

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

可以启动多个网络服务器(或后台进程)

playwright.config.ts
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 字符串 (可选)

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

    • env 对象<字符串, 字符串> (可选)

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

    • gracefulShutdown 对象 (可选)

      • signal "SIGINT" | "SIGTERM"

      • timeout 数字

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

    • ignoreHTTPSErrors 布尔值 (可选)

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

    • name 字符串 (可选)

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

    • port 数字 (可选)

      您的 http 服务器预计出现在哪个端口。它会等到它接受连接。应该指定 porturl

    • reuseExistingServer 布尔值 (可选)

      如果为 true,它将在可用时重用 porturl 上的现有服务器。如果没有服务器正在该 porturl 上运行,它将运行命令以启动一个新服务器。如果为 false,则如果现有进程正在侦听 porturl,它将抛出错误。这通常应设置为 !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 状态码)将被跟踪并检查新位置。应该指定 porturl

详情

如果指定了端口,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 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.snapshotDirtestInfo.snapshotPath() 访问。

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