测试报告器

简介

Playwright Test 提供了多种内置报告器以满足不同需求，同时也支持自定义报告器。尝试内置报告器最简单的方式是通过 --reporter 命令行选项。

npx playwright test --reporter=line

如需更多控制，可以在配置文件中以编程方式指定报告器。

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

export default defineConfig({
  reporter: 'line',
});

多报告器模式

您可以同时使用多个报告器。例如，可以使用 'list' 获得美观的终端输出，同时使用 'json' 生成包含完整测试结果的 JSON 文件。

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

export default defineConfig({
  reporter: [
    ['list'],
    ['json', {  outputFile: 'test-results.json' }]
  ],
});

CI 环境报告器

您可以在本地环境和 CI 环境中使用不同的报告器。例如，使用简洁的 'dot' 报告器可以避免过多输出。这是 CI 环境中的默认设置。

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

export default defineConfig({
  // CI 环境使用简洁的 'dot'，本地运行时默认使用 'list'
  reporter: process.env.CI ? 'dot' : 'list',
});

内置报告器

所有内置报告器都会显示详细的失败信息，主要区别在于对成功测试运行的详细程度不同。

列表报告器

列表报告器是默认的报告器（在 CI 环境中默认使用 dot 报告器）。它会为每个运行的测试打印一行输出。

npx playwright test --reporter=list

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

export default defineConfig({
  reporter: 'list',
});

以下是测试运行中的示例输出。失败案例将在最后列出。

npx playwright test --reporter=list
运行 124 个测试，使用 6 个工作线程

✓ 应该访问环境中的错误 (438ms)
✓ 处理长测试名称 (515ms)
x 1) 渲染预期结果 (691ms)
✓ 应该超时 (932ms)
  应该重复每个:
✓ 应该遵循外层 .gitignore (569ms)
  应该在超时后清理环境:
  应该遵循排除的测试:
✓ 应该处理 beforeEach 环境错误 (638ms)
  应该遵循外层 .gitignore:

您可以通过以下配置选项启用步骤渲染功能：

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

export default defineConfig({
  reporter: [['list', { printSteps: true }]],
});

列表报告器支持以下配置选项和环境变量：

环境变量名称	报告器配置选项	描述	默认值
`PLAYWRIGHT_LIST_PRINT_STEPS`	`printSteps`	是否将每个步骤单独打印一行	`false`
`PLAYWRIGHT_FORCE_TTY`		是否生成适合实时终端的输出。如果指定数字，则同时用作终端宽度	终端处于 TTY 模式时为 `true`，否则为 `false`
`FORCE_COLOR`		是否生成彩色输出	终端处于 TTY 模式时为 `true`，否则为 `false`

行式报告器

行式报告器比列表式报告器更加简洁。它使用单行来报告最后完成的测试，并在出现失败时打印相关信息。行式报告器适用于大型测试套件，它能够显示进度而不会通过列出所有测试来刷屏输出。

npx playwright test --reporter=line

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

export default defineConfig({
  reporter: 'line',
});

以下是测试运行中的示例输出。失败信息会内联显示。

npx playwright test --reporter=line
运行 124 个测试，使用 6 个工作线程
  1) dot-reporter.spec.ts:20:1 › render expected ===================================================

    错误: expect(received).toBe(expected) // Object.is equality

    预期值: 1
    实际值: 0

[23/124] gitignore.spec.ts - 应遵守嵌套的 .gitignore 规则

行式报告器支持以下配置选项和环境变量：

环境变量名	报告器配置选项	描述	默认值
`PLAYWRIGHT_FORCE_TTY`		是否生成适合实时终端的输出。如果指定了数字，它也将用作终端宽度。	当终端处于 TTY 模式时为 `true`，否则为 `false`
`FORCE_COLOR`		是否生成彩色输出。	当终端处于 TTY 模式时为 `true`，否则为 `false`

点状报告器

点状报告器非常简洁 - 每个成功的测试运行只输出一个字符。它是 CI 环境中的默认报告器，适用于不需要大量输出的场景。

npx playwright test --reporter=dot

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

export default defineConfig({
  reporter: 'dot',
});

以下是测试运行中的示例输出。失败案例将在最后列出。

npx playwright test --reporter=dot
运行 124 个测试，使用 6 个工作线程
······F·············································

每个已运行的测试都会显示一个字符，表示其状态：

字符	描述
`·`	通过
`F`	失败
`×`	失败或超时 - 将会重试
`±`	重试后通过 (不稳定)
`T`	超时
`°`	跳过

点状报告器支持以下配置选项和环境变量：

环境变量名称	报告器配置选项	描述	默认值
`PLAYWRIGHT_FORCE_TTY`		是否生成适合实时终端的输出。如果指定了数字，它也将用作终端宽度。	终端处于 TTY 模式时为 `true`，否则为 `false`
`FORCE_COLOR`		是否生成彩色输出。	终端处于 TTY 模式时为 `true`，否则为 `false`

HTML 报告生成器

HTML 报告生成器会创建一个自包含的文件夹，其中包含可作为网页提供的测试运行报告。

npx playwright test --reporter=html

默认情况下，如果某些测试失败，HTML 报告会自动打开。您可以通过 Playwright 配置中的 open 属性或 PLAYWRIGHT_HTML_OPEN 环境变量来控制此行为。该属性的可能值为 always（总是）、never（从不）和 on-failure（仅在失败时，默认值）。

您还可以配置用于提供 HTML 报告的 host 和 port。

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

export default defineConfig({
  reporter: [['html', { open: 'never' }]],
});

默认情况下，报告会写入当前工作目录下的 playwright-report 文件夹。可以使用 PLAYWRIGHT_HTML_OUTPUT_DIR 环境变量或报告生成器配置来覆盖该位置。

在配置文件中，直接传递选项：

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

export default defineConfig({
  reporter: [['html', { outputFolder: 'my-report' }]],
});

如果您将附件从数据文件夹上传到其他位置，可以使用 attachmentsBaseURL 选项让 HTML 报告知道在哪里查找它们。

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

export default defineConfig({
  reporter: [['html', { attachmentsBaseURL: 'https://external-storage.com/' }]],
});

快速打开最后一次测试运行报告的方法是：

npx playwright show-report

或者如果有自定义文件夹名称：

npx playwright show-report my-report

HTML 报告支持以下配置选项和环境变量：

环境变量名称	报告生成器配置选项	描述	默认值
`PLAYWRIGHT_HTML_TITLE`	`title`	在生成的报告中显示的标题。	默认不显示标题
`PLAYWRIGHT_HTML_OUTPUT_DIR`	`outputFolder`	保存报告的目录。	`playwright-report`
`PLAYWRIGHT_HTML_OPEN`	`open`	何时在浏览器中打开 HTML 报告，可选值为 `'always'`、`'never'` 或 `'on-failure'`	`'on-failure'`
`PLAYWRIGHT_HTML_HOST`	`host`	当报告在浏览器中打开时，将绑定到此主机名提供服务。	`localhost`
`PLAYWRIGHT_HTML_PORT`	`port`	当报告在浏览器中打开时，将在此端口上提供服务。	`9323` 或当 `9323` 不可用时使用任何可用端口
`PLAYWRIGHT_HTML_ATTACHMENTS_BASE_URL`	`attachmentsBaseURL`	单独的位置，用于上传来自 `data` 子目录的附件。仅当您将报告和 `data` 分别上传到不同位置时才需要。	`data/`

Blob 报告器

Blob 报告包含测试运行的所有详细信息，可用于后续生成其他类型的报告。其主要功能是便于合并来自分片测试的报告。

npx playwright test --reporter=blob

默认情况下，报告会写入 package.json 所在目录或当前工作目录（如果未找到 package.json）下的 blob-report 目录。报告文件名格式为 report-<hash>.zip，当使用分片时会变为 report-<hash>-<shard_number>.zip。哈希值是根据 --grep、--grepInverted、--project 以及作为命令行参数传递的文件过滤器计算得出的可选值。该哈希值确保 Playwright 使用不同命令行选项运行时会产生不同但稳定的报告名称。输出文件名可以通过配置文件覆盖或通过 'PLAYWRIGHT_BLOB_OUTPUT_FILE' 环境变量指定。

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

export default defineConfig({
  reporter: [['blob', { outputFile: `./blob-report/report-${os.platform()}.zip` }]],
});

Blob 报告支持以下配置选项和环境变量：

环境变量名	报告器配置选项	描述	默认值
`PLAYWRIGHT_BLOB_OUTPUT_DIR`	`outputDir`	保存输出的目录。写入新报告前会删除现有内容。	`blob-report`
`PLAYWRIGHT_BLOB_OUTPUT_NAME`	`fileName`	报告文件名。	`report-<project>-<hash>-<shard_number>.zip`
`PLAYWRIGHT_BLOB_OUTPUT_FILE`	`outputFile`	输出文件的完整路径。如果指定，将忽略 `outputDir` 和 `fileName`。	`undefined`

JSON 报告器

JSON 报告器会生成一个包含测试运行所有信息的对象。

通常情况下，您会希望将 JSON 写入文件。当使用 --reporter=json 运行时，可以通过 PLAYWRIGHT_JSON_OUTPUT_NAME 环境变量指定输出文件：

Bash
PowerShell
Batch

PLAYWRIGHT_JSON_OUTPUT_NAME=results.json npx playwright test --reporter=json

$env:PLAYWRIGHT_JSON_OUTPUT_NAME="results.json"
npx playwright test --reporter=json

set PLAYWRIGHT_JSON_OUTPUT_NAME=results.json
npx playwright test --reporter=json

在配置文件中，可以直接传递选项：

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

export default defineConfig({
  reporter: [['json', { outputFile: 'results.json' }]],
});

JSON 报告支持以下配置选项和环境变量：

环境变量名称	报告器配置选项	描述	默认值
`PLAYWRIGHT_JSON_OUTPUT_DIR`		保存输出文件的目录。如果已指定输出文件则忽略此选项。	`cwd` 或配置目录
`PLAYWRIGHT_JSON_OUTPUT_NAME`	`outputFile`	输出文件的基础名称，相对于输出目录。	JSON 报告会输出到 stdout
`PLAYWRIGHT_JSON_OUTPUT_FILE`	`outputFile`	输出文件的完整路径。如果定义此变量，将忽略 `PLAYWRIGHT_JSON_OUTPUT_DIR` 和 `PLAYWRIGHT_JSON_OUTPUT_NAME`。	JSON 报告会输出到 stdout

JUnit 报告器

JUnit 报告器会生成符合 JUnit 风格的 XML 报告。

通常情况下，您需要将报告写入 XML 文件。当使用 --reporter=junit 运行时，可以通过 PLAYWRIGHT_JUNIT_OUTPUT_NAME 环境变量指定输出文件：

Bash
PowerShell
Batch

PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junit

$env:PLAYWRIGHT_JUNIT_OUTPUT_NAME="results.xml"
npx playwright test --reporter=junit

set PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml
npx playwright test --reporter=junit

在配置文件中，可以直接传递选项：

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

export default defineConfig({
  reporter: [['junit', { outputFile: 'results.xml' }]],
});

JUnit 报告支持以下配置选项和环境变量：

环境变量名称	报告器配置选项	描述	默认值
`PLAYWRIGHT_JUNIT_OUTPUT_DIR`		输出文件的保存目录。如果未指定输出文件则忽略此设置。	`cwd` 或配置目录
`PLAYWRIGHT_JUNIT_OUTPUT_NAME`	`outputFile`	输出的基础文件名，相对于输出目录。	JUnit 报告会输出到 stdout
`PLAYWRIGHT_JUNIT_OUTPUT_FILE`	`outputFile`	输出文件的完整路径。如果定义此变量，将忽略 `PLAYWRIGHT_JUNIT_OUTPUT_DIR` 和 `PLAYWRIGHT_JUNIT_OUTPUT_NAME`。	JUnit 报告会输出到 stdout
`PLAYWRIGHT_JUNIT_STRIP_ANSI`	`stripANSIControlSequences`	是否在写入报告前移除文本中的 ANSI 控制序列。	默认按原样输出文本
`PLAYWRIGHT_JUNIT_INCLUDE_PROJECT_IN_TEST_NAME`	`includeProjectInTestName`	是否在每个测试用例名称前添加 Playwright 项目名称作为前缀。	默认不包含
`PLAYWRIGHT_JUNIT_SUITE_ID`		根节点 `<testsuites/>` 报告中 `id` 属性的值。	空字符串
`PLAYWRIGHT_JUNIT_SUITE_NAME`		根节点 `<testsuites/>` 报告中 `name` 属性的值。	空字符串

GitHub Actions 注解

在 GitHub Actions 中运行时，您可以使用内置的 github 报告器来获取自动失败注解。

请注意，所有其他报告器也可以在 GitHub Actions 中工作，但不会提供注解。此外，如果使用矩阵策略运行测试，不建议使用此注解类型，因为堆栈跟踪失败会成倍增加并干扰 GitHub 文件视图。

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

export default defineConfig({
  // 在 GitHub Actions CI 中使用 'github' 生成注解，并附加简洁的 'dot'
  // 本地运行时默认使用 'list'
  reporter: process.env.CI ? 'github' : 'list',
});

自定义报告器

您可以通过实现一个包含部分报告器方法的类来创建自定义报告器。了解更多关于 Reporter API 的信息。

my-awesome-reporter.ts
import type {
  FullConfig, FullResult, Reporter, Suite, TestCase, TestResult
} from '@playwright/test/reporter';

class MyReporter implements Reporter {
  onBegin(config: FullConfig, suite: Suite) {
    console.log(`开始运行，共 ${suite.allTests().length} 个测试`);
  }

  onTestBegin(test: TestCase, result: TestResult) {
    console.log(`开始测试 ${test.title}`);
  }

  onTestEnd(test: TestCase, result: TestResult) {
    console.log(`完成测试 ${test.title}: ${result.status}`);
  }

  onEnd(result: FullResult) {
    console.log(`运行结束: ${result.status}`);
  }
}

export default MyReporter;

现在可以通过 testConfig.reporter 使用这个报告器。

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

export default defineConfig({
  reporter: './my-awesome-reporter.ts',
});

或者直接通过 --reporter 命令行选项传递报告器文件路径：

npx playwright test --reporter="./myreporter/my-awesome-reporter.ts"

以下是编写自定义报告器时可参考的开源报告器实现列表：

简介​

多报告器模式​

CI 环境报告器​

内置报告器​

列表报告器​

行式报告器​

点状报告器​

HTML 报告生成器​

Blob 报告器​

JSON 报告器​

JUnit 报告器​

GitHub Actions 注解​

自定义报告器​

简介