TestProject

Playwright Test 支持同时运行多个测试项目。这对于在多种配置下运行测试非常有用。例如，可以考虑针对多个浏览器运行测试。此类型描述了配置文件中项目的格式，要在运行时访问已解析的配置参数，请使用 FullProject。

TestProject 封装了特定于单个项目的配置。项目在配置文件中指定的 testConfig.projects 中进行配置。请注意，TestProject 的所有属性在顶层 TestConfig 中也可用，在这种情况下它们会在所有项目之间共享。

以下是一个示例配置，该配置在 Chromium、Firefox 和 WebKit 的桌面版和移动版上运行每个测试。

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

export default defineConfig({
  // 所有项目共享的选项
  timeout: 30000,
  use: {
    ignoreHTTPSErrors: true,
  },

  // 每个项目特定的选项
  projects: [
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
    },
    {
      name: 'Mobile Chrome',
      use: devices['Pixel 5'],
    },
    {
      name: 'Mobile Safari',
      use: devices['iPhone 12'],
    },
  ],
});

属性

dependencies

添加于: v1.31

testProject.dependencies

列出在当前项目任何测试运行前需要先运行的项目列表。依赖项可用于以测试形式配置全局设置操作。传递 --no-deps 参数会忽略依赖项，表现得好像它们未被指定一样。

使用依赖项允许全局设置生成追踪记录和其他产物，在测试报告中查看设置步骤等。

用法

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

export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /global.setup\.ts/,
    },
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
      dependencies: ['setup'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
      dependencies: ['setup'],
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
      dependencies: ['setup'],
    },
  ],
});

类型

Array<string>

expect

v1.10 版本新增

testProject.expect

expect 断言库的配置项。

使用 testConfig.expect 可以为所有项目修改此选项。

用法

testProject.expect

类型

Object
- timeout number (可选)
  
  异步 expect 匹配器的默认超时时间（毫秒），默认为 5000ms。
- toHaveScreenshot Object (可选)
  - threshold number (可选)
    
    比较图像中相同像素之间可接受的感知色差，范围从 0（严格）到 1（宽松）。"pixelmatch" 比较器在 YIQ 色彩空间中计算色差，默认 threshold 值为 0.2。
  - maxDiffPixels number (可选)
    
    允许存在差异的最大像素数量，默认未设置。
  - maxDiffPixelRatio number (可选)
    
    允许存在差异的像素占总像素的比例，范围在 0 到 1 之间，默认未设置。
  - animations "allow" | "disabled" (可选)
    
    参见 page.screenshot() 中的 animations。默认为 "disabled"。
  - caret "hide" | "initial" (可选)
    
    参见 page.screenshot() 中的 caret。默认为 "hide"。
  - scale "css" | "device" (可选)
    
    参见 page.screenshot() 中的 scale。默认为 "css"。
  - stylePath string | Array<string> (可选)
    
    参见 page.screenshot() 中的 style。
  - pathTemplate string (可选)
    
    控制截图保存位置的模板。详情参见 testProject.snapshotPathTemplate。
  expect(page).toHaveScreenshot() 方法的配置项。
- toMatchAriaSnapshot Object (可选)
  - pathTemplate string (可选)
    
    控制 ARIA 快照保存位置的模板。详情参见 testProject.snapshotPathTemplate。
  expect(locator).toMatchAriaSnapshot() 方法的配置项。
- toMatchSnapshot Object (可选)
  - threshold number (可选)
    
    比较图像中相同像素之间可接受的感知色差，范围从 0（严格）到 1（宽松）。"pixelmatch" 比较器在 YIQ 色彩空间中计算色差，默认 threshold 值为 0.2。
  - maxDiffPixels number (可选)
    
    允许存在差异的最大像素数量，默认未设置。
  - maxDiffPixelRatio number (可选)
    
    允许存在差异的像素占总像素的比例，范围在 0 到 1 之间，默认未设置。
  expect(value).toMatchSnapshot() 方法的配置项。
- toPass Object (可选)
  - timeout number (可选)
    
    toPass 方法的超时时间（毫秒）。
  - intervals Array<number> (可选)
    
    toPass 方法的探测间隔时间（毫秒）。
  expect(value).toPass() 方法的配置项。

fullyParallel

Added in: v1.10

testProject.fullyParallel

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

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

用法

testProject.fullyParallel

类型

boolean

grep

Added in: v1.10

testProject.grep

筛选器，仅运行标题匹配指定模式的测试。例如，传递 grep: /cart/ 将只运行标题中包含 "cart" 的测试。此选项也可全局使用，或在命令行中使用 -g 选项。正则表达式将针对由项目名称、测试文件名、test.describe 名称（如果有）、测试名称和测试标签组成的字符串进行匹配，这些内容以空格分隔，例如 chromium my-test.spec.ts my-suite my-test。

grep 选项也适用于标记测试。

用法

testProject.grep

类型

RegExp | Array<RegExp>

grepInvert

Added in: v1.10

testProject.grepInvert

筛选不匹配指定模式的测试用例运行。这是 testProject.grep 的反向操作。该选项也可全局使用或在命令行通过 --grep-invert 参数指定。

grepInvert 选项也适用于测试标记。

用法

testProject.grepInvert

类型

RegExp | Array<RegExp>

ignoreSnapshots

Added in: v1.44

testProject.ignoreSnapshots

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

用法

以下示例将仅在 Chromium 上执行截图断言。

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

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
      ignoreSnapshots: true,
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
      ignoreSnapshots: true,
    },
  ],
});

类型

boolean

metadata

Added in: v1.10

testProject.metadata

将直接以 JSON 格式序列化到测试报告中的元数据。

用法

testProject.metadata

类型

Metadata

name

Added in: v1.10

testProject.name

项目名称会在测试报告和执行过程中显示。

注意

Playwright 会多次执行配置文件。请不要在配置中动态生成不稳定的值。

用法

testProject.name

类型

string

outputDir

Added in: v1.10

testProject.outputDir

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

该目录会在开始时被清空。运行测试时，会在 testProject.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');
});

使用 testConfig.outputDir 可为所有项目修改此选项。

用法

testProject.outputDir

类型

string

repeatEach

Added in: v1.10

testProject.repeatEach

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

使用 testConfig.repeatEach 可以为所有项目修改此选项。

用法

testProject.repeatEach

类型

number

respectGitIgnore

Added in: v1.45

testProject.respectGitIgnore

在搜索测试文件时是否跳过 .gitignore 中的条目。默认情况下，如果既没有明确指定 testConfig.testDir 也没有指定 testProject.testDir，Playwright 会忽略任何匹配 .gitignore 条目的测试文件。此选项允许覆盖该行为。

用法

testProject.respectGitIgnore

类型

boolean

retries

Added in: v1.10

testProject.retries

失败测试的最大重试次数。了解更多关于测试重试的信息。

使用 test.describe.configure() 可以为特定文件或测试组修改重试次数。

使用 testConfig.retries 可以为所有项目修改此选项。

用法

testProject.retries

类型

number

snapshotDir

添加于: v1.10

testProject.snapshotDir

用于存储 toMatchSnapshot 创建的快照文件的基础目录，相对于配置文件路径。默认为 testProject.testDir。

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

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

用法

testProject.snapshotDir

类型

string

snapshotPathTemplate

v1.28 版本新增

testProject.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',

  // 所有断言共用的模板
  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',

  // 特定断言的模板
  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：

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} - 文件系统安全的测试标题，包括父级描述但不包括文件名。
- 值：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' } },
  ],
});

在此配置中：

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

teardown

添加于: v1.34

testProject.teardown

指定在当前项目及其所有依赖项目运行完毕后需要执行的项目名称。teardown 可用于清理当前项目获取的任何资源。

传递 --no-deps 参数会忽略 testProject.teardown 并表现得像未指定该参数一样。

使用方式

常见模式是带有对应"teardown"的"setup"依赖项：

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

export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /global.setup\.ts/,
      teardown: 'teardown',
    },
    {
      name: 'teardown',
      testMatch: /global.teardown\.ts/,
    },
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
      dependencies: ['setup'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
      dependencies: ['setup'],
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
      dependencies: ['setup'],
    },
  ],
});

类型

string

testDir

Added in: v1.10

testProject.testDir

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

每个项目可以使用不同的目录。以下示例展示了在三种浏览器中运行冒烟测试，同时在稳定的 Chrome 浏览器中运行所有其他测试。

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

export default defineConfig({
  projects: [
    {
      name: 'Smoke Chromium',
      testDir: './smoke-tests',
      use: {
        browserName: 'chromium',
      }
    },
    {
      name: 'Smoke WebKit',
      testDir: './smoke-tests',
      use: {
        browserName: 'webkit',
      }
    },
    {
      name: 'Smoke Firefox',
      testDir: './smoke-tests',
      use: {
        browserName: 'firefox',
      }
    },
    {
      name: 'Chrome Stable',
      testDir: './',
      use: {
        browserName: 'chromium',
        channel: 'chrome',
      }
    },
  ],
});

使用 testConfig.testDir 可以为所有项目修改此选项。

用法

testProject.testDir

类型

string

testIgnore

Added in: v1.10

testProject.testIgnore

匹配这些模式的文件不会作为测试文件执行。匹配是基于文件的绝对路径进行的。字符串被视为 glob 模式。

例如，'**/test-assets/**' 会忽略 test-assets 目录中的所有文件。

使用 testConfig.testIgnore 可以为所有项目修改此选项。

用法

testProject.testIgnore

类型

string | RegExp | Array<string | RegExp>

testMatch

Added in: v1.10

testProject.testMatch

只有匹配以下模式之一的文件才会被作为测试文件执行。匹配是基于文件的绝对路径进行的。字符串会被视为 glob 模式。

默认情况下，Playwright 会查找符合以下 glob 模式的文件：**/*.@(spec|test).?(c|m)[jt]s?(x)。这意味着带有 ".test" 或 ".spec" 后缀的 JavaScript 或 TypeScript 文件，例如 login-screen.wrong-credentials.spec.ts。

使用 testConfig.testMatch 可以为所有项目更改此选项。

用法

testProject.testMatch

类型

string | RegExp | Array<string | RegExp>

timeout

Added in: v1.10

testProject.timeout

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

这是所有测试的基础超时时间。每个测试可以通过 test.setTimeout() 配置自己的超时时间。每个文件或测试组可以通过 test.describe.configure() 配置超时时间。

使用 testConfig.timeout 可以为所有项目更改此选项。

用法

testProject.timeout

类型

number

use

添加于: v1.10

testProject.use

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

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

export default defineConfig({
  projects: [
    {
      name: 'Chromium',
      use: {
        browserName: 'chromium',
      },
    },
  ],
});

使用 testConfig.use 可以为所有项目修改此选项。

用法

testProject.use

类型

TestOptions

workers

v1.52 版本新增

testProject.workers

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

这在某些场景下很有用，例如当项目中的所有测试共享单一资源（如测试账户）时，因此无法并行执行。将此类项目的 workers 限制为 1 可以防止同时使用共享资源。

请注意全局的 testConfig.workers 限制适用于所有工作进程总数。但 Playwright 会通过 testProject.workers 的值来限制该项目使用的工作进程数。

默认情况下，项目没有单独的限制。关于总 worker 限制的默认值，请参阅 testConfig.workers。

用法

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

export default defineConfig({
  workers: 10,  // 总 worker 限制

  projects: [
    {
      name: '并行运行',
    },
    {
      name: '每次一个',
      workers: 1,  // 本项目的 worker 限制
    },
  ],
});

类型

number | string

属性​

dependencies​

expect​

fullyParallel​

grep​

grepInvert​

ignoreSnapshots​

metadata​

name​

outputDir​

repeatEach​

respectGitIgnore​

retries​

snapshotDir​

snapshotPathTemplate​

teardown​

testDir​

testIgnore​

testMatch​

timeout​

use​

workers​

属性

dependencies

expect

fullyParallel

grep

grepInvert

ignoreSnapshots

metadata

name

outputDir

repeatEach

respectGitIgnore

retries

snapshotDir

snapshotPathTemplate

teardown

testDir

testIgnore

testMatch

timeout

use

workers