TestProject

Playwright 测试支持同时运行多个测试项目。这对于在多种配置中运行测试很有用。例如，考虑针对多个浏览器运行测试。此类型描述了配置文件中项目的格式，要在运行时访问已解析的配置参数，请使用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'],
    },
  ],
});

属性

依赖项

新增于：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'],
    },
  ],
});

类型

数组<字符串>

预期

新增于：v1.10

testProject.expect

expect 断言库的配置。

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

用法

testProject.expect

类型

对象
- timeout 数字 （可选）
  
  异步预期匹配器的默认超时时间（以毫秒为单位），默认为 5000 毫秒。
- toHaveScreenshot 对象 （可选）
  - threshold 数字 （可选）
    
    比较图像中相同像素之间可接受的感知颜色差异，范围从 0（严格）到 1（宽松）。"pixelmatch" 比较器计算YIQ 颜色空间中的颜色差异，并将 threshold 值默认为 0.2。
  - maxDiffPixels 数字 （可选）
    
    可以不同的像素数量，默认为未设置。
  - maxDiffPixelRatio 数字 （可选）
    
    不同的像素与像素总数之间的可接受比率，介于 0 和 1 之间，默认为未设置。
  - animations "allow" | "disabled" （可选）
    
    请参阅动画中的page.screenshot()。默认为 "disabled"。
  - caret "hide" | "initial" （可选）
    
    请参阅插入符号中的page.screenshot()。默认为 "hide"。
  - scale "css" | "device" （可选）
    
    请参阅缩放中的page.screenshot()。默认为 "css"。
  - stylePath 字符串 | 数组<字符串> （可选）
    
    请参阅样式中的page.screenshot()。
  expect(page).toHaveScreenshot() 方法的配置。
- toMatchSnapshot 对象 （可选）
  - threshold 数字 （可选）
    
    比较图像中相同像素之间可接受的感知颜色差异，范围从 0（严格）到 1（宽松）。"pixelmatch" 比较器计算YIQ 颜色空间中的颜色差异，并将 threshold 值默认为 0.2。
  - maxDiffPixels 数字 （可选）
    
    可以不同的像素数量，默认为未设置。
  - maxDiffPixelRatio 数字 （可选）
    
    不同的像素与像素总数之间的可接受比率，介于 0 和 1 之间，默认为未设置。
  expect(value).toMatchSnapshot() 方法的配置。
- toPass 对象 （可选）
  - timeout 数字 （可选）
    
    toPass 方法的超时时间（以毫秒为单位）。
  - intervals 数组<数字> （可选）
    
    toPass 方法的探测间隔时间（以毫秒为单位）。
  expect(value).toPass() 方法的配置。

完全并行

新增于：v1.10

testProject.fullyParallel

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

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

用法

testProject.fullyParallel

类型

布尔值

grep

新增于：v1.10

testProject.grep

筛选器，仅运行标题与其中一个模式匹配的测试。例如，传递 grep: /cart/ 应该只运行标题中包含“cart”的测试。还可以在全局和命令行中使用 -g 选项获得。正则表达式将针对由项目名称、测试文件名、test.describe 名称（如果有）、测试名称和测试标签（用空格分隔）组成的字符串进行测试，例如 chromium my-test.spec.ts my-suite my-test。

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

用法

testProject.grep

类型

正则表达式 | 数组<正则表达式>

grepInvert

新增于：v1.10

testProject.grepInvert

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

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

用法

testProject.grepInvert

类型

正则表达式 | 数组<正则表达式>

忽略快照

新增于：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,
    },
  ],
});

类型

布尔值

元数据

新增于：v1.10

testProject.metadata

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

用法

testProject.metadata

类型

元数据

名称

新增于：v1.10

testProject.name

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

用法

testProject.name

类型

字符串

输出目录

新增于：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

类型

字符串

重复每个

新增于：v1.10

testProject.repeatEach

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

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

用法

testProject.repeatEach

类型

数字

respectGitIgnore

新增于：v1.45

testProject.respectGitIgnore

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

用法

testProject.respectGitIgnore

类型

布尔值

retries

新增于：v1.10

testProject.retries

分配给失败测试的最大重试次数。详细了解测试重试。

使用 test.describe.configure() 更改特定文件或一组测试的重试次数。

使用 testConfig.retries 更改所有项目的此选项。

用法

testProject.retries

类型

数字

snapshotDir

新增于：v1.10

testProject.snapshotDir

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

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

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

用法

testProject.snapshotDir

类型

字符串

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

类型

字符串

详情

该值可能包含一些将在测试执行期间替换为实际值的“标记”。

考虑以下文件结构

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

类型

字符串

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

类型

字符串

testIgnore

新增于：v1.10

testProject.testIgnore

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

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

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

用法

testProject.testIgnore

类型

字符串 | RegExp | 数组<字符串 | RegExp>

testMatch

新增于：v1.10

testProject.testMatch

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

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

使用 testConfig.testMatch 更改所有项目的此选项。

用法

testProject.testMatch

类型

字符串 | RegExp | 数组<字符串 | RegExp>

timeout

新增于：v1.10

testProject.timeout

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

这是所有测试的基本超时时间。每个测试都可以使用 test.setTimeout() 配置其自己的超时时间。每个文件或一组测试可以使用 test.describe.configure() 配置超时时间。

使用 testConfig.timeout 更改所有项目的此选项。

用法

testProject.timeout

类型

数字

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

属性​

依赖项​

预期​

完全并行​

grep​

grepInvert​

忽略快照​

元数据​

名称​

输出目录​

重复每个​

respectGitIgnore​

retries​

snapshotDir​

snapshotPathTemplate​

teardown​

testDir​

testIgnore​

testMatch​

timeout​

use​

属性

依赖项

预期

完全并行

grep

grepInvert

忽略快照

元数据

名称

输出目录

重复每个

respectGitIgnore

retries

snapshotDir

snapshotPathTemplate

teardown

testDir

testIgnore

testMatch

timeout

use