Playwright 测试报告器（Reporters）完全指南：内置报告器、自定义报告器与 CI 集成
【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright
Playwright Test 内置了面向不同场景的多种报告器，覆盖本地开发、CI 流水线、可视化调试与跨环境汇总等需求，并允许开发者通过实现Reporter接口编写完全自定义的报告器。本文以 docs/src/test-reporters-js.md 为核心骨架，结合仓库内packages/playwright/src/reporters/目录下的真实实现源码，系统讲解每种内置报告器的用法、配置项、环境变量及其底层行为，帮助你为测试套件选型、定制最适合的输出方案，并具备独立编写自定义报告器的能力。
报告器使用入门
Playwright Test 的每一个内置于运行时的报告器实现都位于 packages/playwright/src/reporters/ 目录下（如list.ts、html.ts、blob.ts等）。目前官方内置报告器共 10 种，定义在 packages/playwright/src/common/config.ts：
export const builtInReporters = ['list', 'line', 'dot', 'json', 'junit', 'null', 'github', 'html', 'blob', 'perfetto'] as const;其中'null'（对应empty.ts）表示不输出任何结果，通常用于只想静默运行、由其他通道收集结果的场景。
命令行--reporter选项
最直接的试用方式是给npx playwright test传入--reporter命令行选项（详见 命令行参考 docs/src/test-cli-js.md）：
npx playwright test --reporter=line从 packages/playwright/src/program.ts 可以看到，--reporter选项的取值正是上面这份内置报告器名单，并且支持逗号分隔多个值；还有一个--add-reporter选项可以"叠加"一个额外的报告器而不覆盖配置文件中已有的报告器。传入的若不在内置名单中，则会被解析为指向自定义报告器模块的路径（见 packages/playwright/src/cli/testActions.ts 中的resolveReporter逻辑：先匹配内置名，再尝试以当前工作目录解析本地文件）。
配置文件中的reporter字段
需要更多控制时，可以在 配置文件 docs/src/test-configuration-js.md 中以编程方式指定报告器：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: 'line', });配置加载阶段会调用resolveReporters对reporter字段做解析：内置报告器名直接透传，其余值通过require.resolve(id, { paths: [rootDir] })解析为模块绝对路径（见 packages/playwright/src/common/config.ts），这正是配置文件与 CLI 两种方式共用同一条解析链路的原因。
同时使用多个报告器
可以同时启用多个报告器。例如用'list'获得友好的终端输出，同时用'json'产出包含完整测试结果的 JSON 文件：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: [ ['list'], ['json', { outputFile: 'test-results.json' }] ], });多个报告器由 packages/playwright/src/reporters/multiplexer.ts 中的 Multiplexer 统一调度——它把 runner 发出的每一次事件并行转发给所有注册的报告器，因此不同报告器可以独立工作、互不干扰。
本地与 CI 使用不同报告器
可以在本地和 CI 使用不同的报告器。例如用简洁的'dot'报告器避免产生过多输出——这也是 CI 环境下的默认选择。这一默认逻辑就定义在源码中：
// packages/playwright/src/common/config.ts export const defaultReporter = process.env.CI ? 'dot' : 'list';配置示例：
import { defineConfig } from '@playwright/test'; export default defineConfig({ // Concise 'dot' for CI, default 'list' when running locally reporter: process.env.CI ? 'dot' : 'list', });由此可以看到：本地默认是list，一旦检测到CI环境变量，默认报告器自动切换为dot，而项目初始化时也会依赖 packages/playwright/src/reporters/dot.ts 与 packages/playwright/src/reporters/list.ts 这两个实现。
内置报告器总览
所有内置报告器都会对失败的测试展示详尽信息，其差异主要体现在"测试全部通过"时输出内容的详细程度上。下面逐个介绍各报告器的用法、输出示例、配置项与环境变量。
List 报告器
List 报告器是本地默认报告器（CI 上默认dot）。它为每个正在运行的测试打印一行，失败详情默认汇总在运行结束之后统一列出。
npx playwright test --reporter=listimport { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: 'list', });一次运行中途的示例输出：
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:从实现细节看，List 报告器在终端为 TTY 时会实时重绘正在执行的测试行（参见 packages/playwright/src/reporters/list.ts 中的行号/列号管理逻辑），状态标记✓（通过）与✘（失败）在 Windows 上不支持 UTF-8 的旧终端中会自动退化为ok/x（见该文件第 27–30 行）。它还对每个测试维护行映射_testRows，从而实现"跑完一个测试就原地更新其状态与耗时"的动态效果。
可以按需开启以下选项：
逐步（step）渲染——把每个test.step输出为独立的一行：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: [['list', { printSteps: true }]], });失败内联输出——一旦某个测试失败立刻打印其失败详情，而不是等待运行结束：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: [['list', { printFailuresInline: true }]], });省略标签（tags）——去掉自动追加在测试标题后的 tag：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: [['list', { omitTags: true }]], });这些配置在 list.ts 构造函数中与同名环境变量共同解析（getAsBooleanFromENV允许环境变量覆盖配置项），_printFailuresInline还会决定收尾的epilogue是否重复汇总失败（见该文件onEnd实现）。onTestPaused方法则负责调试模式下"暂停"提示与中断支持。
List 报告器支持的完整配置与环境变量如下：
| 环境变量名称 | 报告器配置项 | 说明 | 默认值 |
|---|---|---|---|
PLAYWRIGHT_LIST_PRINT_STEPS | printSteps | 是否把每个 step 单独打印为一行。 | false |
PLAYWRIGHT_LIST_PRINT_FAILURES_INLINE | printFailuresInline | 是否在测试失败后立即打印失败详情，而不是留到运行结束。 | false |
PLAYWRIGHT_LIST_OMIT_TAGS | omitTags | 是否省略自动追加到测试标题后的 tag。 | 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 | |
NO_COLOR | 是否禁用彩色输出（遵循 no-color.org 约定）。任何非空值都会禁用颜色。 | 未设置 |
Line 报告器
Line 报告器比 List 更简洁——它只使用一行来报告最新结束的测试，并在失败发生时立即打印失败信息。对于测试数量庞大的套件非常适用：既能展示进度，又不会把输出刷屏。
npx playwright test --reporter=lineimport { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: 'line', });运行中途的示例输出（失败会内联报告）：
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其中[23/124]前缀表示当前已完成第 23 个 / 共 124 个测试。对应实现见 packages/playwright/src/reporters/line.ts，其底层同样继承自TerminalReporter。
Line 报告器支持的配置选项与环境变量：
| 环境变量名称 | 报告器配置项 | 说明 | 默认值 |
|---|---|---|---|
PLAYWRIGHT_LINE_OMIT_TAGS | omitTags | 是否省略自动追加到测试标题后的 tag。 | false |
PLAYWRIGHT_FORCE_TTY | 是否产生适合实时终端显示的输出。支持true、1、false、0、[WIDTH]与[WIDTH]x[HEIGHT]。 | 终端处于 TTY 模式时为true，否则为false | |
FORCE_COLOR | 是否产生彩色输出。 | 终端处于 TTY 模式时为true，否则为false | |
NO_COLOR | 是否禁用彩色输出。任何非空值都会禁用颜色。 | 未设置 |
Dot 报告器
Dot 报告器极其简洁——每个成功运行的测试只产生一个字符。它是 CI 上的默认报告器，适合不希望产生大量输出的场景。
npx playwright test --reporter=dotimport { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: 'dot', });运行中途的示例输出（失败默认汇总在末尾）：
npx playwright test --reporter=dot Running 124 tests using 6 workers ······F·············································每个已运行的测试对应一个状态字符，含义如下：
| 字符 | 说明 |
|---|---|
· | 通过（Passed） |
F | 失败（Failed） |
× | 失败或超时，且将会被重试 |
± | 重试后通过（flaky，不稳定测试） |
T | 超时（Timed out） |
° | 跳过（Skipped） |
Dot 报告器支持的配置选项与环境变量：
| 环境变量名称 | 报告器配置项 | 说明 | 默认值 |
|---|---|---|---|
PLAYWRIGHT_DOT_OMIT_TAGS | omitTags | 是否省略自动追加到测试标题后的 tag。 | false |
PLAYWRIGHT_FORCE_TTY | 是否产生适合实时终端显示的输出。支持true、1、false、0、[WIDTH]与[WIDTH]x[HEIGHT]。 | 终端处于 TTY 模式时为true，否则为false | |
FORCE_COLOR | 是否产生彩色输出。 | 终端处于 TTY 模式时为true，否则为false | |
NO_COLOR | 是否禁用彩色输出。任何非空值都会禁用颜色。 | 未设置 |
HTML 报告器
HTML 报告器会生成一个自包含的文件夹，内含可将本次测试运行渲染为网页的报告。
npx playwright test --reporter=html默认情况下，只要存在失败的测试，HTML 报告会在运行结束后自动在浏览器中打开。这一行为可以通过配置中的open属性或PLAYWRIGHT_HTML_OPEN环境变量控制，取值只能是always、never与on-failure（默认值）。这三个取值与 packages/playwright/src/reporters/html.ts 中HtmlReportOpenOption的校验逻辑一一对应。
还可以配置host与port，用于控制报告在浏览器打开时绑定的地址与端口：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: [['html', { open: 'never' }]], });默认情况下报告写入当前工作目录下的playwright-report文件夹，可以通过PLAYWRIGHT_HTML_OUTPUT_DIR环境变量或报告器配置覆盖该位置：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: [['html', { outputFolder: 'my-report' }]], });从源码看，html.ts 在
onBegin阶段还会做一次目录冲突校验：若 HTML 报告输出目录与某个 project 的outputDir（测试产物目录）互相嵌套，会打印 Configuration Error 警告，因为 HTML 报告器会先清空自身输出目录再写入，这可能导致测试附件（截图、trace 等）被误删。
如果你要把附件从本地data目录上传到其他存储位置，可用attachmentsBaseURL选项告诉 HTML 报告去哪里查找这些附件：
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也可以直接传入.zip归档——例如从 CI 制品下载下来的压缩包。该压缩包顶层必须包含index.html，Playwright 会把它解压到临时目录并启动服务展示报告：
npx playwright show-report playwright-report.zipHTML 报告器支持的完整配置选项与环境变量：
| 环境变量名称 | 报告器配置项 | 说明 | 默认值 |
|---|---|---|---|
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/ |
PLAYWRIGHT_HTML_NO_COPY_PROMPT | noCopyPrompt | 为true时不渲染错误信息的 Copy 提示按钮。支持true、1、false、0。 | false |
PLAYWRIGHT_HTML_NO_SNIPPETS | noSnippets | 为true时不在操作日志中渲染代码片段。若存在顶层错误，该报告区块中的代码片段仍会渲染。支持true、1、false、0。 | false |
PLAYWRIGHT_HTML_DO_NOT_INLINE_ASSETS | doNotInlineAssets | 为true时，JavaScript、CSS 与报告数据会作为独立文件与index.html平级存放，而不是内联嵌入。适用于在禁止内联脚本与样式的严格 Content Security Policy 下托管报告。支持true、1、false、0。 | false |
PLAYWRIGHT_HTML_MERGE_FILES | mergeFiles | 为true时，测试按其顶层test.describe()标题而非所属文件分组。支持true、1、false、0。 | false |
Blob 报告器
Blob 报告器包含测试运行的全部细节，可事后用于生成任何其他类型的报告。它的核心用途是合并来自分片（shard）测试的报告，详见 分片执行指南 docs/src/test-sharding-js.md。
npx playwright test --reporter=blob默认情况下，报告写入package.json所在目录或当前工作目录（当找不到package.json时）下的blob-report目录。
报告文件名形如report-<hash>.zip；使用分片时则为report-<hash>-<shard_number>.zip。其中的 hash 是可选值，由命令行传入的--grep、--grepInverted、--project、TestConfig.tag以及文件过滤条件共同计算得出。这一设计保证了：使用不同命令行选项运行 Playwright 会得到不同名称的报告，而相同选项的多次运行间名称保持稳定。输出文件名可在配置文件中覆盖，或通过PLAYWRIGHT_BLOB_OUTPUT_FILE环境变量传入。
分片场景（Shards）——用 Blob 报告合并多个分片时，无需传任何选项：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: 'blob', });多环境场景（Environments）——在多个环境中分别运行测试时，可以用TestConfig.tag为每个环境追加一个全局 tag。该 tag 会给合并后的报告带来清晰的归属信息，同时也会参与生成唯一对应的 blob 报告名：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: 'blob', tag: process.env.CI_ENVIRONMENT_NAME, // for example "@APIv2" or "@linux" });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 |
分片合并完成后，可通过npx playwright merge-reports（底层实现在 packages/playwright/src/cli/reportActions.ts）把多份 blob 报告加工成 HTML 等可视化报告，这也是"海量测试跑在多个机器上、最终汇总一份报告"的标准姿势。
JSON 报告器
JSON 报告器会生成包含本次测试运行全部信息的 JSON 对象。
大多数场景下你希望把 JSON 写入文件。使用--reporter=json运行时，配合PLAYWRIGHT_JSON_OUTPUT_NAME环境变量：
PLAYWRIGHT_JSON_OUTPUT_NAME=results.json npx playwright test --reporter=jsonset PLAYWRIGHT_JSON_OUTPUT_NAME=results.json npx playwright test --reporter=json$env:PLAYWRIGHT_JSON_OUTPUT_NAME="results.json" npx playwright test --reporter=json在配置文件中直接传参：
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 |
注意上表揭示了一个通用的路径解析规则：OUTPUT_DIR+OUTPUT_NAME组合出相对路径，而OUTPUT_FILE是最高优先级的完整路径，一旦给定前两者即失效。JSON 结构中的测试数据（时长、状态、错误、附件路径等）由 packages/playwright/src/reporters/json.ts 收集整理，字段与onTestEnd/onStepEnd收到的TestResult、TestStep对象一一对应。
JUnit 报告器
JUnit 报告器生成 JUnit 风格的 XML 报告，可以被 Jenkins、GitLab CI 等大量第三方系统直接消费。
大多数场景下你会希望把报告写入 XML 文件。使用--reporter=junit时，配合PLAYWRIGHT_JUNIT_OUTPUT_NAME环境变量：
PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junitset PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junit$env:PLAYWRIGHT_JUNIT_OUTPUT_NAME="results.xml" npx playwright test --reporter=junit在配置文件中直接传参：
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_OMIT_TAGS | omitTags | 是否省略自动追加到失败详情中的测试 tag。 | false |
PLAYWRIGHT_JUNIT_SUITE_ID | 根节点<testsuites/>上id属性的值。 | 空字符串 | |
PLAYWRIGHT_JUNIT_SUITE_NAME | 根节点<testsuites/>上name属性的值。 | 空字符串 |
XML 的生成与转义逻辑见 packages/playwright/src/reporters/junit.ts。
Perfetto 报告器
Perfetto 报告器生成符合 Trace Event Format 的 JSON 文件，可在 Perfetto UI 或chrome://tracing中打开。它把整个测试运行渲染为一条时间轴：每个 worker 占一个泳道（lane），每个测试是一个切片（slice），内部再嵌套其 before/after hooks、fixtures 与步骤作为子切片。每个切片都通过 trace 事件的 arguments 携带测试或步骤的详细信息，包括源码位置、TestStep.params、tags、annotations、错误、stdio 以及附件文件路径。
npx playwright test --reporter=perfetto默认报告写入test-results/perfetto.json。当输出文件名以.gz结尾时，报告会在写盘过程中实时 gzip 压缩——Perfetto 与 chrome://tracing 两种查看器都接受 gzip 后的文件，对于大型测试运行非常值得开启：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: [['perfetto', { outputFile: 'perfetto.json.gz' }]], });Perfetto 报告器支持的配置选项与环境变量：
| 环境变量名称 | 报告器配置项 | 说明 | 默认值 |
|---|---|---|---|
PLAYWRIGHT_PERFETTO_OUTPUT_DIR | 输出文件保存目录。当指定了输出文件时被忽略。 | test-results | |
PLAYWRIGHT_PERFETTO_OUTPUT_NAME | 输出的基础文件名，相对于输出目录。 | perfetto.json | |
PLAYWRIGHT_PERFETTO_OUTPUT_FILE | outputFile | 输出文件的完整路径。一旦定义，PLAYWRIGHT_PERFETTO_OUTPUT_DIR与PLAYWRIGHT_PERFETTO_OUTPUT_NAME将被忽略。 | undefined |
GitHub Actions 注解
内置的github报告器可在 GitHub Actions 中为失败测试自动生成行内注解（annotations）。
注意：其他所有报告器在 GitHub Actions 上也能正常工作，只是不会产生注解。同时，若你在使用矩阵（matrix）策略跑测试，不建议使用这类注解——因为堆栈跟踪失败会成倍叠加，反而遮蔽 GitHub 文件视图中的真实改动。
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', });github报告器同样支持omitTags配置（或PLAYWRIGHT_GITHUB_OMIT_TAGS环境变量），用于在注解中抑制测试 tag，例如reporter: [['github', { omitTags: true }]]。
其底层实现在 packages/playwright/src/reporters/github.ts：报告器通过GitHubLogger向 stdout 输出::error file=...,line=...::message形式的 GitHub Actions workflow commands（见该文件第 40–70 行），并把换行符转义为%0A、剥离 ANSI 颜色序列，从而让失败信息精确落到对应的源文件与行号上。由于注解以::命令为前缀，报告中还特意关闭了颜色输出（colors: noColors），避免控制台染色字符污染注解内容。
编写自定义报告器
你可以通过实现一个带有若干报告器方法的类来创建自定义报告器。Reporter 接口的完整 API 参考见 Reporter 类文档 docs/src/test-reporter-api/class-reporter.md，运行时侧与之对应的底层接口定义在 packages/playwright/src/reporters/reporterV2.ts，它声明了onBegin、onTestBegin、onStdOut、onTestPaused、onEnd、onExit、onError、onStepBegin/End等全部生命周期钩子。
一个最小可用的自定义报告器示例：
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配置项：
import { defineConfig } from '@playwright/test'; export default defineConfig({ reporter: './my-awesome-reporter.ts', });或者直接把报告器文件路径作为--reporter命令行选项传入：
npx playwright test --reporter="./myreporter/my-awesome-reporter.ts"需要补充的钩子语义（可从 Reporter 接口类型声明 packages/playwright/types/testReporter.d.ts 的注释确认）：
onBegin(config, suite)：整个运行开始时调用一次，suite是包含所有子 suite 与测试的根 suite；可通过suite.allTests()拿到完整测试清单；onTestBegin(test, result)：每个测试用例运行开始时调用；onTestEnd(test, result)在其结束时调用，此时result.status、result.error、result.attachments等已就绪；onStepBegin/onStepEnd：测试内部的每个test.step与框架步骤开始时调用（底层通过TestStep描述，含category、duration、error等字段，list报告器正是依赖它实现 step 渲染）；onError(error)：捕获诸如配置错误、全局错误等不属于任何测试的错误；onEnd(result)：所有测试结束后调用一次，允许返回 Promise；它还可以返回一个status覆盖运行结果，从而影响进程退出码——这是"把失败标记为通过/把通过标记为失败"类自定义逻辑的入口；printsToStdio()：返回false表示该报告器不会向 stdout/stderr 打印内容（如 HTML 报告器），runner 可据此避免与其他终端输出的报告器产生混淆。
此外，类型上需要以@playwright/test/reporter为入口导入Reporter、Suite、TestCase、TestResult、FullResult等类型——它们与@playwright/test主入口导出的类型互补，专为报告器插件作者设计。
社区中已有若干开源报告器实现可以参考借鉴（如 Allure、Github Actions、Mail、ReportPortal、Monocart 等），在动手前阅读其源码有助于理解 hooks 的组合技巧；而从零起步时，ListReporter、JsonReporter等在 packages/playwright/src/reporters/ 中的内置实现也是很好的学习范本。
小结：报告器选型速查
| 场景 | 推荐报告器 | 关键要点 |
|---|---|---|
| 本地开发默认 | list | 每测试一行，失败汇总在末尾；支持printSteps、printFailuresInline、omitTags |
| 超大套件进度条 | line | 单行滚动输出，失败即时内联 |
| CI 最小化输出 | dot（CI 默认） | 每测试一个状态字符 |
| 人工阅读的可视化报告 | html | 自包含文件夹，show-report一键打开，可上传附件 |
| 分片/多环境合并 | blob | 全量数据中间产物，配合merge-reports再生成 HTML 等 |
| 对接第三方工具 | json/junit | 标准机器可读格式，支持 Jenkins、GitLab 等 |
| 时间线性能分析 | perfetto | 逐 worker 时间轴，支持.gz输出 |
| GitHub Actions | github | 自动生成行内失败注解，可叠加dot使用 |
| 完全静默 | null | 不输出任何报告内容 |
| 定制输出 | 自定义Reporter | 实现生命周期钩子，配置reporter指向模块路径 |
所有内置报告器都可通过--reporter命令行参数、配置文件reporter字段或PLAYWRIGHT_*系列环境变量三种方式启用与调参，且可同时叠加多个报告器以满足"终端友好 + 机器可读归档"并存的诉求。生产环境的推荐组合通常是：本地list、CI 用github/dot外加json或blob归档，再在需要时用npx playwright show-report或merge-reports将结果沉淀为一份可供团队浏览的 HTML 报告。
【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)