TestInfo

TestInfo 包含当前运行测试的相关信息。它可用于测试函数、test.beforeEach()、test.afterEach()、test.beforeAll() 和 test.afterAll() 钩子函数，以及测试作用域的 fixtures。TestInfo 提供了控制测试执行的实用工具：附加文件、更新测试超时、确定当前运行的测试以及是否重试等。

import { test, expect } from '@playwright/test';

test('basic test', async ({ page }, testInfo) => {
  expect(testInfo.title).toBe('basic test');
  await page.screenshot(testInfo.outputPath('screenshot.png'));
});

---

方法

attach

添加于: v1.10 testInfo.attach

将值或磁盘文件附加到当前测试。某些报告器会显示测试附件。必须指定 path 或 body 之一，但不能同时指定两者。

例如，您可以将屏幕截图附加到测试中：

import { test, expect } from '@playwright/test';

test('basic test', async ({ page }, testInfo) => {
  await page.goto('https://playwright.dev');
  const screenshot = await page.screenshot();
  await testInfo.attach('screenshot', { body: screenshot, contentType: 'image/png' });
});

或者您可以附加 API 返回的文件：

import { test, expect } from '@playwright/test';
import { download } from './my-custom-helpers';

test('basic test', async ({}, testInfo) => {
  const tmpPath = await download('a');
  await testInfo.attach('downloaded', { path: tmpPath });
});

备注

testInfo.attach() 会自动处理将附件文件复制到报告器可访问的位置。在等待 attach 调用完成后，您可以安全地删除附件。

用法

await testInfo.attach(name);
await testInfo.attach(name, options);

参数

• name string#

  附件名称。名称会被清理并用作保存到磁盘时的文件名前缀。

• options Object (可选)

  • body string | Buffer (可选)#

    附件内容。与 path 互斥。

  • contentType string (可选)#

    附件的内容类型，用于在报告中正确显示，例如 'application/json' 或 'image/png'。如果省略，则基于 path 推断内容类型，对于 string 附件默认为 text/plain，对于 Buffer 附件默认为 application/octet-stream。

  • path string (可选)#

    附件文件在文件系统中的路径。与 body 互斥。

返回值

• Promise<void>#

---

fail()

Added in: v1.10 testInfo.fail()

将当前运行的测试标记为"预期失败"。Playwright Test 会运行此测试并确保它确实失败。这对于文档目的很有用，可以确认某些功能在修复前是损坏的。这与 test.fail() 类似。

用法

testInfo.fail();

---

fail(condition)

Added in: v1.10 testInfo.fail(condition)

根据条件将当前运行的测试标记为"预期失败"，可附加描述信息。这与 test.fail() 类似。

用法

testInfo.fail(condition);
testInfo.fail(condition, description);

参数

• condition boolean#

  当条件为 true 时，测试会被标记为"预期失败"。

• description string (可选)#

  可选描述信息，会在测试报告中显示。

---

fixme()

Added in: v1.10 testInfo.fixme()

将测试标记为"待修复"，表示有意修复它。测试会立即中止。这与 test.fixme() 类似。

用法

testInfo.fixme();

fixme(condition)

添加于: v1.10 testInfo.fixme(condition)

根据条件将当前运行的测试标记为"待修复"（可附加描述）。此方法与 test.fixme() 类似。

用法

testInfo.fixme(condition);
testInfo.fixme(condition, description);

参数

• condition boolean#

  当条件为 true 时，测试会被标记为"待修复"。

• description string (可选)#

  可选描述信息，会在测试报告中显示。

---

outputPath

添加于: v1.10 testInfo.outputPath

返回 testInfo.outputDir 内的一个路径，测试可以安全地在此存放临时文件。确保并行运行的测试不会相互干扰。

import { test, expect } from '@playwright/test';
import fs from 'fs';

test('example test', async ({}, testInfo) => {
  const file = testInfo.outputPath('dir', 'temporary-file.txt');
  await fs.promises.writeFile(file, 'Put some data to the dir/temporary-file.txt', 'utf8');
});

注意 pathSegments 接受指向测试输出目录的路径片段，例如 testInfo.outputPath('relative', 'path', 'to', 'output')。 但是该路径必须位于每个测试的 testInfo.outputDir 目录内（即 test-results/a-test-title），否则会抛出异常。

用法

testInfo.outputPath(...pathSegments);

参数

• ...pathSegments Array<string>#

  要附加在结果路径末尾的路径片段。

返回值

• string#

---

setTimeout

添加于: v1.10 testInfo.setTimeout

修改当前运行测试的超时时间。零表示无超时限制。了解更多关于各种超时设置。

超时时间通常在配置文件中指定，但在某些场景下修改超时时间会很有用：

import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }, testInfo) => {
  // 为所有运行此钩子的测试延长30秒超时时间
  testInfo.setTimeout(testInfo.timeout + 30000);
});

用法

testInfo.setTimeout(timeout);

参数

• timeout number#

  超时时间（毫秒）。

---

skip()

添加于: v1.10 testInfo.skip()

无条件跳过当前运行的测试。测试会立即中止。这与 test.skip() 类似。

用法

testInfo.skip();

---

skip(condition)

添加于: v1.10 testInfo.skip(condition)

根据条件跳过当前运行的测试，可附加描述信息。此方法与 test.skip() 类似。

用法

testInfo.skip(condition);
testInfo.skip(condition, description);

参数

• condition boolean#

  跳过条件。当条件为 true 时跳过测试。

• description string (可选)#

  可选描述信息，会显示在测试报告中。

---

slow()

添加于: v1.10 testInfo.slow()

将当前运行的测试标记为"慢速测试"，使其获得三倍于默认的超时时间。此方法与 test.slow() 类似。

用法

testInfo.slow();

---

slow(condition)

添加于: v1.10 testInfo.slow(condition)

根据条件将当前运行的测试标记为"慢速测试"，可附加描述信息，使其获得三倍于默认的超时时间。这与 test.slow() 类似。

用法

testInfo.slow(condition);
testInfo.slow(condition, description);

参数

• condition boolean#

  当条件为 true 时，测试会被标记为"慢速测试"。

• description string (可选)#

  可选描述信息，将会反映在测试报告中。

---

snapshotPath

添加于: v1.10 testInfo.snapshotPath

返回带有给定 name 的快照文件路径。通过传递 kind 可以获取特定类型的路径：

• kind: 'screenshot' 用于 expect(page).toHaveScreenshot();
• kind: 'aria' 用于 expect(locator).toMatchAriaSnapshot();
• kind: 'snapshot' 用于 expect(value).toMatchSnapshot().

用法

await expect(page).toHaveScreenshot('header.png');
// 上述截图断言期望在此路径下找到截图:
const screenshotPath = test.info().snapshotPath('header.png', { kind: 'screenshot' });

await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });
// 上述 ARIA 快照断言期望在此路径下找到快照:
const ariaSnapshotPath = test.info().snapshotPath('main.aria.yml', { kind: 'aria' });

expect('some text').toMatchSnapshot('snapshot.txt');
// 上述快照断言期望在此路径下找到快照:
const snapshotPath = test.info().snapshotPath('snapshot.txt');

expect('some text').toMatchSnapshot(['dir', 'subdir', 'snapshot.txt']);
// 上述快照断言期望在此路径下找到快照:
const nestedPath = test.info().snapshotPath('dir', 'subdir', 'snapshot.txt');

参数

• ...name Array<string>#

  快照名称或定义快照文件路径的路径片段。同一测试文件中相同名称的快照预期是相同的。

  当传递 kind 时，不支持多个名称片段。

• options Object (可选)

  • kind "snapshot" | "screenshot" | "aria" (可选) 添加于: v1.53#

    快照类型控制使用哪个快照路径模板。详情请参阅 testConfig.snapshotPathTemplate。默认为 'snapshot'。

返回值

• string#

---

属性

annotations

添加于: v1.10 testInfo.annotations

适用于当前测试的注解列表。包括来自测试本身的注解、测试所属的所有 test.describe() 组的注解，以及测试文件的文件级注解。

了解更多关于 测试注解 的信息。

用法

testInfo.annotations

类型

• Array<Object>

  • type string

    注解类型，例如 'skip' 或 'fail'。

  • description string (可选)

    可选的描述信息。

---

attachments

添加于: v1.10 testInfo.attachments

附加到当前测试的文件或缓冲区列表。某些报告器会显示测试附件。

要添加附件，请使用 testInfo.attach() 方法，而不是直接向此数组推送内容。

用法

testInfo.attachments

类型

• Array<Object>

  • name string

    附件名称。

  • contentType string

    附件的内容类型，用于在报告中正确显示，例如 'application/json' 或 'image/png'。

  • path string (可选)

    可选的文件系统中附件路径。

  • body Buffer (可选)

    可选的附件内容，用于替代文件。

---

column

添加于: v1.10 testInfo.column

当前运行测试声明所在的列号。

用法

testInfo.column

类型

• number

---

config

Added in: v1.10 testInfo.config

从配置文件处理后的配置信息。

用法

testInfo.config

类型

• FullConfig

---

duration

Added in: v1.10 testInfo.duration

测试完成所用的毫秒数。在测试完成前（无论成功与否）始终为零。可在test.afterEach()钩子中使用。

用法

testInfo.duration

类型

• number

---

error

Added in: v1.10 testInfo.error

测试执行期间抛出的第一个错误（如果有）。该值与testInfo.errors数组中的第一个元素相同。

用法

testInfo.error

类型

• TestInfoError

---

errors

Added in: v1.10 testInfo.errors

测试执行期间抛出的所有错误（如果有）。

用法

testInfo.errors

类型

• Array<TestInfoError>

---

expectedStatus

Added in: v1.10 testInfo.expectedStatus

当前运行测试的预期状态。通常为 'passed'，除以下情况外：

• 'skipped' 表示跳过的测试，例如使用 test.skip()；
• 'failed' 表示标记为失败的测试，使用 test.fail()。

预期状态通常会与实际 testInfo.status 进行比较：

import { test, expect } from '@playwright/test';

test.afterEach(async ({}, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus)
    console.log(`${testInfo.title} did not run as expected!`);
});

用法

testInfo.expectedStatus

类型

• "passed" | "failed" | "timedOut" | "skipped" | "interrupted"

---

file

Added in: v1.10 testInfo.file

声明当前运行测试的文件的绝对路径。

用法

testInfo.file

类型

• string

---

fn

Added in: v1.10 testInfo.fn

传递给 test(title, testFunction) 的测试函数。

用法

testInfo.fn

类型

• function

---

line

Added in: v1.10 testInfo.line

声明当前运行测试的行号。

用法

testInfo.line

类型

• number

---

outputDir

Added in: v1.10 testInfo.outputDir

当前测试运行的输出目录绝对路径。每个测试运行都有自己独立的目录，因此不会产生冲突。

用法

testInfo.outputDir

类型

• string

---

parallelIndex

Added in: v1.10 testInfo.parallelIndex

工作线程的索引值，范围在 0 到 workers - 1 之间。可以保证同时运行的工作线程具有不同的 parallelIndex。当工作线程重启时（例如失败后），新工作线程进程会保持相同的 parallelIndex。

也可以通过 process.env.TEST_PARALLEL_INDEX 获取。了解更多关于 Playwright Test 的并行测试和分片功能。

用法

testInfo.parallelIndex

类型

• number

---

project

Added in: v1.10 testInfo.project

从配置文件中处理后的项目配置信息。

用法

testInfo.project

类型

• FullProject

---

repeatEachIndex

Added in: v1.10 testInfo.repeatEachIndex

在"重复执行"模式下运行时指定的唯一重复索引。该模式通过向命令行传递 --repeat-each 参数启用。

用法

testInfo.repeatEachIndex

类型

• number

---

retry

Added in: v1.10 testInfo.retry

指定测试失败后重试时的重试次数。首次运行测试时 testInfo.retry 值为零，第一次重试时值为一，以此类推。了解更多关于 重试机制 的信息。

import { test, expect } from '@playwright/test';

test.beforeEach(async ({}, testInfo) => {
  // 你可以在任何钩子或 fixture 中访问 testInfo.retry
  if (testInfo.retry > 0)
    console.log(`正在重试!`);
});

test('my test', async ({ page }, testInfo) => {
  // 这里我们在重试时清除一些服务端状态
  if (testInfo.retry)
    await cleanSomeCachesOnTheServer();
  // ...
});

用法

testInfo.retry

类型

• number

---

snapshotDir

Added in: v1.10 testInfo.snapshotDir

当前测试专用的快照输出目录的绝对路径。每个测试套件都有独立的目录，因此不会产生冲突。

此属性不考虑 testProject.snapshotPathTemplate 配置。

用法

testInfo.snapshotDir

类型

• string

---

snapshotSuffix

添加于: v1.10 testInfo.snapshotSuffix

备注

不建议使用 testInfo.snapshotSuffix。请改用 testConfig.snapshotPathTemplate 来配置快照路径。

用于区分多个测试配置之间快照的后缀。例如，如果快照依赖于平台，可以将 testInfo.snapshotSuffix 设置为 process.platform。在这种情况下，expect(value).toMatchSnapshot(snapshotName) 将根据平台使用不同的快照。了解更多关于快照的信息。

用法

testInfo.snapshotSuffix

类型

• string

---

status

添加于: v1.10 testInfo.status

当前运行测试的实际状态。在测试完成后，可通过 test.afterEach() 钩子和 fixture 获取。

通常会将此状态与 testInfo.expectedStatus 进行比较：

import { test, expect } from '@playwright/test';

test.afterEach(async ({}, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus)
    console.log(`${testInfo.title} did not run as expected!`);
});

用法

testInfo.status

类型

• "passed" | "failed" | "timedOut" | "skipped" | "interrupted"

---

tags

Added in: v1.43 testInfo.tags

适用于当前测试的标签。了解更多关于标签的信息。

备注

测试运行时对此列表的任何修改都不会对测试报告器可见。

用法

testInfo.tags

类型

• Array<string>

---

testId

Added in: v1.32 testInfo.testId

与报告器API中测试用例ID匹配的测试ID。

用法

testInfo.testId

类型

• string

---

timeout

Added in: v1.10 testInfo.timeout

当前运行测试的超时时间（毫秒）。零表示无超时限制。了解更多关于各种超时设置。

超时时间通常在配置文件中指定

import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }, testInfo) => {
  // 为所有运行此钩子的测试延长30秒超时时间
  testInfo.setTimeout(testInfo.timeout + 30000);
});

用法

testInfo.timeout

类型

• number

---

title

Added in: v1.10 testInfo.title

当前运行测试的标题，即传递给test(title, testFunction)的标题。

用法

testInfo.title

类型

• string

---

titlePath

Added in: v1.10 testInfo.titlePath

从测试文件名开始的完整标题路径。

用法

testInfo.titlePath

类型

• Array<string>

---

workerIndex

添加于: v1.10 testInfo.workerIndex

运行测试的 worker 进程的唯一索引。当 worker 重启时（例如失败后），新的 worker 进程会获得一个新的唯一 workerIndex。

也可以通过 process.env.TEST_WORKER_INDEX 获取。了解更多关于 Playwright Test 的并行和分片机制。

用法

testInfo.workerIndex

类型

• number