企业官网建设流程全解析

JavaClaw 是一个基于 Spring Boot、Spring AI 和 JobRunr 构建的 Java 版 OpenClaw（个人 AI Agent 网关），它把测试当成一等公民：用 Testcontainers 让 Spring 集成测试不依赖本地环境，用 ArchUnit 把"核心、插件、Provider 互不越界"写死成可执行的架构规则，再用"假上游"（Fake Upstream）实现零凭据、零真实推理的集成测试。本文带你逐一拆解 JavaClaw AI Agent 测试的三大核心套路，帮助新手快速掌握 AI Agent 项目的测试方法。

一、分层测试全景：每层只解决一类问题 🔍

JavaClaw 是典型的 Gradle 多模块工程：base/（Agent、任务、工具等核心）、providers/（Anthropic、OpenAI、Ollama 等 LLM 提供方）、plugins/（Telegram、Discord、Brave、Playwright 等插件）、app/（Spring Boot 入口与 Web 聊天通道）。每个模块自带测试目录，且按"测试金字塔"分工明确：

所有测试统一在 build.gradle 根配置中启用 JUnit Platform，版本集中管理在 libs.versions.toml（如 ArchUnit 1.4.2）。

二、Testcontainers：Spring 集成测试不依赖本地数据库 🧱

AI Agent 应用动辄要连数据库、消息队列，本地环境一乱测试就"薛定谔式失败"。JavaClaw 的解法很轻：

1. 依赖引入：app/build.gradle 中同时引入spring-boot-testcontainers与testcontainers-junit-jupiter，base/build.gradle也引入了后者，两个模块共享容器能力。
2. 测试专用配置：TestcontainersConfiguration.java 是一个极简的@TestConfiguration，作为容器装配的挂载点。
3. 独立测试入口：TestJavaClawApplication.java 通过SpringApplication.from(JavaClawApplication::main).with(TestcontainersConfiguration.class)组装应用，测试运行时自动带上容器环境。

配合runtimeOnly 'com.h2database:h2'，开发用内嵌 H2、测试用容器化组件，测试机不需要预装任何中间件——这是 Spring AI 项目做 CI 集成测试的标准姿势。

三、ArchUnit 模块边界：用代码守住架构红线 🚧

插件化的 AI Agent 框架最大的腐化风险是：今天 Telegram 插件顺手引用了 Discord 插件，明天 Provider 偷偷依赖了某个工具插件。JavaClaw 用 ArchUnit 把边界规则变成"违反即构建失败"的测试。

ModuleBoundaryArchTest.java 定义了 6 条规则，覆盖ai.javaclaw全部包（排除测试代码）：

值得注意的技巧：用slices().matching("..channels.(*)..")通配切分，未来新增一个通道插件无需改测试，规则自动生效。

此外还有两道补充防线：

• Spring Modulith 结构校验：ModularityTests.java 调用ApplicationModules.of(JavaClawApplication.class).verify()，校验模块内部包的依赖方向。
• 自动配置注册校验：AutoConfigurationImportsTestSupport.java 通过java-test-fixtures机制从base/模块共享给各 Provider 模块，确保每个@AutoConfiguration都真实注册在AutoConfiguration.imports文件中，防止"类写了但没生效"。例如 AnthropicAgentAutoConfigurationTest.java 用它做了断言。

四、假上游集成测试：零凭据验证 Claude Code 通道 🎭

测试 AI Agent 最难的一环是：真实模型调用花钱、不稳定、有网络依赖。JavaClaw 的claude-codeProvider 用"假上游"优雅破解了这个难题。

FakeAnthropicUpstream.java 只用 JDK 自带的HttpServer在 127.0.0.1 随机端口搭了一个合成版 Anthropic Messages 端点，按"脚本"回放 SSE 流，支持 7 种模式：

然后 ClaudeCodeChatModelIntegrationTest.java 驱动真实的claudeCLI 进程去打这个假上游，验证真实命令行参数、stream-json 协议、历史回放、工具命名映射、429 错误映射，甚至"取消流时上游连接是否关闭"。关键在于：

• 不需要任何 API Key，不发生真实推理（ANTHROPIC_API_KEY填的是fixture-not-a-real-key）；
• 用@EnabledIf("claudeInstalled")标注（L37），没装claude的环境自动跳过，CI 不阻塞。

这套"真客户端 + 假服务器"的模式，是所有 AI Agent 项目集成测试的黄金参考。

五、WebSocket 流式集成测试：真端口验证分帧协议 📡

Web 聊天是 JavaClaw 的核心交互，回答以chunk→chunk→done的 JSON 帧推送。ChatStreamingIntegrationTest.java 的做法：

1. @SpringBootTest(webEnvironment = RANDOM_PORT)拉起真实 Tomcat 与 WebSocket 端点；
2. 用StandardWebSocketClient连接ws://localhost:{port}/ws/chat，发送一条userMessage帧；
3. 断言收到帧类型序列containsSubsequence("chunk", "chunk", "done")且以done收尾（L70-L72）。

而 Agent 本身被一个内存版假实现替代（TestConfig 内直接返回 Token 事件），再搭配InMemoryChatMemoryRepository，只测传输协议，不碰任何 LLM。

六、单元测试的克制：Mockito + WebMvcTest ✅

集成测试再强，也需要大量快速单元测试兜底，JavaClaw 的几个亮点：

• 切片测试：AgentPageControllerTest.java 用@WebMvcTest+@MockitoBean只加载 Controller 层，逐一验证列表、新建、编辑、404、422 校验等 HTMX 片段行为；
• 无 Spring 容器的纯单测：TaskManagerTest.java 用 Mockito 隔离 Agent 与仓储，JobRunr 换成InMemoryStorageProvider，异步断言交给 Awaitility；
• 错误路径也测 UI：ChatWebSocketHandlerTest.java 验证 Agent 抛 401 时，前端会收到"清除输入中指示器 + 展示错误详情"的 HTML 片段——连出错时的用户体验都有测试守护。

七、快速上手：运行 JavaClaw 的完整测试 🚀

git clone https://gitcode.com/gh_mirrors/ja/JavaClaw cd JavaClaw ./gradlew test

分模块运行示例：

💡 提示：项目使用 Java 25 工具链（见 build.gradle），请确保本地 JDK ≥ 25。

八、小结：AI Agent 项目测试的三条可复制经验 📝

1. 架构规则代码化：用 ArchUnit（slices()+ 通配包名）+ Spring Modulith 双重守护模块边界，新插件零维护成本纳入治理；
2. 外部依赖容器化：Testcontainers + 内嵌数据库让集成测试在任何机器上都能跑；
3. 真实协议假数据：用本地假上游回放 SSE/流式协议，真实客户端零凭据集成测试，@EnabledIf优雅跳过缺依赖环境。

这三层防线共同保证了 JavaClaw 这样的多 Provider、多通道 AI Agent 框架在快速迭代中，架构不腐化、协议不漂移、CI 不烧钱。