@chenguangyao/devflow-kit 0.1.43

package/skills/verify/references/report-templates.md

@@ -0,0 +1,510 @@
+# verify / report-templates
+
+每种报告的模板、frontmatter 字段语义、测试框架与 coverage 解析规则。
+
+---
+
+## frontmatter 字段
+
+### 必填
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `slug` | string | change 的 slug(如 `coupon-batch-grant`) |
+| `kind` | enum | `unit` / `integration` / `e2e` / `joint` / `remote` / `smoke` / `self-test` / `regression` / `perf` |
+| `status` | enum | `pass` / `fail` / `partial` / `blocked` |
+| `failureType` | enum | `code_error` / `env_error` / `-` |
+| `ts` | ISO datetime | 报告生成时间(不是测试运行时间的开始时间,是记录时间) |
+
+`status` 语义:
+
+- `pass`:全部通过(允许少量已审计跳过)
+- `fail`:至少 1 个 fail,无法发布
+- `partial`:部分通过,需用户 / orchestrator 判断是否接受(如跨 day 跑时部分环境不可达)
+- `blocked`:测试未能有效执行,通常是环境、URL、浏览器工具或账号权限问题
+
+`failureType` 用来指导回流:
+
+- `code_error`:测试已运行但断言失败或命令退出非 0,下一步回 apply 修代码并重跑
+- `env_error`:测试环境、API 地址、浏览器自动化工具、账号或网络不可用,下一步先修环境再重跑
+- `-`:未失败或暂不分类
+
+### 推荐
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `total` | int | 测试总数 |
+| `passed` | int | 通过数 |
+| `failed` | int | 失败数 |
+| `skipped` | int | 跳过数(含 quarantined) |
+| `duration_ms` | int | 测试执行耗时 |
+| `command` | string | 真正执行的命令(便于重跑) |
+| `coverage.lines` | float | 行覆盖率(百分比) |
+| `coverage.branches` | float | 分支覆盖率 |
+| `coverage.functions` | float | 函数覆盖率 |
+| `coveragePath` | string | coverage 源文件路径 |
+| `runner` | string | 识别的测试框架(jest / pytest / junit / go ...) |
+
+### 可选字段(按 kind)
+
+**perf-test**:
+
+```yaml
+perf:
+  p50_ms: 80
+  p95_ms: 150
+  p99_ms: 180
+  throughput_qps: 5400
+  concurrent_users: 100
+  baseline_p99_ms: 200   # 来自 design.md 的 NFR
+```
+
+**e2e-test**:
+
+```yaml
+browser: chromium
+viewport: "1920x1080"
+screenshots: reports/screenshots/e2e/
+videoPath: reports/videos/e2e-session.mp4
+```
+
+**joint-test**:
+
+```yaml
+backendUrl: http://localhost:8080
+frontendUrl: http://localhost:3000
+browserTool: agent-browser | chrome-devtools-mcp | playwright | -
+preflightStatus: pass | blocked | -
+database: staging-mysql
+```
+
+**remote-test**:
+
+```yaml
+apiBaseUrl: https://test-api.example.com
+preflightStatus: pass | blocked | -
+```
+
+**self-test**:
+
+```yaml
+acCovered: 12    # tests.md 里总共多少条 AC
+acPassed: 12
+evidence: reports/evidence/
+```
+
+---
+
+## unit / integration section 模板
+
+```markdown
+---
+slug: coupon-batch-grant
+kind: unit
+status: pass
+ts: 2026-04-24T14:32:11Z
+command: "mvn -pl coupon-service test"
+runner: junit
+total: 243
+passed: 243
+failed: 0
+skipped: 0
+duration_ms: 142300
+coverage:
+  lines: 86.4
+  branches: 78.1
+coveragePath: coupon-service/target/site/jacoco/jacoco.xml
+---
+
+# 单元测试报告 — coupon-batch-grant
+
+## 概要
+
+全部通过,line 覆盖 86.4%,branch 78.1%,达标(目标 ≥ 80% / ≥ 70%)。
+
+## 失败详情
+
+无。
+
+## 跳过项
+
+无。
+
+## 覆盖率低点
+
+以下类 branch 覆盖率 < 70%,下一个迭代补:
+
+- `CouponGrantService.validateBatch`(65%)— 异常分支未测
+
+## 命令与重跑
+
+```bash
+mvn -pl coupon-service test
+```
+
+## 附件
+
+- 完整 report: `target/site/surefire-report.html`
+- Coverage: `target/site/jacoco/index.html`
+```
+
+---
+
+## e2e section 模板
+
+```markdown
+---
+slug: coupon-batch-grant
+kind: e2e
+status: pass
+ts: 2026-04-24T15:10:00Z
+total: 18
+passed: 18
+failed: 0
+duration_ms: 325000
+browser: chromium
+screenshots: reports/screenshots/e2e/
+---
+
+# 端到端测试报告 — coupon-batch-grant
+
+## 测试场景覆盖
+
+- 登录 → 进入后台 → 批量发放 1000 张 → 校验 DB 落库 → 验证用户收到
+- 失败场景:上传错误 CSV / 权限不足 / 超过单次上限
+
+## 场景明细
+
+| 场景 | 状态 | 截图 |
+| --- | --- | --- |
+| 成功路径(admin, 1000 用户) | pass | ![sc1](screenshots/e2e/sc1.png) |
+| 上传错误格式 CSV | pass | ![sc2](screenshots/e2e/sc2.png) |
+| 无权限用户(operator) | pass | 权限错误页 |
+| 超过单次上限(10001 条) | pass | 400 + 明确 error message |
+
+## 视频回放
+
+- `reports/videos/e2e-sc1.mp4`
+
+## 命令
+
+```bash
+npx playwright test --project=chromium --reporter=html
+```
+```
+
+---
+
+## joint section 模板
+
+`joint` 是前后端联调报告,吸收 arb-workflow-kit 的 test-executor 思路:先做浏览器工具和 URL 预检,再把测试用例转成打开页面、点击、填写、截图、断言的步骤。它不是 L1/L2 的硬性产物,但一旦本 change 涉及前端页面、跳转、轮询、缓存 key、回调参数或跨项目消费者适配,就应该生成。
+
+```markdown
+---
+slug: coupon-batch-grant
+kind: joint
+status: pass
+failureType: -
+ts: 2026-04-24T15:20:00Z
+total: 6
+passed: 6
+failed: 0
+backendUrl: http://localhost:8080
+frontendUrl: http://localhost:3000
+browserTool: agent-browser
+preflightStatus: pass
+---
+
+# 联调测试报告 — coupon-batch-grant
+
+## 环境信息
+
+| 项 | 值 |
+| --- | --- |
+| 后端地址 | http://localhost:8080 |
+| 前端地址 | http://localhost:3000 |
+| 浏览器工具 | agent-browser |
+| 预检结果 | pass |
+
+## 用例执行详情
+
+| 用例 | 步骤 | 期望 | 实际 | 状态 |
+| --- | --- | --- | --- | --- |
+| 支付签约成功 | 打开收银台 → 选择渠道 → 确认签约 | 返回支付成功页 | 成功页展示正确 | pass |
+
+## 截图与证据
+
+- `reports/screenshots/joint/pay-success.png`
+
+## 失败详情
+
+无。
+```
+
+预检失败时也要写报告,但 `status: blocked`、`failureType: env_error`,并把缺失的 browser tool、backend-url、frontend-url 写进"预检详情"。
+
+---
+
+## remote section 模板
+
+`remote` 是已部署测试环境 API 验收,适合纯后端或服务端变更已经部署到测试环境、需要绕过本地 Mock 直接验证真实接口的场景。它同样来自 arb-workflow-kit 的 remote API 测试实践。
+
+```markdown
+---
+slug: coupon-batch-grant
+kind: remote
+status: pass
+failureType: -
+ts: 2026-04-24T15:25:00Z
+total: 8
+passed: 8
+failed: 0
+apiBaseUrl: https://test-api.example.com
+preflightStatus: pass
+---
+
+# 远程 API 测试报告 — coupon-batch-grant
+
+## 环境信息
+
+| 项 | 值 |
+| --- | --- |
+| API Base URL | https://test-api.example.com |
+| 预检结果 | pass |
+
+## 用例执行详情
+
+| 用例 | 请求 | 期望 | 实际 | 状态 |
+| --- | --- | --- | --- | --- |
+| 创建批次 | POST /api/v1/coupons/batch-grant | HTTP 200,grantedCount=100 | HTTP 200,grantedCount=100 | pass |
+
+## 失败详情
+
+无。
+```
+
+预检失败时写 `status: blocked`、`failureType: env_error`;命令执行失败时写 `status: fail`、`failureType: code_error`。
+
+---
+
+## smoke section 模板
+
+手工写。重点是"新发布的 change 真正被用起来的关键路径"。
+
+```markdown
+---
+slug: coupon-batch-grant
+kind: smoke
+status: pass
+ts: 2026-04-24T15:30:00Z
+executor: @eng-a
+environment: staging
+---
+
+# 冒烟测试报告 — coupon-batch-grant
+
+## 场景
+
+新 API `/api/v1/coupons/batch-grant` 上线后,运营最常用的路径:
+
+1. 登录管理后台
+2. 选择活动 "双十一优惠券"
+3. 上传 100 用户的 CSV
+4. 点击"批量发放"
+5. 看到 toast "已发放 100 张"
+6. 抽样检查 3 个用户,DB 里有记录
+
+## 执行
+
+### Step 1-5
+
+![成功路径](screenshots/smoke/1-5.png)
+
+### Step 6(抽样)
+
+```sql
+select * from coupon_log where user_id in ('u_100', 'u_500', 'u_999');
+```
+
+三条都在,时间戳 2026-04-24 15:28,status=granted。
+
+## 结论
+
+**pass**。staging 上核心路径通。
+```
+
+---
+
+## self-test section 模板
+
+```markdown
+---
+slug: coupon-batch-grant
+kind: self-test
+status: pass
+ts: 2026-04-24T15:45:00Z
+acCovered: 12
+acPassed: 12
+evidence: reports/evidence/
+---
+
+# 提测自测报告 — coupon-batch-grant
+
+覆盖 tests.md 里所有 F-ID 和 AC,逐项核验。
+
+## F-01: 批量发放优惠券
+
+### AC1: 提交 1000 条用户 → 返回 grantedCount=1000
+
+- **执行方式**: postman 批量提交 `/api/v1/coupons/batch-grant`
+- **输入**: `reports/evidence/F-01-AC1-input.json`(1000 用户)
+- **期望**: response.grantedCount=1000
+- **实际**: 1000 ✅
+- **DB 校验**: `select count(*) from coupon_log where activity_id = 'act_1' and batch_id = 'b_xxx'` → 1000
+- **证据**: `reports/evidence/F-01-AC1-response.json`, `reports/evidence/F-01-AC1-db.png`
+
+### AC2: 含 10 条风控失败用户 → 返回 grantedCount=990, failedCount=10
+
+- **执行方式**: postman 批量提交,其中 10 个 user_id 命中风控规则
+- **期望**: grantedCount=990, failedCount=10,failedReasons 明确
+- **实际**: grantedCount=990, failedCount=10, 10 条 reason 都是 `RISK_BLOCKED:user_in_blacklist` ✅
+- **证据**: `reports/evidence/F-01-AC2-response.json`
+
+### AC3: 单批次超过 10000 → 返回 400 BAD_REQUEST
+
+- **执行方式**: postman,10001 条
+- **期望**: HTTP 400,error.code=BATCH_TOO_LARGE
+- **实际**: 400, code=BATCH_TOO_LARGE, message=最大支持 10000 条 ✅
+- **证据**: `reports/evidence/F-01-AC3-response.json`
+
+## F-02: 发放结果查询
+
+...
+
+## 结论
+
+所有 12 条 AC 均满足,12/12 pass。
+```
+
+---
+
+## perf-test.md 模板
+
+```markdown
+---
+slug: coupon-batch-grant
+kind: perf
+status: pass
+ts: 2026-04-24T16:30:00Z
+command: "k6 run perf/batch-grant.js"
+runner: k6
+duration_ms: 600000
+perf:
+  p50_ms: 78
+  p95_ms: 150
+  p99_ms: 180
+  throughput_qps: 5400
+  concurrent_users: 100
+  baseline_p99_ms: 200
+  error_rate: 0.0003
+---
+
+# 性能测试报告 — coupon-batch-grant
+
+## 测试场景
+
+- 工具:k6
+- 场景:模拟 100 并发用户,每用户 300s 持续调用 `/api/v1/coupons/batch-grant`(每次 100 条)
+- 环境:staging + 独立压测数据库
+- 数据:10 万用户池 + 5 活动池
+
+## 结果
+
+| 指标 | 实际 | NFR 基线 | 状态 |
+| --- | --- | --- | --- |
+| P50 | 78 ms | — | — |
+| P95 | 150 ms | 180 ms | ✅ |
+| P99 | 180 ms | 200 ms | ✅ |
+| 吞吐 | 5,400 qps | 5,000 qps | ✅ |
+| 错误率 | 0.03% | < 0.1% | ✅ |
+
+## 图表
+
+- QPS 曲线: `reports/perf/qps.png`
+- 延迟分布: `reports/perf/latency-dist.png`
+- 资源监控: CPU 峰值 65%,内存稳定 1.2GB
+
+## 结论
+
+所有 NFR 满足,pass。
+```
+
+---
+
+## 9 种测试框架识别规则
+
+`devflow test <kind> --cmd <...>` 会尝试解析 stdout,识别下列框架输出并填充 frontmatter:
+
+| 框架 | 识别信号 | 解析字段 |
+| --- | --- | --- |
+| Jest | `Tests:       243 passed, 243 total` | total / passed / failed / skipped |
+| Vitest | `Test Files   15 passed (15)` + `Tests  243 passed (243)` | 同上 |
+| Mocha | `  243 passing (142s)` | 同上 |
+| Tap | `# tests 243` `# pass 243` | 同上 |
+| node:test | `ok 243 ...` + `# tests 243` | 同上 |
+| Go | `--- PASS: TestXXX (0.00s)` + `PASS\nok\tpkg` | 逐测试累加 |
+| Pytest | `============== 243 passed in 142.30s ==============` | 同上 |
+| unittest | `Ran 243 tests in 142.300s\n\nOK` | 同上 |
+| JUnit | XML 报告(surefire-reports / build/test-results) | 读 XML `<testsuite>` |
+
+识别失败时填 `runner: unknown`,字段留 null,要求用户手动补(或用 `devflow test <kind> --parse <format>` 指定)。
+
+---
+
+## 5 种 coverage 格式识别
+
+| 格式 | 文件名 |
+| --- | --- |
+| JSON summary | `coverage/coverage-summary.json` |
+| LCOV | `coverage/lcov.info` |
+| Cobertura XML | `coverage/cobertura.xml` |
+| Go profile | `coverage.out`(`go tool cover -func`) |
+| JaCoCo XML | `target/site/jacoco/jacoco.xml` |
+
+自动扫描常见路径,或用 `--coverage-path <path>` 显式指定。解析后填:
+
+```yaml
+coverage:
+  lines: 86.4
+  branches: 78.1
+  functions: 90.2
+coveragePath: <path>
+```
+
+---
+
+## 自定义扩展
+
+- **加一种 frontmatter 字段**:直接写,finalize 不会因为额外字段报错
+- **接入新测试框架**:PR 加到 `src/core/report/parsers/<framework>.js`(实现 `parse(stdout) => { total, passed, failed, skipped, duration_ms }`)
+- **接入新 coverage 格式**:类似,加到 `src/core/report/coverage/<format>.js`
+
+---
+
+## 报告命名约定
+
+- 默认唯一:`test-report.md` 里的 `#<kind>` section(不要再生成一堆 `unit-test-v2.md`)
+- 兼容旧工具:显式加 `--split-report` 时才额外生成 `<kind>-test.md`
+- 一次性多份(如 perf 多场景):加 `perf-test-<scenario>.md`,finalize 按 glob 读
+- 截图:`reports/screenshots/<kind>/...`
+- 附件:`reports/evidence/<kind>/...`
+- 日志:`reports/logs/<kind>.log`
+
+---
+
+## 常见坑
+
+- **skipped 不报告**:frontmatter 必须如实写 skipped 数;review / finalize 会比对 tests.md 总数
+- **partial 当 pass 写**:禁止;partial 要附"剩余 N 个不通过的处置 checklist"
+- **reports/ 外部链接路径错误**:用**相对于 `devflow/changes/<slug>/` 的相对路径**,不要用绝对路径或 http(部分环境不联网)
+- **coverage 只报 line 不报 branch**:L2/L3 推荐两者都报,不然回归时不知道哪些逻辑分支没测