Case Atlas
Case Atlas 是一个面向 AI 生成测试用例的人工评审与治理工具。
AI 编码助手让创建测试变得越来越容易,却也让测试套件迅速膨胀:用例从哪里来、测试什么、是否重复、是否仍然有价值,往往没人能快速回答。传统测试报告关注“这次运行是否通过”,测试管理工具关注“测试流程是否完成”,但它们没有解决测试用例本身的价值判断问题。
Case Atlas 关注的是测试套件的长期质量:让人看懂每条用例,做出明确决策,再把决策转化为可执行的修改方案交给 AI,最后通过运行和复核确认结果。
它解决什么问题
AI 编码过程中生成的测试用例,质量往往无法保证,典型有三类问题:
- 过期用例:需求迭代后测试没有跟着更新,仍按旧版本测试——老功能可能已废弃,或交互逻辑、功能逻辑已发生较大变化;
- 无价值用例:AI 自认为重要的点,实际反映不了任何问题,跑了一堆特别费资源又没用的测试脚本;
- 覆盖缺失:该测的核心流程没有被覆盖到。
针对这三类问题,Case Atlas 首版提供以下能力:
- 看得见:集中展示测试代码、业务意图、证据和 AI 推断(推断会明确标注;运行历史等信息需由生成 Agent 提供)。
- 审得动:提供以单条用例为核心的评审页面,支持保留、废弃或要求修改。
- 改得准:把人的意见整理为结构化 Markdown 变更任务,供 Agent 生成可审阅 patch。
- 能闭环:Agent 执行后运行批次框架对应的完整验证(pytest、Vitest、Playwright、
node --test,或 tsc/ruff/mypy 静态检查),由人复核结果,评审结论和证据持续留档。
总体架构
Case Atlas 由三部分组成闭环,核心特征是 Web 评审界面零 AI 依赖、md 文件是唯一跨系统协议、文件系统即状态机:
Claude Code(通过内置 skill)
│ 执行生成 skill,按固定 schema 产出结构化待评审数据
↓
~/.case-atlas/pending/<批次>/ ── case-atlas serve 拉起本地 Web 评审界面
│ (纯程序化输出,不调用任何模型)
│ 人工评审:逐条决策、提出新增用例需求,进度实时持久化
↓
评审结果 md(人给 AI 的任务书,同时是审计记录)
│ 配合执行 skill 交回 Agent 会话
↓
AI 受控修改(patch / 分支)→ 按批次框架运行完整验证 → 执行报告 → 人工复核
核心工作流
评审动作及其含义:
- pass:用例有价值,保留并纳入套件;
- discard:用例没有实际价值,确认后删除;不确定时可附质疑 prompt,交由 AI 判定是否删除;
- discard-question:暂不确定是否删除,要求 Agent 独立判断并说明理由;
- revise:测试意图有价值,但步骤、数据或断言需要修改,附修改意见交给 AI;
- defer:本轮暂不处理,导出时保持不变;
- add:发现覆盖缺失,以需求描述交由 AI 新增用例(独立于用例 decision)。
设计原则
- 人做价值判断,AI 做分析和执行。AI 可以解释、归类和起草方案,但不替人做最终取舍。
- 结论必须有证据。AI 推断与源码、运行历史、覆盖率等事实分开呈现,并保留来源和置信度。
- 变更默认可审阅、可回滚。删除和修改先生成 patch 或分支,不直接破坏原始代码。
- 评审结果是结构化资产。决策、理由、验收标准和验证结果可被编码助手读取和执行。
- 质量不等于覆盖率。测试价值还要结合业务风险、断言质量、稳定性、维护成本和缺陷发现能力。
目标用户
- 使用 Claude Code 生成或维护 pytest / Vitest / Playwright /
node --test测试与 tsc / ruff / mypy 静态检查的个人开发者和团队(其他 Agent 尚未在首版提供 skill); - 持有大型存量测试套件、希望系统治理测试质量的工程团队;
- 需要让 AI 持续维护测试,而又不希望失去人工把关的项目。
项目状态
当前仓库已提供首版可运行实现:文件系统持久化、CLI、仅回环监听的本地 Web 评审界面、事务化 Markdown 导出,以及 Claude Code 生成/执行 skill 模板。数据契约支持以下验证框架(批次 manifest 的 project.framework):pytest、vitest、playwright、node-test(各测试框架收集的用例)、tsc、ruff、mypy(静态检查的当前发现)、catalog(项目自维护清单/登记表定义的验证用例);生成/执行 skill 首版只覆盖 claude-code。测试代码的发现、删改增和最终验证仍由 Agent 在用户明确确认后完成。
运行时边界
- 运行数据只写入
~/.case-atlas/(可用CASE_ATLAS_HOME隔离);批次使用 UTF-8 JSON/JSONL。显式执行install-skill时,另会在用户级~/.claude/skills/写入两个 skill 模板(不在目标项目内写任何文件);导出时还会在当前工作目录生成评审 Markdown。 - Web 服务只监听
127.0.0.1,不调用模型、遥测或外部网络,也不使用数据库或前端构建链。 - CLI 不读取或修改用户项目测试代码;导出的 Markdown 是交给执行 Agent 的唯一跨系统协议。
快速开始
pip install case-atlas
case-atlas init
case-atlas install-skill claude-code
# 生成 skill 通常会自动创建批次;需要空批次时可手工执行:
# case-atlas new-batch --project "$PWD"
case-atlas serve
请在包含测试或静态检查配置的项目根目录执行上述命令,并确保 case-atlas 已安装到当前
Python 环境;运行生成/执行 skill 还需要可用的 Claude Code 会话。install-skill 只会在
用户级 ~/.claude/skills/case-atlas-{generate,execute}/SKILL.md 创建或更新 skill,
目标项目内不写入任何文件,也不会修改测试代码。安装后,
在 Claude Code 会话中运行生成 skill,并先选择全量或增量发现范围;skill 会创建批次、
写入用例并运行最多三次 validate 自检。CLI 不会替 Agent 发现、删除或修改测试。
通常不需要手工先运行 new-batch:生成 skill 会为本次会话创建批次。只有在需要准备
空批次或调试批次文件时,才直接运行 case-atlas new-batch;该命令只创建 Case Atlas
自己的文件,不会读取项目测试。
生成 skill 会把符合契约的验证用例(按批次框架:pytest / vitest / playwright / node-test 的测试用例,tsc / ruff / mypy 的当前发现,或清单条目)写入 Case Atlas 根目录的 pending/(默认根目录为
~/.case-atlas/,也可用 CASE_ATLAS_HOME 隔离)。在本地页面完成评审后,CLI 或页面导出
case-atlas-review-<batch_id>.md;该文件同时保存到当前目录和配置的 exports_dir(默认
为根目录下的 exports/),原始批次随后进入只读归档。Web 服务只监听 127.0.0.1,不
使用数据库、模型 API 或外部静态资源。
常用命令:
case-atlas validate <batch_id>:检查批次数据契约;case-atlas list:查看 pending 批次和评审进度;case-atlas export <batch_id>:在所有用例有决策后导出并归档。
评审时可对每条用例选择 pass、discard、discard-question、revise 或
defer;discard 需要二次确认,后两种质疑/修改动作必须填写 prompt。新增需求在
页面的 add 区登记。只有所有用例都有决策(包括 defer)时才能导出;导出会拒绝覆盖
已有同名 Markdown。将生成的 Markdown 路径交给执行 skill,确认计划后 Agent 才会在新
分支或 patch 中执行删改增并运行批次框架对应的完整验证。
通过页面/API 添加的新增需求会在批次内使用 a001、a002……这样的 ID;删除后序号不会
复用,以便导出的评审记录和后续执行报告保持可追溯。validate 也支持对 exported/ 中的只读归档批次
进行复核,但归档批次不能再写入决策或新增需求。
更多命令、数据位置、故障处理和安全边界见 docs/usage.md。
这个项目最终想达成什么
让测试从“AI 批量生成的一堆文件”变成“人理解并认可、AI 持续维护、能够真实覆盖项目功能的质量资产”。
Metadata
Release files for case-atlas 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| case_atlas-0.1.0.tar.gz | 97.9 kB | Without provenance | Details for case_atlas-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| case_atlas-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for case_atlas-0.1.0-py3-none-any.whl |
Total release size: 189.1 kB
Release files / case_atlas-0.1.0.tar.gz
| Download URL | case_atlas-0.1.0.tar.gz |
|---|---|
| Size | 97.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6ab21f7d88a0c3f9184b8f1b39ea6af015603b5f0e6fc2bee6fdc8a5a7650bec
|
|
BLAKE2b-256 checksum How to use checksums |
b5e4a4a32aa8cab0c5afe3c3ce38b40eaea67283b7fa2eaeccf09845a115f41a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / case_atlas-0.1.0-py3-none-any.whl
| Download URL | case_atlas-0.1.0-py3-none-any.whl |
|---|---|
| Size | 91.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2b4b7e8b32893b208f40e4f5c1e0e0f0a8708fd8fe452f7062958dffbbe3e265
|
|
BLAKE2b-256 checksum How to use checksums |
4024f20fdbfee4a22500f3ea70aa6607cd14f933c488f7e3f43640a8c2c51f1c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for case-atlas 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.