TestConfig

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

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

import { defineConfig } from '@playwright/test';

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

属性​

构建​

Playwright 转译器配置。

用法

import { defineConfig } from '@playwright/test';

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

类型

• Object

  • external Array<string> (可选)

    要从转译中排除的路径，以glob模式列表表示。通常这里会列出测试使用的大型JS包。

捕获Git信息​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• Object

  • commit boolean (可选)

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

  • diff boolean (可选)

    是否捕获提交差异。

详情

• Capturing commit information is useful when you'd like to see it in your HTML (or a third party) report.
• 捕获diff信息有助于通过实际源代码差异来丰富报告。这些信息可用于提供关于如何修复测试的智能建议。

expect​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• Object

  • timeout number (可选)

    异步expect匹配器的默认超时时间，单位为毫秒，默认为5000毫秒。

  • toHaveScreenshot Object (可选)

    • animations "allow" | "disabled" (可选)

      参见page.screenshot()中的animations。默认为"disabled"。

    • caret "hide" | "initial" (可选)

      参见caret在page.screenshot()中的说明。默认为"hide"。

    • maxDiffPixels number (可选)

      可接受的像素差异数量，默认未设置。

    • maxDiffPixelRatio number (可选)

      可接受的差异像素与总像素之比，范围在0到1之间，默认未设置。

    • scale "css" | "device" (可选)

      参见 scale 在 page.screenshot() 中的说明。默认为 "css"。

    • stylePath string | Array<string> (可选)

      参见 page.screenshot() 中的 style。

    • threshold number (可选)

      比较图像中相同像素之间可接受的感知色差，范围从0(严格)到1(宽松)。"pixelmatch"比较器在YIQ色彩空间中计算色差，默认threshold值为0.2。

    • pathTemplate string (可选)

      控制截图保存位置的模板。详情请参阅testConfig.snapshotPathTemplate。

    expect(page).toHaveScreenshot() 方法的配置。

  • toMatchAriaSnapshot Object (可选)

    • pathTemplate string (可选)

      控制aria快照存储位置的模板。详情请参阅testConfig.snapshotPathTemplate。

    expect(locator).toMatchAriaSnapshot() 方法的配置。

  • toMatchSnapshot Object (可选)

    • maxDiffPixels number (可选)

      允许存在差异的像素数量，默认未设置。

    • maxDiffPixelRatio number (可选)

      可接受的不同像素与总像素的比率，介于0和1之间，默认未设置。

    • threshold number (可选)

      比较图像中相同像素之间可接受的感知色差，范围从0（严格）到1（宽松）。"pixelmatch"比较器在YIQ色彩空间中计算色差，默认threshold值为0.2。

    expect(value).toMatchSnapshot() 方法的配置。

  • toPass Object (可选)

    • intervals Array<number> (可选)

      toPass方法的探测间隔时间，单位为毫秒。

    • timeout number (可选)

      toPass方法的超时时间，单位为毫秒。

    expect(value).toPass() 方法的配置。

禁止仅​

如果任何测试或组被标记为test.only()或test.describe.only()，是否要报错退出。在CI上很有用。

用法

import { defineConfig } from '@playwright/test';

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

类型

• boolean

fullyParallel​

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

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• boolean

全局设置​

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

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• string | Array<string>

全局拆卸​

全局清理文件的路径。该文件将在所有测试完成后被引入并执行。它必须导出一个单独的函数。另请参阅testConfig.globalSetup。可以传递一个路径数组来指定多个全局清理文件。

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• string | Array<string>

全局超时​

整个测试套件运行的最长时间（毫秒）。零超时（默认）会禁用此行为。在CI环境中非常有用，可以防止因设置问题导致运行时间过长和资源浪费。了解更多关于各种超时的信息。

用法

import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalTimeout: process.env.CI ? 60 * 60 * 1000 : undefined,
});

类型

• number

grep​

筛选仅运行标题匹配任一模式的测试。例如，传入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/,
});

类型

• RegExp | Array<RegExp>

grepInvert​

筛选仅运行标题不匹配任一模式的测试。这是testConfig.grep的反向操作。也可通过command line中的--grep-invert选项使用。

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

用法

import { defineConfig } from '@playwright/test';

export default defineConfig({
  grepInvert: /manual/,
});

类型

• RegExp | Array<RegExp>

ignoreSnapshots​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• boolean

maxFailures​

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

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• number

元数据​

Metadata contains key-value pairs to be included in the report. For example, HTML report will display it as key-value pairs, and JSON report will include metadata serialized as json.

用法

import { defineConfig } from '@playwright/test';

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

类型

• 元数据

名称​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• string

outputDir​

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

用法

import { defineConfig } from '@playwright/test';

export default defineConfig({
  outputDir: './test-results',
});

类型

• string

详情

该目录在开始时会被清空。运行测试时，会在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​

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

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

用法

import { defineConfig } from '@playwright/test';

export default defineConfig({
  preserveOutput: 'always',
});

类型

• "always" | "never" | "failures-only"

项目​

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

用法

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    { name: 'chromium', use: devices['Desktop Chrome'] }
  ]
});

类型

• Array<TestProject>

静默​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• boolean

repeatEach​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• number

reportSlowTests​

是否报告运行缓慢的测试文件。传递null可禁用此功能。

用法

import { defineConfig } from '@playwright/test';

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

类型

• null | Object

  • max number

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

  • threshold number

    被视为缓慢的测试文件持续时间（毫秒）。默认为5分钟。

详情

测试文件耗时超过threshold毫秒将被视为慢测试，系统会报告其中最慢的文件，数量不超过max个。如果将max设为零，则会报告所有超过阈值的测试文件。

报告器​

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

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

你可以通过元组形式向报告器传递选项，例如 ['json', { outputFile: './report.json' }]。

了解更多信息，请参阅报告指南。

用法

import { defineConfig } from '@playwright/test';

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

类型

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

  • 0 string

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

  • 1 Object

    一个包含报告器选项的对象（如果有的话）

respectGitIgnore​

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

用法

testConfig.respectGitIgnore

类型

• boolean

重试次数​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• number

分片​

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

了解更多关于使用Playwright Test进行并行测试和分片的信息。

用法

import { defineConfig } from '@playwright/test';

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

类型

• null | Object

  • current number

    要执行的分片索引，从1开始计数。

  • total number

    分片的总数。

snapshotPathTemplate​

此选项配置一个模板，用于控制由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}',
    },
  },
});

类型

• string

详情

该值可能包含一些"令牌"，这些令牌将在测试执行期间被实际值替换。

考虑以下文件结构：

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} - Relative snapshot path without extension. This comes from the arguments passed to toHaveScreenshot(), toMatchAriaSnapshot() or toMatchSnapshot(); if called without arguments, this will be an auto-generated snapshot name.
  • 值: foo/bar/baz
• {ext} - Snapshot extension (with the leading dot).
  • 值: .png
• {platform} - process.platform的值。
• {projectName} - Project's file-system-sanitized name, if any.
  • 值: '' (空字符串).
• {snapshotDir} - Project's testProject.snapshotDir.
  • 值: /home/playwright/tests (由于配置中未提供snapshotDir，默认使用testDir)
• {testDir} - Project's testProject.testDir.
  • 值: /home/playwright/tests (绝对路径，因为testDir是相对于配置文件所在目录解析的)
• {testFileDir} - Directories in relative path from testDir to test file.
  • 值: page
• {testFileName} - Test file name with extension.
  • 值: page-click.spec.ts
• {testFilePath} - Relative path from testDir to test file.
  • 值: page/page-click.spec.ts
• {testName} - File-system-sanitized test title, including parent describes but excluding file name.
  • 值: 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' } },
  ],
});

在此配置中：

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

testDir​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• string

testIgnore​

符合这些模式之一的文件不会作为测试文件执行。匹配是针对绝对文件路径进行的。字符串被视为全局模式。

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• string | RegExp | Array<string | RegExp>

testMatch​

只有匹配这些模式之一的文件才会作为测试文件执行。匹配是针对绝对文件路径进行的。字符串被视为全局模式。

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

类型

• string | RegExp | Array<string | RegExp>

超时时间​

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

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• number

tsconfig​

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• string

updateSnapshots​

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

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

了解更多关于snapshots的信息。

用法

import { defineConfig } from '@playwright/test';

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

类型

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

updateSourceMethod​

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

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

用法

testConfig.updateSourceMethod

类型

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

使用​

所有测试的全局选项，例如 testOptions.browserName。了解更多关于configuration的信息，并查看available options。

用法

import { defineConfig } from '@playwright/test';

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

类型

• TestOptions

web服务器​

在测试期间启动一个开发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');
});

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

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

类型

• Object | 数组<Object>

  • command string

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

  • cwd string (可选)

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

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

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

  • ignoreHTTPSErrors boolean (可选)

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

  • port number (可选)

    您的HTTP服务器预期运行的端口。它会等待直到可以接受连接。必须指定port或url其中一个参数。

  • reuseExistingServer boolean (可选)

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

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

    如果设置为"pipe"，会将命令的标准输出通过管道传输到进程的标准输出。如果设置为"ignore"，则会忽略命令的标准输出。默认为"ignore"。

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

    是否将命令的标准错误输出(stderr)传递给进程的标准错误输出或忽略它。默认为"pipe"。

  • timeout number (可选)

    等待进程启动并可用所需的时间，以毫秒为单位。默认为60000。

  • gracefulShutdown Object (可选)

    • signal "SIGINT" | "SIGTERM"

    • timeout number

    如何关闭进程。如果未指定，进程组将被强制SIGKILL终止。如果设置为{ signal: 'SIGTERM', timeout: 500 }，进程组会先收到SIGTERM信号，若500毫秒内未退出则发送SIGKILL。您也可以使用SIGINT作为替代信号。0超时值表示不会发送SIGKILL。Windows系统不支持SIGTERM和SIGINT信号，因此该选项在Windows上会被忽略。请注意关闭Docker容器需要使用SIGTERM。

  • url string (可选)

    当服务器准备接受连接时，您的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会生成等于http://localhost:8080的baseURL。如果将webServer指定为数组，则必须显式配置baseURL（即使它只有一个条目）。

工作线程​

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

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

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

用法

import { defineConfig } from '@playwright/test';

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

类型

• number | string

已弃用​

snapshotDir​

用于存储通过toMatchSnapshot创建的快照文件的基础目录，相对于配置文件的位置。默认为testConfig.testDir。

用法

import { defineConfig } from '@playwright/test';

export default defineConfig({
  snapshotDir: './snapshots',
});

类型

• string

详情

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

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