Java Auto Test Agent

面向 Spring Boot 项目的自动化测试 Agent：Code Graph → Context RAG → 模板/LLM 生成 → Maven 执行 → JaCoCo 覆盖率迭代。

环境要求

• JDK 8+（Agent 自身）；目标项目 JDK 需与本机 Maven 一致
• Maven 在 PATH 中（Windows 使用 mvn.cmd）
• 目标项目为 Maven 多模块或单模块 Spring Boot 工程

构建

mvn clean package

产物：target/java-auto-test-agent-1.0.0.jar（fat jar）

npm CLI 发布

项目可作为 npm 命令行工具分发。npm 包只包含 Node.js 启动器和 Maven 构建的 fat JAR；运行环境仍需要 JDK 8+。

npm run verify
npm run clean

npm run verify 会运行 Maven 测试，并用 npm pack --dry-run 列出实际会发布的文件。npm pack 和 npm publish 会自动构建 JAR，完成后自动清理产物。确认 package.json 的 name、version 和 license 后，再由具备 npm 发布权限的账号执行：

npm publish --access public

若发布到 npm scope，请先将包名改为例如 @your-org/java-auto-test-agent。安装后可直接运行：

npx java-auto-test-agent /path/to/spring-boot-project --analyze-only

npm run clean 会删除 target/ 和 dist/，使源码目录恢复为无构建产物状态。

许可证

本项目采用 Apache License 2.0。发布 fat JAR 前，发布方还应根据实际 Maven 依赖清单，保留各第三方组件要求的许可证和版权声明。

快速开始

1. 仅分析（图谱 + RAG 上下文）

java -jar target/java-auto-test-agent-1.0.0.jar /path/to/spring-boot-project --analyze-only

输出：.autotest/project-graph.json、src/test/report/ 下的 prompt 与上下文文件。

2. 完整自动化审计（默认）

java -jar target/java-auto-test-agent-1.0.0.jar /path/to/project

默认执行：项目预检、图谱分析、测试生成、mvn test 与报告解析。未启用 JaCoCo 时，结果会标记为 INCONCLUSIVE，避免把“测试能运行”误报为“覆盖审计通过”。

3. 仅生成测试（不跑 Maven）

java -jar target/java-auto-test-agent-1.0.0.jar /path/to/project \
  --api="POST /users/login" --generate-only

测试写入 Controller 所在模块的 src/test/java/<controller-package>/generated/。

4. 生成并执行测试

java -jar target/java-auto-test-agent-1.0.0.jar /path/to/project --run-maven

5. 覆盖率驱动迭代

java -jar target/java-auto-test-agent-1.0.0.jar /path/to/project \
  --run-maven --with-jacoco --max-iterations=3 --line-target=80 --branch-target=70

--with-jacoco 会自动调用 JaCoCo prepare-agent 和 report；目标项目仍需允许 Maven 下载插件和依赖。

CLI 参数

| 参数 | 说明 | |------|------| | --analyze-only | 只构建图谱与 prompt，不生成测试 | | --api="GET /path" | 指定单个 API（默认全部 API） | | --run-maven | 执行 mvn test | | --generate-only | 生成测试但不执行 Maven | | --no-run-maven | --generate-only 的别名 | | --with-jacoco | 额外执行 jacoco:report | | --allow-unmeasured-pass | 明确允许未启用 JaCoCo 时把测试通过标为 PASSED | | --skip-runtime | 不部署 runtime/support 模板类 | | --max-iterations=N | 失败/覆盖率迭代次数（默认 3） | | --maven-timeout-ms=N | 单次 Maven 命令超时，默认 600000ms | | --line-target=80 | 行覆盖率目标（%） | | --branch-target=70 | 分支覆盖率目标（%） | | --llm-provider=<name> | LLM Provider（初版为 openai-compatible） | | --llm-url=<url> | LLM API 地址（可选） | | --llm-key=<key> | LLM API Key | | --llm-model=<model> | 模型名（默认 gpt-4o-mini） | | --llm-retries=2 | HTTP 429/5xx 请求重试次数 | | --llm-compile-retries=2 | LLM 生成后 test-compile 失败重试次数 | | --allow-llm-execution | 执行通过静态安全校验的 LLM 测试代码 | | --allow-insecure-llm-url | 仅对受信任本地端点允许 HTTP URL | | --allow-project-ai-config | 信任项目内 AI 配置文件（默认不读取） |

环境变量：AUTOTEST_LLM_PROVIDER、AUTOTEST_LLM_URL、AUTOTEST_LLM_KEY、AUTOTEST_LLM_MODEL、AUTOTEST_LLM_RETRIES、AUTOTEST_RUN_MAVEN=true

AI 配置文件（推荐）

不用每次传 --llm-url / --llm-key，可在 JSON 文件里配置 LLM。

生成模板

java -jar target/java-auto-test-agent-1.0.0.jar /path/to/project --init-ai-config

会在项目根目录生成 autotest-ai.json。使用该文件时请显式传入 --ai-config=/path/to/project/autotest-ai.json，或明确使用 --allow-project-ai-config。

配置示例

复制 autotest-ai.json.example：

{
  "enabled": true,
  "provider": "openai-compatible",
  "apiUrl": "https://api.openai.com/v1/chat/completions",
  "model": "gpt-4o-mini",
  "compileRetries": 2,
  "temperature": 0.2,
  "connectTimeoutMs": 15000,
  "readTimeoutMs": 120000,
  "requestRetries": 2
}

| 字段 | 说明 | |------|------| | enabled | false 时强制走模板，不调 LLM | | provider | Provider 类型，初版支持 openai-compatible | | apiUrl | OpenAI 兼容 Chat Completions 地址 | | apiKey | API Key，可选；更推荐使用 AUTOTEST_LLM_KEY 环境变量 | | model | 模型名 | | compileRetries | LLM 生成后 test-compile 失败重试次数 | | temperature | 采样温度 | | connectTimeoutMs | 建立连接超时时间 | | readTimeoutMs | 读取响应超时时间 | | requestRetries | HTTP 429/5xx 的请求重试次数 |

自动查找顺序

1. --ai-config=/path/to/file.json（显式指定）
2. ~/.autotest/ai.json
3. ~/autotest-ai.json
4. <项目>/.autotest/ai.json（仅 --allow-project-ai-config）
5. <项目>/autotest-ai.json（仅 --allow-project-ai-config）

优先级（后者覆盖前者）： 配置文件 → 环境变量 → 命令行参数。环境变量会覆盖文件中的端点与 Key。

启动时会打日志：

• Test generation: LLM (model=...) — 已启用 AI
• Test generation: template (LLM disabled or apiUrl not configured) — 走模板

建议把含 Key 的 autotest-ai.json 加入 .gitignore，勿提交仓库。项目内配置默认不读取，避免目标项目劫持 LLM 端点。

LLM 输出会先经过 Java AST 安全校验，拒绝进程、文件系统、网络、反射与静态初始化器。通过校验的 LLM 测试默认只生成、不在宿主机执行；需显式传 --allow-llm-execution。生产场景仍建议在隔离的 CI/容器环境中执行。

报告位置

src/test/report/

• report.md / report.json — 汇总（生成数、Surefire、覆盖率缺口；常见配置密钥已脱敏）
• maven-iteration-N.log — Maven 日志
• coverage-iteration-N.json — JaCoCo 解析结果

多模块项目说明

• 按 Controller 的 sourcePath 定位模块，测试写到对应子模块
• Maven 使用 -pl <artifactIds> -am，会扫描所有 *GeneratedTest.java 所在模块
• 嵌套 multi-module（如 parent/api/service）支持递归发现

重要： 升级 Agent 或修复图谱逻辑后，请删除目标项目下的 .autotest/ 以重建缓存（当前图谱版本 2.3）。

Windows 迁移清单

复制到 Windows 时至少需要：

1. Agent jar（mvn package 产物）
2. 或完整 Agent 源码中的 pom.xml + 整个 src/main/（含 resources/runtime-templates/）

在目标 Spring Boot 项目上：

rmdir /s /q D:\path\to\project\.autotest

java -jar java-auto-test-agent.jar D:\path\to\project --run-maven

本地样本项目

• samples/demo-springboot — 单模块 Spring Boot 示例（无预置生成测试）
• src/test/resources/fixtures/ — Agent 自身测试使用的内置单模块与多模块 fixture

对样本运行 Agent：

java -jar target/java-auto-test-agent-1.0.0.jar samples/demo-springboot --run-maven --skip-runtime

架构概览

AgentMain → TestPipeline
  → GraphService（AST 图谱 + 缓存）
  → ContextRetriever / PromptBuilder（RAG）
  → TestScenarioPlanner（场景计划）
  → TemplateTestGenerator / LlmProvider（生成）
  → RuntimeDeployer（runtime 支持类）
  → MavenCoverageRunner + SurefireReportParser + JaCoCoReportParser
  → ReportWriter

LLM 默认使用 openai-compatible Provider。LlmProvider 负责模型调用，OpenAiCompatibleLlmProvider 负责 Chat Completions 协议，HTTP 传输也单独抽象，后续新增其他厂商只需增加 Provider 适配器。

生成策略默认使用 @WebMvcTest + @MockBean 切片测试，避免每个 API 全量启动 Spring 容器。

开发

mvn test

集成测试使用 src/test/resources/fixtures/nested-multi-module/ 多模块 fixture。