TestConfig

Playwright Test 提供了许多选项来配置测试的收集和执行方式，例如 timeout 或 testDir。这些选项在配置文件中的 TestConfig 对象中描述。

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  timeout: 30000,
  globalTimeout: 600000,
  reporter: 'list',
  testDir: './tests',
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  timeout: 30000,
  globalTimeout: 600000,
  reporter: 'list',
  testDir: './tests',
};

module.exports = config;

testConfig.expect

Added in: v1.10

type:<Object>
- timeout? <number> 异步 expect 匹配器的默认超时时间（以毫秒为单位），默认为 5000ms。
- toHaveScreenshot? <Object> expect(page).toHaveScreenshot(name[, options]) 方法的配置。
  - threshold? <number> 比较图像中相同像素之间在 YIQ 颜色空间中可接受的感知颜色差异，介于零（严格）和一（宽松）之间。默认为 0.2。
  - maxDiffPixels? <number> 可接受的不同像素数量，默认未设置。
  - maxDiffPixelRatio? <number> 不同像素占总像素数量的可接受比例，介于 0 和 1 之间，默认未设置。
  - animations? <"allow"|"disabled"> 参见 page.screenshot([options]) 中的 animations。默认为 "disabled"。
  - caret? <"hide"|"initial"> 参见 page.screenshot([options]) 中的 caret。默认为 "hide"。
  - scale? <"css"|"device"> 参见 page.screenshot([options]) 中的 scale。默认为 "css"。
- toMatchSnapshot? <Object> expect(screenshot).toMatchSnapshot(name[, options]) 方法的配置。
  - threshold? <number> 比较图像中相同像素之间在 YIQ 颜色空间中可接受的感知颜色差异，介于零（严格）和一（宽松）之间。默认为 0.2。
  - maxDiffPixels? <number> 可接受的不同像素数量，默认未设置。
  - maxDiffPixelRatio? <number> 不同像素占总像素数量的可接受比例，介于 0 和 1 之间，默认未设置。

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  expect: {
    timeout: 10000,
    toMatchSnapshot: {
      maxDiffPixels: 10,
    },
  },
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  expect: {
    timeout: 10000,
    toMatchSnapshot: {
      maxDiffPixels: 10,
    },
  },
};

module.exports = config;

testConfig.forbidOnly

Added in: v1.10

type:<boolean>

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  forbidOnly: !!process.env.CI,
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  forbidOnly: !!process.env.CI,
};

module.exports = config;

testConfig.fullyParallel

Added in: v1.10

type:<boolean>

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

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

testConfig.globalSetup

Added in: v1.10

type:<string>

全局设置文件的路径。此文件将在所有测试之前被 require 并运行。它必须导出一个接受 [TestConfig] 参数的单个函数。

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  globalSetup: './global-setup',
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  globalSetup: './global-setup',
};

module.exports = config;

testConfig.globalTeardown

Added in: v1.10

type:<string>

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

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  globalTeardown: './global-teardown',
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  globalTeardown: './global-teardown',
};

module.exports = config;

testConfig.globalTimeout

Added in: v1.10

type:<number>

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
};

module.exports = config;

testConfig.grep

Added in: v1.10

type:<RegExp|Array<RegExp>>

过滤器，仅运行标题与其中一个模式匹配的测试。例如，传递 grep: /cart/ 应仅运行标题中包含 "cart" 的测试。也可以在命令行中使用 -g 选项。

grep 选项对于标记测试也很有用。

testConfig.grepInvert

Added in: v1.10

type:<RegExp|Array<RegExp>>

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

grepInvert 选项对于标记测试也很有用。

testConfig.ignoreSnapshots

Added in: v1.26

type:<boolean>

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

testConfig.maxFailures

Added in: v1.10

type:<number>

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

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  maxFailures: process.env.CI ? 1 : 0,
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  maxFailures: process.env.CI ? 1 : 0,
};

module.exports = config;

testConfig.metadata

Added in: v1.10

type:<[Metadata]>

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

testConfig.name

Added in: v1.10

type:<string>

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

testConfig.outputDir

Added in: v1.10

type:<string>

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  outputDir: './test-results',
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  outputDir: './test-results',
};

module.exports = config;

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

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

TypeScript
JavaScript

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');
});

const { test, expect } = require('@playwright/test');
const fs = require('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');
});

testConfig.preserveOutput

Added in: v1.10

type:<"always"|"never"|"failures-only">

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

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

testConfig.projects

Added in: v1.10

type:<Array<TestProject>>

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

testConfig.quiet

Added in: v1.10

type:<boolean>

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

testConfig.repeatEach

Added in: v1.10

type:<number>

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

testConfig.reportSlowTests

Added in: v1.10

type:<null|Object>
- max <number> 要报告的最大慢速测试文件数。默认为 5。
- threshold <number> 被视为慢速的测试持续时间（以毫秒为单位）。默认为 15 秒。

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

耗时超过 threshold 毫秒的测试文件被视为慢速，并且报告最慢的文件，不超过 max 个。将 max 传递为零将报告所有超过阈值的测试文件。

testConfig.reporter

Added in: v1.10

type:<string|Array<Object>|"list"|"dot"|"line"|"github"|"json"|"junit"|"null"|"html">
- 0 <string> 报告器名称或模块或文件路径
- 1 <Object> 包含报告器选项的对象（如果有）

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

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

您可以将选项作为元组传递给报告器，如 ['json', { outputFile: './report.json' }]。

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  reporter: 'line',
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  reporter: 'line',
};

module.exports = config;

testConfig.retries

Added in: v1.10

type:<number>

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  retries: 2,
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  retries: 2,
};

module.exports = config;

testConfig.shard

Added in: v1.10

type:<null|Object>
- total <number> 分片总数。
- current <number> 要执行的分片索引，从 1 开始。

分片测试并仅执行选定的分片。以从 1 开始的形式指定，如 { total: 5, current: 2 }。

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

testConfig.snapshotDir

Added in: v1.10

type:<string>

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

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

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

testConfig.testDir

Added in: v1.10

type:<string>

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  testDir: './tests/playwright',
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  testDir: './tests/playwright',
};

module.exports = config;

testConfig.testIgnore

Added in: v1.10

type:<string|RegExp|Array<string|RegExp>>

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

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  testIgnore: '**/test-assets/**',
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  testIgnore: '**/test-assets/**',
};

module.exports = config;

testConfig.testMatch

Added in: v1.10

type:<string|RegExp|Array<string|RegExp>>

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

默认情况下，Playwright Test 查找匹配 .*(test|spec)\.(js|ts|mjs) 的文件。

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  testMatch: /.*\.e2e\.js/,
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  testMatch: /.*\.e2e\.js/,
};

module.exports = config;

testConfig.timeout

Added in: v1.10

type:<number>

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

这是所有测试的基本超时时间。此外，每个测试可以使用 test.setTimeout(timeout) 配置自己的超时时间。了解有关各种超时的更多信息。

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  timeout: 5 * 60 * 1000,
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  timeout: 5 * 60 * 1000,
};

module.exports = config;

testConfig.updateSnapshots

Added in: v1.10

type:<"all"|"none"|"missing">

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

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

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

testConfig.use

Added in: v1.10

type:<TestOptions>

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

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  use: {
    browserName: 'chromium',
  },
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  use: {
    browserName: 'chromium',
  },
};

module.exports = config;

testConfig.webServer

Added in: v1.10

type:<Object|Array<Object>>
- command <string> 要启动的 Shell 命令。例如 npm run start。
- port? <number> 您的 http 服务器预期出现的端口。它确实会等待直到它接受连接。port 或 url 必须且只能指定一个。
- url? <string> 当服务器准备好接受连接时，预期返回 2xx、3xx、400、401、402 或 403 状态代码的 http 服务器上的 url。port 或 url 必须且只能指定一个。
- ignoreHTTPSErrors? <boolean> 获取 url 时是否忽略 HTTPS 错误。默认为 false。
- timeout? <number> 等待进程启动并可用的时间（以毫秒为单位）。默认为 60000。
- reuseExistingServer? <boolean> 如果为 true，它将在可用时重用 port 或 url 上的现有服务器。如果该 port 或 url 上没有运行服务器，它将运行命令以启动新服务器。如果为 false，如果现有进程正在侦听 port 或 url，它将抛出异常。这通常应设置为 !process.env.CI 以允许在本地运行测试时使用本地开发服务器。
- cwd? <string> 生成进程的当前工作目录，默认为配置文件的目录。
- env? <Object<string, string>> 为命令设置的环境变量，默认为 process.env。

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

如果指定了端口，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 生成等于 http://localhost:8080 的 baseURL。如果 webServer 指定为数组，则必须显式配置 baseURL（即使它只有一个条目）。

note

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

TypeScript
JavaScript

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

// playwright.config.js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  webServer: {
    command: 'npm run start',
    port: 3000,
    timeout: 120 * 1000,
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: 'http://localhost:3000/',
  },
};
module.exports = config;

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

TypeScript
JavaScript

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

test('test', async ({ page }) => {
  // 这将导致 http://localhost:3000/foo
  await page.goto('/foo');
});

// test.spec.js
const { test } = require('@playwright/test');

test('test', async ({ page }) => {
  // 这将导致 http://localhost:3000/foo
  await page.goto('/foo');
});

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

TypeScript
JavaScript

// playwright.config.ts
import type { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
  webServer: [
    {
      command: 'npm run start',
      port: 3000,
      timeout: 120 * 1000,
      reuseExistingServer: !process.env.CI,
    },
    {
      command: 'npm run backend',
      port: 3333,
      timeout: 120 * 1000,
      reuseExistingServer: !process.env.CI,
    }
  ],
  use: {
    baseURL: 'http://localhost:3000/',
  },
};
export default config;

// playwright.config.js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  webServer: [
    {
      command: 'npm run start',
      port: 3000,
      timeout: 120 * 1000,
      reuseExistingServer: !process.env.CI,
    },
    {
      command: 'npm run backend',
      port: 3333,
      timeout: 120 * 1000,
      reuseExistingServer: !process.env.CI,
    }
  ],
  use: {
    baseURL: 'http://localhost:3000/',
  },
};
module.exports = config;

testConfig.workers

Added in: v1.10

type:<number|string>

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

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

默认为逻辑 CPU 核心数的一半。了解有关 Playwright Test 的并行和分片的更多信息。

TypeScript
JavaScript

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

const config: PlaywrightTestConfig = {
  workers: 3,
};
export default config;

// playwright.config.js
// @ts-check

/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
  workers: 3,
};

module.exports = config;

testConfig.expect​

testConfig.forbidOnly​

testConfig.fullyParallel​

testConfig.globalSetup​

testConfig.globalTeardown​

testConfig.globalTimeout​

testConfig.grep​

testConfig.grepInvert​

testConfig.ignoreSnapshots​

testConfig.maxFailures​

testConfig.metadata​

testConfig.name​

testConfig.outputDir​

testConfig.preserveOutput​

testConfig.projects​

testConfig.quiet​

testConfig.repeatEach​

testConfig.reportSlowTests​

testConfig.reporter​

testConfig.retries​

testConfig.shard​

testConfig.snapshotDir​

testConfig.testDir​

testConfig.testIgnore​

testConfig.testMatch​

testConfig.timeout​

testConfig.updateSnapshots​

testConfig.use​

testConfig.webServer​

testConfig.workers​

testConfig.expect

testConfig.forbidOnly

testConfig.fullyParallel

testConfig.globalSetup

testConfig.globalTeardown

testConfig.globalTimeout

testConfig.grep

testConfig.grepInvert

testConfig.ignoreSnapshots

testConfig.maxFailures

testConfig.metadata

testConfig.name

testConfig.outputDir

testConfig.preserveOutput

testConfig.projects

testConfig.quiet

testConfig.repeatEach

testConfig.reportSlowTests

testConfig.reporter

testConfig.retries

testConfig.shard

testConfig.snapshotDir

testConfig.testDir

testConfig.testIgnore

testConfig.testMatch

testConfig.timeout

testConfig.updateSnapshots

testConfig.use

testConfig.webServer

testConfig.workers