报告器

介绍

🌐 Introduction

Playwright Test 提供了一些内置的报告工具，以满足不同的需求，并且可以提供自定义报告工具。尝试内置报告工具的最简单方法是传递 --reporter 命令行选项。

🌐 Playwright Test comes with a few built-in reporters for different needs and ability to provide custom reporters. The easiest way to try out built-in reporters is to pass --reporter command line option.

npx playwright test --reporter=line

为了获得更多控制，你可以在配置文件中以编程方式指定报告器。

🌐 For more control, you can specify reporters programmatically in the configuration file.

playwright.config.ts

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

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

多报告器

🌐 Multiple reporters

你可以同时使用多个报告器。例如，你可以使用 'list' 来获得漂亮的终端输出，同时使用 'json' 获取包含测试结果的完整 JSON 文件。

🌐 You can use multiple reporters at the same time. For example you can use 'list' for nice terminal output and 'json' to get a comprehensive json file with the test results.

playwright.config.ts

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

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

CI 报告器

🌐 Reporters on CI

你可以在本地和持续集成（CI）中使用不同的报告器。例如，使用简洁的 'dot' 报告器可以避免输出过多内容。这是 CI 上的默认设置。

🌐 You can use different reporters locally and on CI. For example, using concise 'dot' reporter avoids too much output. This is the default on CI.

playwright.config.ts

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

export default defineConfig({
  // Concise 'dot' for CI, default 'list' when running locally
  reporter: process.env.CI ? 'dot' : 'list',
});

内置报告器

🌐 Built-in reporters

所有内置报告器都会显示有关失败的详细信息，并且成功运行的详细信息大多有所不同。

🌐 All built-in reporters show detailed information about failures, and mostly differ in verbosity for successful runs.

列表报告器

🌐 List reporter

列表报告器是默认的（除了在 CI 上，dot 报告器是默认的）。它会为每个正在运行的测试打印一行。

🌐 List reporter is default (except on CI where the dot reporter is default). It prints a line for each test being run.

npx playwright test --reporter=list

playwright.config.ts

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

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

这是测试运行中间的示例输出。失败将在最后列出。

🌐 Here is an example output in the middle of a test run. Failures will be listed at the end.

npx playwright test --reporter=list
Running 124 tests using 6 workers

 1  ✓ should access error in env (438ms)
 2  ✓ handle long test names (515ms)
 3  x 1) render expected (691ms)
 4  ✓ should timeout (932ms)
 5    should repeat each:
 6  ✓ should respect enclosing .gitignore (569ms)
 7    should teardown env after timeout:
 8    should respect excluded tests:
 9  ✓ should handle env beforeEach error (638ms)
10    should respect enclosing .gitignore:

你可以通过传递以下配置选项来选择进入步骤渲染：

🌐 You can opt into the step rendering via passing the following config option:

playwright.config.ts

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

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

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

🌐 List report supports the following configuration options and environment variables:

环境变量名称	报告器配置选项	描述	默认值
PLAYWRIGHT_LIST_PRINT_STEPS	printSteps	是否将每个步骤打印在单独的一行上。	false
PLAYWRIGHT_FORCE_TTY		是否生成适合实时终端的输出。支持 true、1、false、0、[WIDTH] 和 [WIDTH]x[HEIGHT]。[WIDTH] 和 [WIDTH]x[HEIGHT] 指定 TTY 尺寸。	当终端处于 TTY 模式时为 true，否则为 false。
FORCE_COLOR		是否生成彩色输出。	当终端处于 TTY 模式时为 true，否则为 false。

行报告器

🌐 Line reporter

行报告器比列表报告器更简洁。它使用一行来报告最后完成的测试，并在出现失败时打印错误信息。行报告器对于大型测试套件非常有用，因为它显示进度，但不会通过列出所有测试来淹没输出信息。

🌐 Line reporter is more concise than the list reporter. It uses a single line to report last finished test, and prints failures when they occur. Line reporter is useful for large test suites where it shows the progress but does not spam the output by listing all the tests.

npx playwright test --reporter=line

playwright.config.ts

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

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

这是测试运行中间的示例输出。失败会在行内报告。

🌐 Here is an example output in the middle of a test run. Failures are reported inline.

npx playwright test --reporter=line
Running 124 tests using 6 workers
  1) dot-reporter.spec.ts:20:1 › render expected ===================================================

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

    Expected: 1
    Received: 0

[23/124] gitignore.spec.ts - should respect nested .gitignore

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

🌐 Line report supports the following configuration options and environment variables:

环境变量名称	Reporter配置选项	描述	默认值
PLAYWRIGHT_FORCE_TTY		是否生成适用于实时终端的输出。支持 true、1、false、0、[WIDTH] 和 [WIDTH]x[HEIGHT]。[WIDTH] 和 [WIDTH]x[HEIGHT] 指定TTY尺寸。	当终端为TTY模式时为 true，否则为 false。
FORCE_COLOR		是否生成彩色输出。	当终端为TTY模式时为 true，否则为 false。

点报告器

🌐 Dot reporter

点报告器非常简洁——每次成功的测试运行只会产生一个字符。它是 CI 的默认设置，并且在你不希望有大量输出时非常有用。

🌐 Dot reporter is very concise - it only produces a single character per successful test run. It is the default on CI and useful where you don't want a lot of output.

npx playwright test --reporter=dot

playwright.config.ts

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

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

这是测试运行中间的示例输出。失败将在最后列出。

🌐 Here is an example output in the middle of a test run. Failures will be listed at the end.

npx playwright test --reporter=dot
Running 124 tests using 6 workers
······F·············································

为每个已运行的测试显示一个字符，指示其状态：

🌐 One character is displayed for each test that has run, indicating its status:

字符	描述
·	通过
F	未通过
×	未通过或超时 - 将重试
±	重试通过（不稳定）
T	超时
°	跳过

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

🌐 Dot report supports the following configuration options and environment variables:

环境变量名称	Reporter配置选项	描述	默认值
PLAYWRIGHT_FORCE_TTY		是否生成适用于实时终端的输出。支持 true、1、false、0、[WIDTH] 和 [WIDTH]x[HEIGHT]。[WIDTH] 和 [WIDTH]x[HEIGHT] 指定TTY尺寸。	当终端为TTY模式时为 true，否则为 false。
FORCE_COLOR		是否生成彩色输出。	当终端为TTY模式时为 true，否则为 false。

HTML 报告器

🌐 HTML reporter

HTML 报告器生成一个独立的文件夹，其中包含可用作网页的测试运行报告。

🌐 HTML reporter produces a self-contained folder that contains report for the test run that can be served as a web page.

npx playwright test --reporter=html

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

🌐 By default, HTML report is opened automatically if some of the tests failed. You can control this behavior via the open property in the Playwright config or the PLAYWRIGHT_HTML_OPEN environmental variable. The possible values for that property are always, never and on-failure (default).

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

🌐 You can also configure host and port that are used to serve the HTML report.

playwright.config.ts

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

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

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

🌐 By default, report is written into the playwright-report folder in the current working directory. One can override that location using the PLAYWRIGHT_HTML_OUTPUT_DIR environment variable or a reporter configuration.

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

🌐 In configuration file, pass options directly:

playwright.config.ts

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

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

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

🌐 If you are uploading attachments from a data folder to another location, you can use attachmentsBaseURL option to let html report know where to look for them.

playwright.config.ts

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

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

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

🌐 A quick way of opening the last test run report is:

npx playwright show-report

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

🌐 Or if there is a custom folder name:

npx playwright show-report my-report

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

🌐 HTML report supports the following configuration options and environment variables:

Environment Variable Name	Reporter Config Option	Description	Default
PLAYWRIGHT_HTML_TITLE	title	A title to display in the generated report.	No title is displayed by default
PLAYWRIGHT_HTML_OUTPUT_DIR	outputFolder	Directory to save the report to.	playwright-report
PLAYWRIGHT_HTML_OPEN	open	When to open the html report in the browser, one of 'always', 'never' or 'on-failure'	'on-failure'
PLAYWRIGHT_HTML_HOST	host	When report opens in the browser, it will be served bound to this hostname.	localhost
PLAYWRIGHT_HTML_PORT	port	When report opens in the browser, it will be served on this port.	9323 or any available port when 9323 is not available.
PLAYWRIGHT_HTML_ATTACHMENTS_BASE_URL	attachmentsBaseURL	A separate location where attachments from the data subdirectory are uploaded. Only needed when you upload report and data separately to different locations.	data/
PLAYWRIGHT_HTML_NO_COPY_PROMPT	noCopyPrompt	If true, disable rendering of the Copy prompt for errors. Supports true, 1, false, and 0.	false
PLAYWRIGHT_HTML_NO_SNIPPETS	noSnippets	If true, disable rendering code snippets in the action log. If there is a top level error, that report section with code snippet will still render. Supports true, 1, false, and 0.	false

Blob 报告器

🌐 Blob reporter

Blob 报告包含关于测试运行的所有详细信息，可在以后用于生成任何其他报告。它们的主要功能是便于合并来自分片测试的报告。

🌐 Blob reports contain all the details about the test run and can be used later to produce any other report. Their primary function is to facilitate the merging of reports from sharded tests.

npx playwright test --reporter=blob

默认情况下，报告会写入 package.json 目录下的 blob-report 目录中，或者如果未找到 package.json，则写入当前工作目录。

🌐 By default, the report is written into the blob-report directory in the package.json directory or current working directory (if no package.json is found).

报告文件名在使用sharding时看起来像 report-<hash>.zip 或 report-<hash>-<shard_number>.zip。哈希是一个可选值，它是根据 --grep、--grepInverted、--project、testConfig.tag 以及作为命令行参数传入的文件过滤器计算得出的。该哈希保证了使用不同命令行选项运行 Playwright 时，会生成不同但在多次运行之间保持稳定的报告名称。输出文件名可以在配置文件中覆盖，也可以作为 'PLAYWRIGHT_BLOB_OUTPUT_FILE' 环境变量传入。

Shards

在使用 blob 报告合并多个分片时，你不需要传递任何选项。

🌐 When using blob report to merge multiple shards, you don't have to pass any options.

playwright.config.ts

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

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

Environments

在不同环境中运行测试时，你可能希望使用 testConfig.tag 添加与环境对应的全局标签。此标签将使合并报告更加清晰，并且将用于生成唯一的 blob 报告名称。

🌐 When running tests in different environments, you might want to use testConfig.tag to add a global tag corresponding to the environment. This tag will bring clarity to the merged report, and it will be used to produce a unique blob report name.

playwright.config.ts

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

export default defineConfig({
  reporter: 'blob',
  tag: process.env.CI_ENVIRONMENT_NAME,  // for example "@APIv2" or "@linux"
});

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

🌐 Blob report supports following configuration options and environment variables:

环境变量名称	报告配置选项	描述	默认值
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 reporter

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

🌐 JSON reporter produces an object with all information about the test run.

你很可能想把 JSON 写入文件。在使用 --reporter=json 运行时，请使用 PLAYWRIGHT_JSON_OUTPUT_NAME 环境变量：

🌐 Most likely you want to write the JSON to a file. When running with --reporter=json, use PLAYWRIGHT_JSON_OUTPUT_NAME environment variable:

Bash

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

PowerShell

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

Batch

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

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

🌐 In configuration file, pass options directly:

playwright.config.ts

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

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

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

🌐 JSON report supports following configuration options and environment variables:

环境变量名称	Reporter 配置选项	描述	默认值
PLAYWRIGHT_JSON_OUTPUT_DIR		保存输出文件的目录。如果指定了输出文件则该项被忽略。	cwd 或配置目录。
PLAYWRIGHT_JSON_OUTPUT_NAME	outputFile	输出文件的基础文件名，相对于输出目录。	JSON 报告将打印到标准输出。
PLAYWRIGHT_JSON_OUTPUT_FILE	outputFile	输出文件的完整路径。如果定义了，则 PLAYWRIGHT_JSON_OUTPUT_DIR 和 PLAYWRIGHT_JSON_OUTPUT_NAME 将被忽略。	JSON 报告将打印到标准输出。

JUnit 报告器

🌐 JUnit reporter

JUnit 报告器生成 JUnit 样式的 xml 报告。

🌐 JUnit reporter produces a JUnit-style xml report.

你很可能想将报告写入 XML 文件。运行 --reporter=junit 时，请使用 PLAYWRIGHT_JUNIT_OUTPUT_NAME 环境变量：

🌐 Most likely you want to write the report to an xml file. When running with --reporter=junit, use PLAYWRIGHT_JUNIT_OUTPUT_NAME environment variable:

Bash

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

PowerShell

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

Batch

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

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

🌐 In configuration file, pass options directly:

playwright.config.ts

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

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

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

🌐 JUnit report supports following configuration options and environment variables:

环境变量名称	Reporter 配置选项	描述	默认值
PLAYWRIGHT_JUNIT_OUTPUT_DIR		保存输出文件的目录。如果未指定输出文件，则忽略。	cwd 或配置目录
PLAYWRIGHT_JUNIT_OUTPUT_NAME	outputFile	输出的基础文件名，相对于输出目录。	JUnit 报告输出到标准输出
PLAYWRIGHT_JUNIT_OUTPUT_FILE	outputFile	输出文件的完整路径。如果定义了此项，将忽略 PLAYWRIGHT_JUNIT_OUTPUT_DIR 和 PLAYWRIGHT_JUNIT_OUTPUT_NAME。	JUnit 报告输出到标准输出
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 annotations

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

🌐 You can use the built in github reporter to get automatic failure annotations when running in GitHub actions.

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

🌐 Note that all other reporters work on GitHub Actions as well, but do not provide annotations. Also, it is not recommended to use this annotation type if running your tests with a matrix strategy as the stack trace failures will multiply and obscure the GitHub file view.

playwright.config.ts

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

export default defineConfig({
  // 'github' for GitHub Actions CI to generate annotations, plus a concise 'dot'
  // default 'list' when running locally
  reporter: process.env.CI ? 'github' : 'list',
});

定制报告器

🌐 Custom reporters

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

🌐 You can create a custom reporter by implementing a class with some of the reporter methods. Learn more about the 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(`Starting the run with ${suite.allTests().length} tests`);
  }

  onTestBegin(test: TestCase, result: TestResult) {
    console.log(`Starting test ${test.title}`);
  }

  onTestEnd(test: TestCase, result: TestResult) {
    console.log(`Finished test ${test.title}: ${result.status}`);
  }

  onEnd(result: FullResult) {
    console.log(`Finished the run: ${result.status}`);
  }
}

export default MyReporter;

现在使用这个报道器与testConfig.reporter一起。

🌐 Now use this reporter with testConfig.reporter.

playwright.config.ts

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

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

或者只需将报告器文件路径作为 --reporter 命令行选项传递:

🌐 Or just pass the reporter file path as --reporter command line option:

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

以下是开源报告器实现的简短列表，你可以在编写自己的报告器时查看：

🌐 Here's a short list of open source reporter implementations that you can take a look at when writing your own reporter:

• Allure 报告器
• Github Actions 报告器
• 邮件报告器
• ReportPortal
• Monocart