testgraph

testgraph 是一个旅程级（journey-level）的测试选择器。给定一个 git diff，它能回答一次变更可能会破坏哪些面向用户的流程，以及应该按什么顺序进行测试，返回一个简短的排序列表，而不是指令要求重新运行所有测试。它刻意不驱动浏览器、不生成测试也不进行自我修复；其明确职责是作为现有驱动程序之上的层级，即决定哪些内容值得测试。 工作原理 旅程注册表（journey registry）为每个用户旅程及其入口符号（如路由处理器或调度器扫描）命名。propose 模块通过扫描 Python 路由装饰器和 Next.js 约定并对照索引，为新仓库起草注册表，在人工审核前将其标记为 approved false，因此未审核的注册表在运行时会发出警告而不会静默运行。对于 diff，testgraph 将变更的行范围映射到拥有这些行的符号（即种子）；在 CodeGraph 边图中反向传递遍历，直到找到所有依赖于种子的符号（即受影响集）；然后报告其入口符号在该集合中的旅程，并按扇入（fan-in）排序，每个旅程携带到达它的最强边路径的置信度。置信度是路径中最小边的最大值，因此一条链的可靠性取决于其最弱的一环，而一条稳固的路径就足够了。仅通过弱边或合成边到达的旅程会被标记为需要手动验证而非静默信任，且绝不会从选择列表中删除。该工具遵循召回率优先原则：宁愿过度选择，也不愿静默丢弃一个确实受变更影响的旅程。在回答之前，完整性守护程序（integrity guard）会拒绝在损坏或陈旧的 CodeGraph 索引上运行，因为错误的图会产生自信的错误答案。 注册表解析采用“首中即得”搜索：首先是环境变量逃生口，然后是仓库内部的 .testgraph/journeys 目录（推荐位置），最后是项目检出中与包相邻的 journeys 目录。在所有位置中，注册表根据其自声明的目标而非文件名进行匹配，且拒绝使用从另一个项目复制且未编辑的注册表。 前提条件与安装 需要 Python 3.11 或更高版本（仅使用标准库，无第三方依赖）；用于 diff 输入的 git；以及一个由 codegraph init 生成 CodeGraph 索引的目标仓库。通过 PyPI 使用 pip install testgraph 安装。wheel 包仅包含该软件包，而测量框架和 dogfood 注册表则留在仓库中。 CLI 与 MCP 命令行入口包括 select（提供面向人类或 JSON 的输出，用于 CI 门禁或其他代理）、export（写入静态旅程映射供代理在提交前读取）、propose、record 以及摘要模式。MCP stdio 服务器公开了两个工具：testgraph_impact 和 testgraph_journeys，并按仓库注册。它仅使用标准库并延迟导入分析模块，因此空闲服务器不会加载 sqlite3，不持有数据库连接，也不在内存中保留索引。README 报告在完整握手后测得的 RSS 为 15.2 MB，而典型的 Python MCP SDK 服务器为 62 至 69 MB。 接线与账本 hooks/install.sh 为每个拥有已审核注册表的仓库安装 pre-push 钩子，因此每次 push 都会打印出可能被破坏的旅程。钩子首先运行 codegraph sync，因为种子来自行范围，如果在代码移动前构建索引，则 diff 将对照陈旧的跨度解析；如果变更文件的字节仍与索引副本不一致，答案将降级并指明该文件。钩子绝不会导致 push 失败（所有路径退出码均为 0），且可以通过 git config 设置在每个仓库中禁用，或使用 uninstall 标志删除。每次运行都会向 JSONL 账本追加一行选择记录；record 命令写入另一半内容（即运行旅程的结果），将两者通过仓库和提交记录关联，可以统计出在选择列表中未出现但实际失败的旅程，这被称为“静默欠选”（silent under-selection）。 状态 它被描述为阶段 1 的探索性开发（spike）加上置信度加权路径，已在一个 dogfood 目标上验证：在 5 个手动标记的提交中召回率为 1.00，平均精确度为 0.68；在 20 个基于独立 AST oracle 评分的种子突变点中召回率为 1.00，且完整性守护程序已通过测试并固定了 schema。其范围仅限于该单一目标，分析后端和前端文件，旅程注册在后端入口点上。README 还记录，随后在两个没有注册表的仓库上进行的测量证伪了早期的节省主张：在 23 个旅程的情况下，一个仓库在 38 个提交中返回 0 个旅程，在 2 个提交中返回 23 个；在 207 个旅程的情况下，另一个仓库在排除未触及注册表表面的提交后，仅避免了 54.1% 的旅程运行。因此，选择数量应被视为耦合度的底线，而非节省时间的承诺。同样的测量确认了排序功能：一个置信度为 0.3 的全注册表误报被标记为手动验证，而一个真实的巨大影响范围则以 0.9 的置信度清晰返回。