qa-dashboard

构建能够推动决策，而非仅仅展示数据的仪表板。这样可以避免一种常见失败模式：满屏面板只显示“5 个失败”，却没有指向失败项的链接、目标或趋势——这不过是乔装成工具的通知，到了第三周，所有人都会不再打开它。本技能提供面向特定受众的 QA 报告方案——丰富的 HTML 报告（Allure）、带回归提醒的实时趋势面板（Grafana/InfluxDB）、可自托管的 AI 辅助汇总（ReportPortal），以及自动生成的利益相关者摘要。每个面板都对应一个实际问题，每个红色指标都能深入查看失败测试。

快速导航

情况	前往
已在使用 Grafana 监控基础设施指标	Grafana 仪表板——在生产指标旁添加测试指标
测试运行器已有托管仪表板（Cypress/Playwright）	SaaS 原生仪表板——所需配置最少
需要从捆绑的 QA 运行器生成本地证据报告	本地 QA 报告
需要从现有 Allure 适配器生成丰富的 HTML 报告	Allure 报告
需要跨框架汇总并使用 AI 进行分类处理，且要求可自托管	ReportPortal
需要查看多个运行器的统一视图	Grafana 或 Allure（跨运行器汇总）
需要向利益相关者提供每周摘要／发布评估	利益相关者报告

---

调研问题

先检查 .agents/qa-project-context.md——如果该文件存在，就使用其中的信息，并跳过已回答的问题。然后：

1. 你现在使用什么工具生成测试报告？ 控制台输出、JUnit XML、HTML 报告，还是专用平台？这能确定当前的起点以及还需要多少配置工作。
2. 谁会查看仪表板？ 开发人员需要失败详情和跟踪记录；QA 负责人需要趋势和不稳定测试情况；管理层需要发布信心和缺陷率。不同受众需要不同视图。
3. 仪表板应推动哪些决策？ “此构建可以安全发布吗？”“哪些测试需要修复？”“质量是否在逐个冲刺地提升？”没有决策背景的仪表板最终只会被束之高阁。
4. 测试结果存储在哪里？ GitHub Actions 制品、S3，还是数据库？存储位置决定了哪些仪表板工具实用。
5. 使用什么 CI 平台？ GitHub Actions、GitLab CI，还是 Jenkins？它们在制品和报告集成方面各不相同。

---

核心原则

1. 仪表板应回答问题，而不是展示数字。 每个面板都必须对应一个实际问题。“不稳定率是多少？”是一个问题。“测试总数”只是无关紧要的数据。

2. 不同受众需要不同视图。 调试 CI 失败的开发人员需要堆栈跟踪、屏幕截图和跟踪记录。副总裁需要一个简单的数字：“我们准备好发布了吗？”不要强迫两者使用同一个仪表板。

3. CI 使用实时数据，管理层使用趋势。 CI 仪表板应在每次流水线运行时更新。管理层仪表板应按周或按冲刺汇总。混用更新频率会让两类受众都感到困惑。

4. 深入查看以采取行动。 每个红色指标都必须链接到具体的失败测试、不稳定测试或覆盖率缺口。显示“5 个失败”却不链接到失败项的仪表板只是通知，不是工具。

5. 自动生成报告。 需要手动操作（运行脚本、复制数据、整理幻灯片）的报告，经不起第一个繁忙的冲刺。应从 CI 流水线自动生成报告。

---

本地 QA 报告

对于使用完整 QA Skills checkout 的项目，请运行 node <qa-skills>/scripts/qa.mjs run --project <project> --goal "<current QA task>"。 打开生成的 report.html；使用 result.json 获取机器可读的判定结果。 报告包含技能路由、目标／源上下文、各项检查的证据和后续步骤。分享报告时，请保留配套日志和证据目录。

保留失败、受阻、未完成和已跳过的工作。没有观察到测试，即使退出代码为零，也不代表测试套件通过。不要用 Agent 的叙述代替缺失的证据。使用 if: always() 将运行目录发布为 CI 构建产物，以便仍可检查失败的运行。有关配置和保留策略，请参阅仓库中的 docs/QA-RUNNER.md。

Allure 报告

Allure 可根据测试结果生成内容丰富的 HTML 报告，内置历史记录、分类和重试功能。它适用于 Playwright、Jest、Vitest、pytest 和大多数框架。

Allure 2 与 Allure 3。 两种路径很容易混淆，因为框架适配器（allure-playwright、allure-vitest、allure-jest）会生成相同的 Allure 2 结果文件；区别仅在于读取器：

• Allure 2 路径 — allure-commandline（2.42.1，2026 年 6 月）。brew install allure 安装的是此版本，而不是 v3。命令：allure generate / allure open / allure serve；通过放入 allure-results/ 的 categories.json 配置分类。稳定、已冻结，目前只接受依赖版本升级。
• Allure 3 路径 — allure npm 包 + allurerc.mjs（3.9.0，2026 年 5 月）。TypeScript 重写版本：支持插件、单文件配置、实时 allure watch、项目级质量门、多环境报告，以及用于服务端历史记录的 Allure Service。命令：npx allure run / npx allure generate / npx allure watch；分类配置移至 allurerc.mjs（放入 categories.json 是 v2 的做法）。

新项目请选择 Allure 3。如果你只使用 brew install allure / allure generate 命令，就采用的是 v2 路径——这完全可行且受支持；只需清楚自己运行的是哪个版本。

对于 Allure Playwright 3.x 适配器，请在其 reporter 配置项中注册 resultsDir 和 environmentInfo，以便每次运行都将原始结果写入配置的目录。 请参阅适配器配置。

// playwright.config.ts
reporter: [
  ["list"],
  ["allure-playwright", {
    resultsDir: "allure-results",
    environmentInfo: {
      Environment: process.env.TEST_ENV ?? "local",
      BaseURL: process.env.BASE_URL ?? "http://localhost:3000",
    },
  }],
],

为每项测试添加元数据（allure.severity / feature / story / tag）以便分组；定义失败 categories，将产品缺陷与基础设施故障区分开；并在 CI 运行之间保留 history/，以便生成趋势。**没有历史记录时，Allure 报告只是单次快照——没有趋势，也无法检测间歇性故障。**完整的 Playwright/Vitest 配置、v2 categories.json、v3 allurerc.mjs + allure run 可运行路径，以及 GitHub Actions 中保留历史记录的步骤，请参阅 references/allure.md。

---

Grafana 仪表板

Grafana 可提供实时仪表板和告警功能。如果团队已经使用 Grafana 监控基础设施，并希望在生产指标旁查看测试指标，那么它最为适合。

**数据管道：**测试后的 CI 步骤会解析结果（JUnit XML、覆盖率 JSON、耗时数据），并将数据点推送到时序数据库（InfluxDB 或 Prometheus pushgateway）；Grafana 会查询这些数据。推送脚本会写入两项度量——test_execution（每项测试一个数据点，带有 suite/test_name/status/branch/run_id 标签）和 test_run_summary（每次运行一个数据点，包含 pass_rate、total、failed、avg_duration_ms）。为每个数据点添加 branch 和 run_id 标签，以便面板筛选 main 并链接回特定运行。

脚本在 if: always() 下运行，因此请用 try/flush/close 包裹写入循环——否则循环中途抛出异常会导致所有已缓冲的数据点丢失。完整的 push-test-metrics.ts（包含 flush 保护）和 GitHub Actions 步骤，请参阅 references/grafana.md。

推荐面板

面板	问题	查询形式
通过率趋势（时间序列）	质量是否在提升？	SELECT mean("pass_rate") FROM "test_run_summary" WHERE "branch"='main' GROUP BY time(1d)，阈值设为 95%（黄色）/99%（绿色）
发布就绪情况（统计值）	main 是否已准备好发布？	SELECT last("pass_rate") FROM "test_run_summary" WHERE "branch"='main'，低于 95 为红色／95–99 为黄色／≥99 为绿色——搭配覆盖率统计值 ≥80
最不稳定的 10 个测试（表格）	哪些测试最浪费时间？	SELECT "test_name", count("retries") AS retry_count FROM "test_execution" WHERE "retries">0 AND time>now()-14d GROUP BY "test_name" ORDER BY retry_count DESC LIMIT 10
CI 耗时趋势	流水线是否越来越慢？	显示随时间变化的 avg_duration_ms，并在 600s 处添加目标线

完整查询以及覆盖率趋势和耗时分布面板见 references/grafana.md。

告警

将告警规则以 YAML 形式配置在 provisioning/alerting/ 下（Grafana 11+）。Done When 要求的规则是：main 的通过率在单日内下降超过 2 个百分点。 通过两个查询构建该规则（分别计算过去 1d 和前一天的 pass_rate 平均值），并输入数学表达式 $yesterday - $today > 2，然后通过 Slack 联系点（incoming-webhook URL）进行路由。完整的预配置规则和联系点见 references/grafana.md。还应针对以下情况设置告警：通过率低于 95% （10m 窗口）、CI 耗时超过 15 min、覆盖率一周内下降超过 2%。仪表板用于调查；告警用于检测——无人查看的仪表板什么也发现不了。

---

ReportPortal

可自托管的测试报告平台，具备机器学习驱动的失败分析、跨框架聚合和实时仪表板。

# Pin to a tagged release (current 26.0.x line: 26.0.3). The `master` branch may not
# match the supported 26.x line.
curl -LO https://raw.githubusercontent.com/reportportal/reportportal/26.0.3/docker-compose.yml
docker compose up -d
# Access at http://localhost:8080 (default: superadmin/erebus)
# ML auto-analysis lives in the `service-auto-analyzer` container — confirm it is running.

从 26.0.3 起，ReportPortal 也能接收 Agentic 测试结果（启动记录带有 AGENTIC 或 AUTOMATION 执行类型徽标）——如果测试套件中的部分测试通过 Claude Code 或其他 Agent 运行，这项功能就很有用。

Playwright 集成

// playwright.config.ts
reporter: [
  ["list"],
  ["@reportportal/agent-js-playwright", {
    apiKey: process.env.RP_API_KEY,
    endpoint: process.env.RP_ENDPOINT ?? "http://localhost:8080/api/v1",
    project: "my-project",
    launch: `E2E Tests - ${process.env.CI ? "CI" : "local"}`,
    attributes: [
      { key: "branch", value: process.env.GITHUB_HEAD_REF ?? "local" },
      { key: "build", value: process.env.GITHUB_RUN_ID ?? "dev" },
    ],
  }],
],

使用 npm i -D @reportportal/agent-js-playwright 安装。

功能	作用
自动分析	通过机器学习分类失败原因：产品缺陷、测试缺陷、系统问题或待调查
缺陷类型映射	为项目自定义缺陷类别及子类型
不稳定测试检测	检测在多次启动记录中交替通过／失败的测试
合并启动记录	将分片的 CI 运行合并为统一视图
质量门禁	为每次启动记录设置通过／失败条件（最大失败数、最低通过率）
对比	并排比较两次启动记录，以发现回归

运行后可通过查询获取质量门禁（GET /api/v1/$PROJECT/launch/$LAUNCH_ID/quality-gate）——将其状态用作 CI 门禁；若状态不是 PASSED，则让流水线失败。

Allure TestOps（托管式替代方案）

如果觉得自托管过于繁重，Allure TestOps（2026 年的 26.2.x 系列）提供 SaaS 方案：Allure 3 质量门禁、命名环境、全局附件，以及 Allure 3 风格的不稳定测试检测（当某个测试在最近 10 次运行中状态转换 ≥3 次时发出标记）。其 MCP 服务处于公开测试版（26.1.1），可让 AI Agent 直接查询启动记录和质量门禁——如果 QA 工作流通过 Claude Code / Cursor 运行，这项功能就很有用。

---

SaaS 原生测试仪表板

如果你的测试运行器提供一流的托管仪表板，应优先使用它处理该运行器的原生数据，而不是 Allure/Grafana——接线工作更少、数据保留更完善，还内置 PR 评论。只有在需要汇总多个运行器的数据时，才与 Allure/Grafana 结合使用。

平台	测试运行器	原生数据 + PR 评论
Cypress Cloud	Cypress	测试回放、并行化、易 flake 检测；AI 附加功能（Auto Heal、Bug Triage）
Currents.dev	Cypress、Playwright	对开源友好的 Cypress Cloud 替代方案；价格更低
Playwright HTML + --reporter=blob	Playwright	免费，可自托管；使用 merge-reports 合并分片
Datadog Test Optimization	任意（CI 侧）	Flaky Test Management（现已支持 Bits AI 自动修复）、TIA、原生 APM
Allure TestOps	任意	Allure 3 质量门禁、命名环境、MCP 服务 Beta 版

合并分片的 Playwright 运行（免费、原生）。 让每个分片生成 blob 报告，再将它们合并为一个 HTML 报告——这是“合并分片 CI 运行”的免费方案：

# each shard: npx playwright test --reporter=blob   (uploads blob-report/ as an artifact)
npx playwright merge-reports --reporter html ./blob-reports

如果需要跨多个运行器使用一个仪表板，或者 SaaS 方案的定价／数据驻留政策不符合需求，请使用 Allure 或 Grafana。否则，SaaS 原生仪表板通常是获取 PR 级信号最经济的方式。

---

利益相关方报告

每周 QA 摘要——通过定时 CI 作业自动生成。包含：通过率及趋势、新增与已修复的失败、最常出现波动的前 5 个测试、覆盖率变化、平均 CI 时长。健康状况分类：STABLE（>= 98%）、NEEDS ATTENTION（>= 95%）、CRITICAL（< 95%）。自动发布到 Slack。

发布质量报告——在每次发布前生成。门禁条件：E2E 通过率 >= 99%、单元测试通过率 100%、分支覆盖率 >= 80%、没有严重 Bug、重大 Bug <= 2，以及符合 Core Web Vitals 预算。输出 READY / NOT READY 结论，并逐项列出门禁的通过／失败情况。

Core Web Vitals 的性能门禁“良好”阈值（截至 2026 年当前标准）：LCP < 2500ms、INP < 200ms、CLS < 0.1。 门禁应依据 INP，而不是 FID——INP 于 2024-03-12 取代 FID 成为 Core Web Vital，FID 已于 2024-09-09 完全弃用。

---

推荐的仪表板面板

一套实用的面板，涵盖团队最常提出的问题。

面板	解答的问题	数据来源	受众
通过／失败趋势	质量是在改善还是恶化？	一段时间内的 CI 测试结果	所有人
波动最频繁的前 10 个测试	哪些测试浪费的时间最多？	过去 14 天内发生重试的测试	开发人员、QA
覆盖率热力图	哪些地方存在盲区？	按模块／目录统计的覆盖率	开发人员
缺陷逃逸趋势	Bug 是否流入了生产环境？	标记为测试逃逸的事故	QA 负责人、管理层
CI 时长	流水线是否越来越慢？	一段时间内的流水线时长	DevOps、开发人员
测试增速	测试数量是否与功能增长相称？	每个 Sprint 新增的测试	QA 负责人
失败类别	是产品 Bug 还是测试基础设施问题？	分类后的失败原因	QA 负责人
发布就绪情况	我们可以发布了吗？	根据所有门禁计算的综合分数	管理层

---

反模式

包含 30 个面板的仪表板。 没人会看。先从 5–6 个能回答最紧迫问题的面板开始；只有当有人提出仪表板无法回答的问题时，才添加面板。

没有上下文的指标。 “通过率：97%”毫无意义，除非同时提供“目标：99%”和“上周：98.5%”。每项指标都需要目标和趋势，才能发挥作用。

手动生成报告。 如果每周摘要需要有人通过 SSH 登录、运行查询并粘贴到幻灯片中，到第 3 周就没人做了。将其自动化并集成到 CI 中。

开发者和管理层使用同一个仪表板。 开发者需要失败详情、堆栈跟踪和复现步骤；管理层只需要一个红黄绿指示灯。应构建不同的视图。

把报告测试数量当作进展。 “我们新增了 200 个测试”并不能说明质量。应报告关键路径覆盖率、缺陷逃逸率，以及检测回归的平均时间。

回归时不发出警报。 没人查看的仪表板毫无用处。通过率下降、覆盖率降低和 CI 时长增加时都应发出警报。仪表板用于调查；警报用于检测。

Allure 没有历史记录。 单个 Allure 报告只是一个快照——没有趋势、无法检测间歇性失败，也无法衡量改进。务必在 CI 运行之间保留 history/（或使用 Allure 3 / Allure Service 在服务端保存历史记录）。

混用 Allure 2 和 3 的代码路径。 只在说明文字中遵循 v3 提示，却照搬 brew install allure + allure generate + 直接放入的 categories.json，最终会使用 v2 和 v2 类别。选定一条路径，并从头到尾使用它的命令。

---

验证

在宣告完成之前，先确认报告／仪表板确实能正常呈现。先从最简单的检查开始：

# Allure: a report builds and the trend widget shows >1 run (history preserved)
npx allure generate allure-results --clean -o allure-report && npx allure open allure-report
#   -> Overview page loads; the "Trend" widget shows more than one run.

# Grafana push: the summary point landed in InfluxDB
influx query 'from(bucket:"test-results") |> range(start:-1d) |> filter(fn:(r)=> r._measurement=="test_run_summary")'
#   -> returns at least one row with a pass_rate field for branch=main.

# Grafana alert: the provisioned rule loaded
curl -s http://localhost:3000/api/v1/provisioning/alert-rules -u admin:admin | jq '.[].title'
#   -> includes "Main pass rate dropped >2pp in a day".

---

完成标准

• 仪表板已发布到团队可访问的已知位置，并能返回 HTTP 200（CI 工件 URL、Grafana URL 或托管 SaaS 链接）——无需本地设置或手动运行报告。
• 至少 2 周的历史数据中，可以查看测试执行趋势（通过率、失败数量、时长）。
• 已配置 Flakiness 面板，显示滚动 14 天窗口内最不稳定的测试及其重试次数。
• 利益相关方报告模板已自动生成——可以是包含 STABLE/NEEDS ATTENTION/CRITICAL 健康标签的每周摘要，也可以是包含 READY/NOT READY 结论及逐项门禁细分的每个版本质量报告（两者任选其一或同时提供）。
• 已配置并完成路由的警报（Slack 或同类工具），当主分支通过率在单日内下降超过 2 个百分点时会触发。

相关技能

• qa-metrics — 定义质量 KPI、衡量框架和指标解读。去这里决定衡量什么；来这里将其可视化。
• ci-cd-integration — 自动生成报告和管理工件的流水线配置。
• ai-bug-triage — 由 AI 驱动的失败分类，可为仪表板中的失败类别提供数据。

参考文件（位于 references/ 中）

• allure.md — 完整的 Playwright/Vitest 适配器配置、逐测试元数据、v2 categories.json、v3 allurerc.mjs + allure run 可运行路径，以及 CI 历史记录保留工作流。
• grafana.md — push-test-metrics.ts 脚本（含刷新保护）、所有面板查询，以及已配置的“>2pp 通过率下降”警报规则 + Slack 联系点。