TestProject

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

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

这是一个示例配置，它在 Chromium、Firefox 和 WebKit 的桌面版和移动版中运行每个测试。

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

export default defineConfig({
  // Options shared for all projects.
  timeout: 30000,
  use: {
    ignoreHTTPSErrors: true,
  },

  // Options specific to each project.
  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

类型

对象
- timeout number (可选)
  
  异步 expect 匹配器的默认超时时间，以毫秒为单位，默认为 5000 毫秒。
- toHaveScreenshot Object (可选)
  - threshold number (可选)
    
    比较图像中相同像素之间可接受的感知颜色差异，范围从 0 (严格) 到 1 (宽松)。 "pixelmatch" 比较器计算 YIQ 色彩空间中的颜色差异，并将默认 threshold 值设置为 0.2。
  - maxDiffPixels number (可选)
    
    可以不同的像素的可接受数量，默认情况下未设置。
  - maxDiffPixelRatio number (可选)
    
    不同像素与像素总量的可接受比率，介于 0 和 1 之间，默认情况下未设置。
  - animations "allow" | "disabled" (可选)
    
    请参阅 animations 中的 page.screenshot()。默认为 "disabled"。
  - caret "hide" | "initial" (可选)
    
    请参阅 caret 中的 page.screenshot()。默认为 "hide"。
  - scale "css" | "device" (可选)
    
    请参阅 scale 中的 page.screenshot()。默认为 "css"。
  - stylePath string | Array<string> (可选)
    
    请参阅 style 中的 page.screenshot()。
  用于 expect(page).toHaveScreenshot() 方法的配置。
- 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

添加于: v1.10

testProject.fullyParallel

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

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

用法

testProject.fullyParallel

类型

boolean

grep

添加于: 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

添加于: v1.10

testProject.grepInvert

筛选器，仅运行标题不与其中一个模式匹配的测试。这与 testProject.grep 相反。也可全局使用，并在命令行中使用 --grep-invert 选项。

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

用法

testProject.grepInvert

类型

RegExp | Array<RegExp>

ignoreSnapshots

添加于: 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

添加于: v1.10

testProject.metadata

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

用法

testProject.metadata

类型

元数据

name

添加于: v1.10

testProject.name

项目名称在报告和测试执行期间可见。

用法

testProject.name

类型

string

outputDir

添加于: 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

添加于: v1.10

testProject.repeatEach

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

使用 testConfig.repeatEach 为所有项目更改此选项。

用法

testProject.repeatEach

类型

number

respectGitIgnore

添加于: v1.45

testProject.respectGitIgnore

在搜索测试文件时是否跳过 .gitignore 中的条目。默认情况下，如果未显式指定 testConfig.testDir 和 testProject.testDir，Playwright 将忽略与 .gitignore 条目匹配的任何测试文件。此选项允许覆盖该行为。

用法

testProject.respectGitIgnore

类型

boolean

retries

添加于: 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(value).toMatchSnapshot() 生成的快照的位置。

用法

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

export default defineConfig({
  testDir: './tests',
  snapshotPathTemplate: '{testDir}/__screenshots__/{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() 和 toMatchSnapshot() 调用的参数；如果在没有参数的情况下调用，这将是一个自动生成的快照名称。
- 值: foo/bar/baz
{ext} - 快照扩展名（带点）
- 值: .png
{platform} - process.platform 的值。
{projectName} - 项目的文件系统安全名称（如果有）。
- 值: '' (空字符串)。
{snapshotDir} - 项目的 testConfig.snapshotDir。
- 值: /home/playwright/tests (由于配置中未提供 snapshotDir，因此默认为 testDir)
{testDir} - 项目的 testConfig.testDir。
- 值: /home/playwright/tests (绝对路径是因为 testDir 是相对于配置目录解析的)
{testFileDir} - 从 testDir 到测试文件的相对路径中的目录。
- 值: page
{testFileName} - 带有扩展名的测试文件名。
- 值: page-click.spec.ts
{testFilePath} - 从 testDir 到测试文件的相对路径
- 值: page/page-click.spec.ts
{testName} - 文件系统安全测试标题，包括父级 describe，但不包括文件名。
- 值: 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

添加于: 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

添加于: v1.10

testProject.testIgnore

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

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

使用 testConfig.testIgnore 为所有项目更改此选项。

用法

testProject.testIgnore

类型

string | RegExp | Array<string | RegExp>

testMatch

添加于: 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

添加于: 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

属性​

dependencies​

expect​

fullyParallel​

grep​

grepInvert​

ignoreSnapshots​

metadata​

name​

outputDir​

repeatEach​

respectGitIgnore​

retries​

snapshotDir​

snapshotPathTemplate​

teardown​

testDir​

testIgnore​

testMatch​

timeout​

use​

属性

dependencies

expect

fullyParallel

grep

grepInvert

ignoreSnapshots

metadata

name

outputDir

repeatEach

respectGitIgnore

retries

snapshotDir

snapshotPathTemplate

teardown

testDir

testIgnore

testMatch

timeout

use