GabrieleScano/test-triage-kit

# 测试 Triage Kit 用于 **Playwright** 的失败分诊工具包：它将原始的测试失败转化为去重、分类并由 AI 丰富内容的缺陷报告 —— 并且知道什么时候*不该*提交报告。 [](https://github.com/GabrieleScano/test-triage-kit/actions/workflows/ci.yml) **[查看实时分诊报告 →](https://gabrielescano.github.io/test-triage-kit/)** —— 在内置的 fixture 上运行的 pipeline：聚类的缺陷、一个不稳定测试 (flaky test)、明确的结论，以及由 AI 编写的缺陷报告（人类可读的标题、根因假设、严重程度、复现步骤）。模型的响应已被[记录](fixtures/recorded-ai.json)并由真实的解析器验证，因此 CI 可以在没有 API key 的情况下确定性地重建页面；[纯确定性输出](https://gabrielescano.github.io/test-triage-kit/deterministic/)也一并发布以供对比。 ## 为什么开发这个项目 为每一个标红的测试自动提交缺陷只会产生噪音，而不是有效的分诊。单个失败的测试无法回答真正的核心问题： - **这是一个缺陷还是十个？** 十个因为同一个选择器而失败的测试应该合并为*一*份报告。 - **这到底是不是缺陷？** 不稳定测试和环境中断不属于应用缺陷。 - **这是新缺陷吗？** 已知的失败应该更新现有的 issue，而不是开启重复项。 该 pipeline 会先确定性地回答这些问题，然后仅在规则无能为力时才使用 AI：编写开发人员真正想看的报告。 ``` ingest → classify → fingerprint/cluster → history → verdict → (AI enrich) → outputs ``` | 阶段 | 功能描述 | 是否确定性? | |---|---|---| | Ingest (接入) | Playwright JSON 报告 **或** 内置的自定义 reporter | ✅ | | Classify (分类) | 规则引擎：`assertion` / `timeout` / `network` / `crash` / `setup` | ✅ | | Fingerprint (指纹) | 规范化易变部分（持续时间、ID、端口）并对 category + selector + message 进行哈希处理 → 具有相同根因的失败会聚类在一起 | ✅ | | History (历史) | 仅追加的运行历史 → 不稳定测试检测（"10 次运行中失败 2 次，但从未连续失败两次"） | ✅ | | Verdict (结论) | `likely-bug` / `likely-flaky` / `infrastructure` —— 并附带明确的理由 | ✅ | | AI enrichment (AI 增强) | 人类可读的标题、根因假设、严重程度建议、自然语言的复现步骤；以及跨运行的综合分析（"12 次失败，一个系统性原因"） | ➕ 附加增强 | | Outputs (输出) | Markdown 报告、静态 HTML 分诊页面、GitHub Issues 生命周期、Slack 摘要 | ✅ | 规则引擎是事实来源；AI 层（带有结构化输出的 Anthropic Messages API）则是尽最大努力运行 —— 网络错误绝不会中断分诊过程，并且其输出在供任何下游环节使用之前都会经过 schema 验证。 ## 用法 ``` npm ci npm test # unit tests, no network needed npm run demo # triage the bundled fixture report into triage-output/ ``` 针对真实运行的测试： ``` npx playwright test --reporter=json > report.json # in your test project npx triage report.json --out triage-output --history .triage-history.json ``` 或者将自定义 reporter 接入 `playwright.config.ts` 并使用其规范化后的输出： ``` reporter: [ ['html'], ['test-triage-kit/reporter', { outputFile: 'triage-input.json' }], ], ``` 选项：`--no-ai`、`--github` (+ `--dry-run`)、`--slack`、`--help`。 ## GitHub Issues 生命周期 使用 `--github` 时（需要 `GITHUB_TOKEN` 和 `GITHUB_REPOSITORY`，这两者在 GitHub Actions 中默认存在）： - **新的指纹 + likely-bug 结论** → 开启一个 issue（带有 `bug`、`automated-triage` 标签），并在正文中将指纹作为标记嵌入。 - **已知的指纹** → 在现有的 issue 下评论此次新发生的情况。永远不会产生重复项。 - **指纹连续 5 次运行通过 (green)** → 评论一条关闭建议。它永远不会自行关闭 issue —— 这种判断始终由人类来决定。 - **Flaky / infrastructure (不稳定 / 基础设施) 结论** → 会被刻意跳过。将它们作为缺陷提交正是该工具旨在避免的噪音。 ## AI 层 ``` cp .env.example .env # add your ANTHROPIC_API_KEY ``` 针对每个聚类，Claude 会接收错误信息、已执行的 `test.step()` 标题、规则引擎的 category 以及历史记录，并返回严格的 JSON（标题、根因*假设*、严重程度及理由、复现步骤）。在运行级别，它会做出单一失败视角无法做出的判断：这些失败是否共享一个系统性原因（例如环境宕机、部署失败）—— 在这种情况下，摘要会直接说明这一点，而不是报告 N 个独立的缺陷。 如果没有 API key，所有确定性流程依然能够正常工作；报告将直接基于确定性数据生成。 ## 设计原则 - **诚实的结论。** 每一个结论都会陈述其理由；“可能存在不稳定性 (flakiness)”是一个首要的合理结果，而不是需要掩饰的尴尬。 - **一个根因，一份报告。** 基于指纹的去重是核心功能，而不是事后补充。 - **AI 提出建议，人类做出决定。** 严重程度是一项建议；关闭 issue 是一种提议；规则引擎始终可以离线运行。 - **运行器无关的核心。** 接入 (ingestion) 之后的所有流程都基于规范化的 `FailureRecord` 运行 —— Playwright 只是第一个适配器，而非硬性依赖。 ## 相关项目 本项目是涵盖 QA (质量保证) 工程完整周期的作品集的一部分：[requirements-analyzer](https://github.com/GabrieleScano/requirements-analyzer) (测试左移的需求审查) → [ai-augmented-e2e](https://github.com/GabrieleScano/ai-augmented-e2e) (测试设计与执行) → **test-triage-kit** (失败分诊)。

标签：MITM代理, 特征检测, 自动化攻击