agent-test-gap-mapper

agent-test-gap-mapper 是一个离线 Python CLI，用来给 Codex、Claude Code、Cursor、Aider 等 AI 编程代理产生的代码改动绘制“测试缺口地图”。它读取 git diff、changed-files 列表、JUnit XML、coverage XML、repo 树和 JSON 配置，输出本次改动缺少哪些测试证据、哪些高风险文件需要额外验证、推荐测试命令，并可作为 CI gate 返回退出码。

它不上传源码、不调用远程服务，运行时只使用 Python 标准库。

适用场景

• AI agent 提 PR 前快速检查“还有哪些测试证据缺口”。
• 在 CI 中把缺少测试证据的源码改动标成 warning 或 error。
• 从 pytest JUnit XML 中把失败测试映射到改动风险报告。
• 从 coverage XML 中发现改动文件低覆盖率或覆盖率下降。
• 为 reviewer 生成 brief/Markdown/JSON/JUnit/SARIF 格式的轻量证据报告。
• 把测试缺口作为 SARIF 上传到 GitHub Code Scanning，让 reviewer 在代码扫描视图里看到证据缺口。
• 用 baseline 记录已复核的历史测试缺口，让 CI 只拦截新增 warning/error。

安装

本项目要求 Python 3.9+。

python -m pip install .
agent-test-gap-mapper --version

开发环境可直接运行：

python -m pip install -e .
python -m unittest discover -s tests
python -m agent_test_gap_mapper --version

快速用法

从 git diff 生成 Markdown 报告：

git diff -- src tests > work/change.diff
agent-test-gap-mapper from-diff work/change.diff --format markdown --output outputs/gap-map.md

生成可直接粘贴到 PR 评论或 AI agent 交接里的短摘要：

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --format brief \
  --output outputs/test-gap-brief.md

生成可直接交给 agent 执行的补测计划：

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --format plan \
  --output outputs/test-plan.md

如果要给自动化或机器人读取：

agent-test-gap-mapper from-diff work/change.diff --format plan-json --output outputs/test-plan.json

合并 diff、JUnit、coverage，并在 warning 及以上时让 CI 失败：

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --baseline-coverage reports/base-coverage.xml \
  --format json \
  --output outputs/gap-map.json \
  --check warning

初始化配置：

agent-test-gap-mapper init-config .agent-test-gap-mapper.json

只看 JUnit 失败测试：

agent-test-gap-mapper from-junit reports/junit.xml --format markdown

只看 coverage 文件低覆盖率信号：

agent-test-gap-mapper from-coverage reports/coverage.xml --format junit --output outputs/gap-map.junit.xml

输出 SARIF 给 GitHub Code Scanning 或其他安全/质量平台：

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --format sarif \
  --output outputs/test-gap-map.sarif

生成并使用已复核 baseline：

agent-test-gap-mapper from-diff work/change.diff --write-baseline outputs/test-gap-baseline.json
agent-test-gap-mapper from-diff work/change.diff --baseline outputs/test-gap-baseline.json --check warning

子命令

• analyze: 综合 diff、changed-files、JUnit、coverage 和 repo tree。
• from-diff: 从 unified git diff 分析改动测试缺口。
• from-junit: 从 JUnit XML 输出失败测试映射和推荐命令。
• from-coverage: 从 coverage XML 输出改动文件覆盖率信号。
• init-config: 写出默认 JSON 配置。

检测能力

• 源码改动无对应测试改动、JUnit 证据或 coverage 证据。
• 删除、修改、重命名测试文件。
• 只改文档时降为 info。
• 风险目录或文件模式权重，例如 auth、security、billing、db、cli。
• coverage XML 中改动文件低覆盖率。
• baseline coverage XML 与当前 coverage XML 的下降信号。
• JUnit XML 中失败测试映射。
• 推荐 pytest、coverage xml、unittest discover 等命令。
• brief 短摘要输出，包含 PASS/REVIEW/BLOCK 决策、最高风险缺口和下一步命令。
• plan / plan-json 输出，把每个缺口变成优先级、测试目标、验收标准和 agent prompt。
• SARIF 2.1.0 输出，可上传到 GitHub Code Scanning。
• baseline JSON 输出和 --baseline 过滤，可保留已接受风险并只阻断新增缺口。
• --check warning|error CI gate，达到阈值返回退出码 2。
• --output 会自动创建父目录。

配置

配置文件是 JSON，默认读取当前目录的 .agent-test-gap-mapper.json。

{
  "source_patterns": ["src/*.py", "src/**/*.py", "*.py"],
  "test_patterns": ["tests/*.py", "tests/**/*.py", "test_*.py", "*_test.py"],
  "docs_patterns": ["README*", "CHANGELOG*", "CONTRIBUTING*", "docs/**", "*.md", "*.rst"],
  "ignore_patterns": [".git/**", ".venv/**", "venv/**", "__pycache__/**", "*.pyc"],
  "risk_weights": {
    "src/**/auth*.py": 3,
    "src/**/security*.py": 3,
    "src/**/payment*.py": 3,
    "src/**/billing*.py": 3,
    "src/**/db*.py": 2,
    "src/**/migration*.py": 2,
    "src/**/cli*.py": 2
  },
  "required_evidence": ["test_change_or_junit_or_coverage"],
  "severity_threshold": "warning",
  "coverage_min_line_rate": 0.7,
  "coverage_drop_tolerance": 0.005
}

required_evidence 支持：

• test_change_or_junit_or_coverage
• test_change
• junit
• coverage

输出字段

JSON 输出包含：

• summary: 改动文件数、源码改动数、测试改动数、文档改动数、失败测试数、coverage 文件数、按严重级别统计。
• recommended_commands: 推荐运行的测试命令。
• findings: 每个发现项，字段为 severity、category、path、message、evidence、recommendation。
• suppressed_findings: 使用 baseline 后被压制的历史缺口明细。

plan-json 输出包含：

• summary.plan_items: 生成的补测任务数量。
• items: 每个计划项的 priority、path、recommended_command、test_targets、acceptance_criteria、agent_prompt 和 fingerprint。

brief 输出适合 PR 评论、agent handoff 和 reviewer 快速判断；plan 输出适合直接分派给 agent 补测试；Markdown 输出适合完整人工阅读；JSON 适合自动化；JUnit 适合上传到 CI 测试报告；SARIF 适合上传到 GitHub Code Scanning 或质量平台。

brief 示例：

# Test Evidence Brief

Decision: REVIEW - warning-level gaps should be resolved or explicitly accepted.
Scope: 3 changed files, 1 source, 1 tests, 0 failed tests.
Findings: 0 error, 2 warning, 0 info.

Top gaps:
- WARNING missing_test_evidence [src/shop/billing.py]: Source changed without matching test-change, JUnit, or coverage evidence.
  Next: Add or run a focused test such as tests/test_billing.py

Recommended commands:
- pytest tests/test_billing.py

Baseline 工作流

baseline 是一个可审阅、可提交的 JSON 文件，包含每条测试缺口的 category、path、message、evidence、recommendation 和稳定 fingerprint。它适合在已有仓库首次接入时承认历史缺口，同时要求后续 PR 不再新增缺少测试证据的改动。

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --write-baseline outputs/test-gap-baseline.json

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --baseline outputs/test-gap-baseline.json \
  --check warning \
  --format json \
  --output outputs/test-gap-map.json

建议流程：

1. 首次接入时生成 test-gap-baseline.json。
2. 人工审阅 baseline 中的缺口类别、路径、证据和 fingerprint。
3. 将 baseline 文件提交到仓库或放入受控质量例外目录。
4. CI 中使用 --baseline，只让新增 warning/error 缺口阻断合并。

不要在同一个阻断型 CI run 中先生成 baseline 再扫描当前改动，否则当前缺口会被直接放过。baseline 应该由维护者在风险复核后更新。

CI 示例

.github/workflows/ci.yml 中包含项目自身测试。集成到其他仓库时可以这样使用：

git diff origin/main...HEAD > work/change.diff
agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --baseline outputs/test-gap-baseline.json \
  --format brief \
  --output outputs/test-gap-brief.md \
  --check warning

上传 SARIF 到 GitHub Code Scanning：

- run: >
    agent-test-gap-mapper analyze
    --diff work/change.diff
    --junit reports/junit.xml
    --coverage reports/coverage.xml
    --format sarif
    --output outputs/test-gap-map.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: outputs/test-gap-map.sarif

examples

examples/ 目录包含可直接运行的 diff、JUnit、coverage 和配置样例：

agent-test-gap-mapper analyze \
  --config examples/config.json \
  --diff examples/change.diff \
  --junit examples/junit.xml \
  --coverage examples/coverage.xml \
  --baseline-coverage examples/baseline-coverage.xml \
  --format markdown

隐私

本工具离线运行，不读取网络，不发送代码、测试结果或配置。报告内容来自你显式传入的文件。

限制

• 路径关联是启发式匹配，不等同于完整依赖分析。
• coverage XML 当前按 Cobertura 风格解析。
• 推荐命令偏向 Python 项目，非 Python 仓库应通过配置和 CI 包装命令补充。
• 覆盖率下降需要同时提供当前和 baseline coverage XML。
• baseline 是审计文件，不是永久忽略规则；请像维护质量例外一样审阅和定期清理。

English

agent-test-gap-mapper is an offline Python CLI that maps missing test evidence for code changes produced by AI coding agents. It accepts unified diffs, changed-file lists, JUnit XML, coverage XML, repository tree lists, and JSON configuration. It reports missing test evidence, risky changed paths, failed test mappings, recommended test commands, and CI gate exit codes.

Runtime has no third-party dependencies. Output formats are brief, test implementation plan, Markdown, JSON, JUnit XML, and SARIF 2.1.0. It is designed for pre-PR checks, local agent workflows, CI evidence gates, reviewer handoffs, and GitHub Code Scanning upload.

Use --format brief when you want a compact PR comment or agent handoff with a PASS/REVIEW/BLOCK decision, top gaps, and next commands:

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --baseline outputs/test-gap-baseline.json \
  --format brief \
  --output outputs/test-gap-brief.md

Use --format plan when the next coding agent should receive concrete test implementation work:

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --format plan \
  --output outputs/test-plan.md

Use --format plan-json for automation. Each item includes priority, inferred test targets, acceptance criteria, a recommended command, and an agent prompt.

Typical SARIF usage:

agent-test-gap-mapper analyze \
  --diff work/change.diff \
  --junit reports/junit.xml \
  --coverage reports/coverage.xml \
  --format sarif \
  --output outputs/test-gap-map.sarif

Reviewed baseline JSON files let teams suppress known historical test evidence gaps while still failing CI on new warning/error gaps:

agent-test-gap-mapper from-diff work/change.diff --write-baseline outputs/test-gap-baseline.json
agent-test-gap-mapper from-diff work/change.diff --baseline outputs/test-gap-baseline.json --check warning

Use github/codeql-action/upload-sarif@v3 in GitHub Actions to publish the report into Code Scanning.