TestProject

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

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

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

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

属性​

依赖项​

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

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

用法

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​

expect 断言库的配置。

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

用法

testProject.expect

类型

• Object

  • timeout number (可选)

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

  • 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" (可选)

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

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

      参见 scale 在 page.screenshot() 中的说明。默认为 "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​

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

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

用法

testProject.fullyParallel

类型

• boolean

grep​

筛选仅运行标题匹配任一模式的测试。例如，传入grep: /cart/应仅运行标题中包含"cart"的测试。该功能也可全局使用，并通过命令行的-g选项实现。正则表达式将针对由项目名称、测试文件名、test.describe名称（如果有）、测试名称和测试标签组成的字符串进行匹配测试，这些元素以空格分隔，例如chromium my-test.spec.ts my-suite my-test。

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

用法

testProject.grep

类型

• RegExp | Array<RegExp>

grepInvert​

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

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

用法

testProject.grepInvert

类型

• RegExp | Array<RegExp>

ignoreSnapshots​

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

用法

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

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

元数据​

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

用法

testProject.metadata

类型

• 元数据

名称​

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

用法

testProject.name

类型

• string

outputDir​

测试执行期间生成文件的输出目录。默认为 /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​

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

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

用法

testProject.repeatEach

类型

• number

respectGitIgnore​

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

用法

testProject.respectGitIgnore

类型

• boolean

重试次数​

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

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

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

用法

testProject.retries

类型

• number

snapshotDir​

用于存放通过toMatchSnapshot创建的截图文件的基础目录，相对于配置文件的位置。默认为testProject.testDir。

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

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

用法

testProject.snapshotDir

类型

• string

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

拆卸​

需要在本项目及其所有依赖项目完成后运行的项目名称。拆卸(Teardown)有助于清理本项目获取的任何资源。

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

用法

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

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​

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

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

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​

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

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

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

用法

testProject.testIgnore

类型

• string | RegExp | Array<string | RegExp>

testMatch​

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

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

超时时间​

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

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

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

用法

testProject.timeout

类型

• number

使用​

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

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

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

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

用法

testProject.use

类型

• TestOptions