构建可驱动决策的 QA 仪表盘与报告（Allure/Graf…

当需要把测试结果可视化为可行动面板、趋势、发布门禁和自动利益相关者报告，并让每个红色指标都能下钻到具体失败时，用 Allure/Grafana/ReportPortal/SaaS 原生仪表盘搭建并验证 QA 仪表盘。

适用场景

解决思路

1. 当团队已用 Grafana 看基础设施指标时，在 Grafana 中加入测试指标并与生产指标并排展示。
2. 当测试 runner 自带托管仪表盘（Cypress/Playwright 等）时，走 SaaS-Native 仪表盘，接线最少。
3. 当需要丰富 HTML 报告且没有基础设施可跑时，用 Allure Report：在 CI 生成并发布 artifact。
4. 当需要自托管跨框架聚合和 AI 分诊时，用 ReportPortal。
5. 当需要跨多个 runner 的单一视图时，用 Grafana 或 Allure 做跨 runner 聚合。
6. 当需要给利益相关者每周摘要或发布结论时，用 Stakeholder Reports。
7. 发现阶段：先检查 `.agents/qa-project-context.md`；如果存在，直接使用其中答案并跳过已被回答的发现项。
8. 发现阶段：询问当前测试报告工具是什么（控制台输出、JUnit XML、HTML 报告或专用平台），确定起点和剩余接线量。
9. 发现阶段：询问谁会看仪表盘（开发者需要失败详情和 trace；QA lead 需要趋势和 flakiness；领导层需要发布信心和缺陷率），为不同受众建不同视图。
10. 发现阶段：询问仪表盘应驱动什么决策（例如“这个 build 可否发布？”“哪些测试需要修？”“质量是否逐 sprint 改善？”），没有决策场景的仪表盘会变成闲置品。
11. 发现阶段：询问测试结果存放位置（GitHub Actions artifacts、S3、数据库？），据存储位置选择可行的仪表盘工具。
12. 发现阶段：询问 CI 平台（GitHub Actions、GitLab CI、Jenkins？），不同平台有不同 artifact 和报告集成。
13. 核心原则：每个面板必须映射到一个真实被问的问题，而不是展示数字；例如“flakiness rate 是多少”是问题，“total test count”是琐事。
14. 核心原则：为不同受众建不同视图；开发者调试 CI 失败需要 stack trace、截图和 trace，VP 只需要一个数字“我们准备好发布了吗”，不要把两者塞进同一个仪表盘。
15. 核心原则：CI 用实时仪表盘，领导层用趋势；CI 仪表盘每次流水线运行更新，领导层仪表盘按周或按 sprint 聚合，不要混用节奏。
16. 核心原则：每个红色指标必须能下钻到具体失败测试、具体 flaky 测试或具体覆盖率缺口；只显示“5 failures”但不链接失败的是通知，不是工具。
17. 核心原则：自动化报告生成；需要手动跑脚本、复制数据、做幻灯片的报告活不过第一个繁忙 sprint，必须从 CI 流水线自动生成。
18. Allure：用 Allure 从测试结果生成带历史、分类和重试的丰富 HTML 报告；可用于 Playwright、Jest、Vitest、pytest 和多数框架。
19. Allure 2 vs 3：框架适配器（`allure-playwright`、`allure-vitest`、`allure-jest`）输出相同的 Allure 2 result 文件，只有读取器不同。
20. Allure 2 路径：使用 `allure-commandline`（2.42.1，Jun 2026）；`brew install allure` 安装的是这个，不是 v3；命令用 `allure generate` / `allure open` / `allure serve`；categories 通过放入 `allure-results/` 的 `categories.json` 配置；稳定、冻结、仅依赖更新。
21. Allure 3 路径：使用 `allure` npm 包 + `allurerc.mjs`（3.9.0，May 2026）；TypeScript 重写，支持 plugins、单文件配置、实时 `allure watch`、项目级质量门、多环境报告和 Allure Service 服务端历史；命令用 `npx allure run` / `npx allure generate` / `npx allure watch`；categories 移到 `allurerc.mjs` 中（放入 `categories.json` 是 v2 概念）。
22. Allure：新项目选择 Allure 3；如果只按 `brew install allure` / `allure generate` 操作，则在 v2 路径上，这没问题且完全支持，但要知道自己运行的是哪条路径。
23. Allure：最小 Playwright reporter 接线是在 `playwright.config.ts` 中注册 adapter 为 `reporter: ["allure-playwright", { outputFolder, environmentInfo }]`，让每次运行将结果放入 `allure-results/` 并捕获环境信息。
24. Allure：添加每个测试的元数据（`allure.severity` / `feature` / `story` / `tag`）以驱动分组；定义失败 `categories` 以区分产品 bug 和基础设施故障；跨 CI 运行保留 `history/` 以让趋势存在。
25. Allure：没有 history 时，Allure 报告只是单次快照——没有趋势、没有间歇性失败检测。
26. Allure：参考 `references/allure.md` 获取完整 Playwright/Vitest 配置、v2 `categories.json`、v3 `allurerc.mjs` + `allure run` 可运行路径，以及 GitHub Actions history-preservation 步骤。
27. Grafana：当团队已用 Grafana 做基础设施指标，并想把测试指标放在生产指标旁边时，用 Grafana 做实时仪表盘和告警。
28. Grafana 数据流水线：在测试后 CI step 中解析结果（JUnit XML、coverage JSON、timing），把点推送到时序 DB（InfluxDB 或 Prometheus pushgateway），Grafana 查询这些数据。
29. Grafana push 脚本写入两个 measurement：`test_execution`（每个测试一个点，tag 为 `suite`/`test_name`/`status`/`branch`/`run_id`）和 `test_run_summary`（每次运行一个点，含 `pass_rate`、`total`、`failed`、`avg_duration_ms`）。
30. Grafana：每个点都打 `branch` 和 `run_id` 标签，以便面板可过滤到 `main` 并链接回具体运行。
31. Grafana：push 脚本在 `if: always()` 下运行；把写循环包在 try/flush/close 中，否则循环中途抛错会丢失所有缓冲点。
32. Grafana：参考 `references/grafana.md` 获取完整 `push-test-metrics.ts`（带 flush guard）和 GitHub Actions step。
33. Grafana 推荐面板 Pass Rate Trend：时序，问题“质量在改善吗？”，查询 `SELECT mean("pass_rate") FROM "test_run_summary" WHERE "branch"='main' GROUP BY time(1d)`，阈值 95% 黄色 / 99% 绿色。
34. Grafana 推荐面板 Release Readiness：stat，问题“main 准备好发布了吗？”，查询 `SELECT last("pass_rate") FROM "test_run_summary" WHERE "branch"='main'`，红色 <95 / 黄色 95–99 / 绿色 ≥99，并搭配覆盖率 stat ≥80。
35. Grafana 推荐面板 Flakiness Top 10：table，问题“哪些测试浪费时间最多？”，查询 `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`。
36. Grafana 推荐面板 CI Duration Trend：问题“流水线变慢了吗？”，对时间画 `avg_duration_ms`，目标线在 600s。
37. Grafana：完整查询及 Coverage Trend 和 Duration Distribution 面板在 `references/grafana.md`。
38. Grafana 告警：在 `provisioning/alerting/` 下用 YAML 配置告警规则（Grafana 11+）。
39. Grafana 必需告警：main pass rate 单日下降超过 2 个百分点；用两个查询（最近 `1d` 的 mean `pass_rate` vs 前一天）输入数学表达式 `$yesterday - $today > 2`，通过 Slack contact point（incoming-webhook URL）路由；完整 provisioned rule + contact point 在 `references/grafana.md`。
40. Grafana 也要告警：pass rate 低于 95%（10m 窗口）、CI duration 高于 15 min、coverage 一周下降 >2%。
41. Grafana：仪表盘用于调查；告警用于检测——没人打开的仪表盘什么都抓不到。
42. ReportPortal：用 ReportPortal 自托管测试报告平台，带 ML 失败分析、跨框架聚合和实时仪表盘。
43. ReportPortal 启动：固定到 tagged release（当前 26.0.x 线：26.0.3）；运行 `curl -LO https://raw.githubusercontent.com/reportportal/reportportal/26.0.3/docker-compose.yml`；运行 `docker compose up -d`；访问 `http://localhost:8080`（默认：superadmin/erebus）；确认 `service-auto-analyzer` 容器运行（ML auto-analysis 在其中）。
44. ReportPortal：26.0.3 也能摄取 agentic 测试结果（launch 带 `AGENTIC` vs `AUTOMATION` execution-type badge），若部分套件通过 Claude Code 或其他 agent 运行则相关。
45. ReportPortal Playwright 集成：在 `playwright.config.ts` 中配置 `@reportportal/agent-js-playwright`，包含 `apiKey`、`endpoint`、`project`、`launch`、`attributes`（`branch`、`build`）。
46. ReportPortal：安装 `npm i -D @reportportal/agent-js-playwright`。
47. ReportPortal 功能：Auto-analysis（ML 失败分类：product bug、test bug、system issue 或 to-investigate）。
48. ReportPortal 功能：Defect type mapping（为项目配置自定义缺陷类别和子类型）。
49. ReportPortal 功能：Flaky test detection（跨 launch 翻转 pass/fail 的测试）。
50. ReportPortal 功能：Merge launches（把分片 CI 运行合并成一个统一视图）。
51. ReportPortal 功能：Quality gates（每次 launch 的通过/失败标准，如最大失败数、最低通过率）。
52. ReportPortal 功能：Comparison（并排比较两个 launch 以发现回归）。
53. ReportPortal：质量门可在运行后查询 `GET /api/v1/$PROJECT/launch/$LAUNCH_ID/quality-gate`；用其状态作为 CI gate，若不是 `PASSED` 则使流水线失败。
54. Allure TestOps 托管替代：如果自托管太重，用 Allure TestOps（26.2.x 线，2026）作为 SaaS 路径；有 Allure 3 quality gates、命名环境、全局 attachments、Allure 3 风格 flaky detection（最近 10 次运行中状态转换 ≥3 次即标记）。
55. Allure TestOps：其 MCP server 公测（26.1.1），允许 AI agent 直接查询 launch 和 quality gates；当 QA 工作流跑在 Claude Code / Cursor 中时相关。
56. SaaS-Native：如果测试 runner 有一流托管仪表盘，优先用它处理该 runner 的原生数据，而不是 Allure/Grafana；接线更少、保留更久、内置 PR comments。
57. SaaS-Native：只在需要跨 runner 聚合时才与 Allure/Grafana 交叉使用。
58. SaaS-Native 平台：Cypress Cloud（Cypress；test replay、parallelization、flake detection；AI add-on Auto Heal、Bug Triage）。
59. SaaS-Native 平台：Currents.dev（Cypress、Playwright；OSS-friendly Cypress Cloud 替代，价格更低）。
60. SaaS-Native 平台：Playwright HTML + `--reporter=blob`（免费、自托管；用 `merge-reports` 合并 shards）。
61. SaaS-Native 平台：Datadog Test Optimization（任意 CI 侧；Flaky Test Management，现带 Bits AI auto-fix，TIA，原生 APM）。
62. SaaS-Native 平台：Allure TestOps（任意；Allure 3 quality gates、命名环境、MCP server beta）。
63. 合并分片 Playwright 运行（免费、原生）：让每个 shard 产出 blob report，再合并成一个 HTML report。
64. 合并分片 Playwright 运行命令：每个 shard 运行 `npx playwright test --reporter=blob`（上传 `blob-report/` 作为 artifact）；然后运行 `npx playwright merge-reports --reporter html ./blob-reports`。
65. 当需要一个跨多个 runner 的仪表盘，或 SaaS 选项的价格/数据驻留不合适时，使用 Allure 或 Grafana；否则 SaaS-native dashboard 通常是获得 PR 级信号的最便宜路径。
66. Stakeholder Weekly QA Summary：通过 scheduled CI job 自动化；包含 pass rate + trend、new vs fixed failures、top 5 flaky tests、coverage delta、avg CI duration。
67. Weekly QA Summary：健康度分类 STABLE (>= 98%)、NEEDS ATTENTION (>= 95%)、CRITICAL (< 95%)；自动 post 到 Slack。
68. Release Quality Report：每次发布前生成；门禁：E2E pass rate >= 99%、unit pass rate 100%、branch coverage >= 80%、zero critical bugs、major bugs <= 2、Core Web Vitals budget。
69. Release Quality Report：输出 READY / NOT READY verdict，并带每项 gate 的 pass/fail breakdown。
70. Core Web Vitals “good” 阈值：`LCP < 2500ms`、`INP < 200ms`、`CLS < 0.1`；门禁用 INP，不用 FID；INP 于 2024-03-12 取代 FID 成为 Core Web Vital，FID 于 2024-09-09 完全退役。
71. 推荐面板：Pass/Fail Trend（问题：质量在改善还是退化？数据源：CI test results over time；受众：所有人）。
72. 推荐面板：Flakiness Top 10（问题：哪些测试浪费时间最多？数据源：过去 14 天有 retries 的测试；受众：开发者、QA）。
73. 推荐面板：Coverage Heatmap（问题：哪里是盲区？数据源：按 module/directory 的 coverage；受众：开发者）。
74. 推荐面板：Defect Escape Trend（问题：bug 是否到达生产？数据源：标记为 test escapes 的 incidents；受众：QA leads、领导层）。
75. 推荐面板：CI Duration（问题：流水线变慢了吗？数据源：随时间的 pipeline duration；受众：DevOps、开发者）。
76. 推荐面板：Test Velocity（问题：测试与功能成比例吗？数据源：每 sprint 新增测试；受众：QA leads）。
77. 推荐面板：Failure Categories（问题：产品 bug 还是测试基础设施？数据源：分类后的失败原因；受众：QA leads）。
78. 推荐面板：Release Readiness（问题：能发布吗？数据源：所有 gates 的 composite score；受众：领导层）。
79. 反模式：不要做 30 个面板的仪表盘；从 5–6 个回答最紧急问题的面板开始，只有当有人问仪表盘无法回答的问题时才加面板。
80. 反模式：不要无上下文指标；"Pass rate: 97%" 需要 "target: 99%" 和 "last week: 98.5%" 才有意义；每个指标都需要目标和趋势才可行动。
81. 反模式：不要手动生成报告；如果每周摘要需要 SSH、跑查询、粘贴到 slide，第 3 周就会停止；把它自动化进 CI。
82. 反模式：开发者和领导层不要用同一个仪表盘；开发者需要失败详情、stack trace、repro steps，领导层需要一个 traffic light；建分开的视图。
83. 反模式：不要把报告测试数量当作进展；"We added 200 tests" 对质量说明不了什么；改报告 critical-path coverage、defect escape rate、mean time to detect regressions。
84. 反模式：不要不对回归告警；没人看的仪表盘没用；对 pass-rate drops、coverage decreases、CI-duration increases 告警；仪表盘用于调查，告警用于检测。
85. 反模式：不要 Allure 没有 history；单次 Allure 报告是快照，没趋势、没间歇性失败检测、没改善度量；始终跨 CI 运行保留 `history/`（或使用 Allure 3 / Allure Service 服务端历史）。
86. 反模式：不要混用 Allure 2 和 3 代码路径；按照文中 v3 说明做但复制 `brew install allure` + `allure generate` + 放入 `categories.json` 会落到 v2 并带 v2 categories；选一条路径并端到端使用其命令。
87. 验证：调用完成前证明 report/dashboard 实际渲染；从小到大检查。
88. Allure 验证：运行 `npx allure generate allure-results --clean -o allure-report && npx allure open allure-report`；预期 Overview 页面加载，`Trend` widget 显示不止一次运行。
89. Grafana push 验证：运行 `influx query 'from(bucket:"test-results") |> range(start:-1d) |> filter(fn:(r)=> r._measurement=="test_run_summary")'`；预期至少返回一行 branch=main 且含 pass_rate 字段。
90. Grafana alert 验证：运行 `curl -s http://localhost:3000/api/v1/provisioning/alert-rules -u admin:admin | jq '.[].title'`；预期包含 `Main pass rate dropped >2pp in a day`。
91. Done When：仪表盘发布到团队可访问的已知位置并返回 HTTP 200（CI artifact URL、Grafana URL 或托管 SaaS 链接），无需本地设置或手动运行报告。
92. Done When：测试执行趋势（pass rate、failure count、duration）在至少 2 周历史数据上可见。
93. Done When：Flakiness 面板配置为显示 top flaky tests 及 rolling 14-day window 的 retry counts。
94. Done When：Stakeholder report 模板自动生成——要么是带 STABLE/NEEDS ATTENTION/CRITICAL 健康标签的 weekly summary，要么是带 READY/NOT READY verdict 和 per-gate breakdown 的 per-release quality report（一个或两个都可接受）。
95. Done When：配置并路由告警（Slack 或等价物），当 main-branch pass rate 单日下降超过 2 个百分点时触发。
96. Related Skills：qa-metrics 决定衡量什么 KPI 和如何解释；本技能只做可视化。
97. Related Skills：ci-cd-integration 配置流水线以自动生成报告和管理 artifact。
98. Related Skills：ai-bug-triage 提供 AI 失败分类，输入仪表盘的 failure categories。
99. Reference Files：`references/allure.md` 包含完整 Playwright/Vitest adapter configs、per-test metadata、v2 `categories.json`、v3 `allurerc.mjs` + `allure run` runnable path、CI history-preservation workflow。
100. Reference Files：`references/grafana.md` 包含 `push-test-metrics.ts`（带 flush guard）、所有 panel queries、provisioned ">2pp pass-rate drop" alert rule + Slack contact point。

适用边界 · 注意事项

• 不适用于定义要衡量哪些 KPI 或如何解释指标；这些用 qa-metrics，本技能只建面板。
• 如果测试 runner 已有原生托管仪表盘，且不需要跨 runner 聚合，优先用该原生仪表盘，而不是自建 Allure/Grafana。
• 如果无法在 CI 中自动生成报告或保留历史，不要先做趋势面板；先解决自动化与 history 保存。