人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载导读本文围绕 PicoClaw 仓库中的 integration/README.md 展开系统讲解该项目两层式集成测试体系Go 侧以//go:build integration构建标签守护的*_integration_test.go测试实现配合 Docker Compose 启动真实依赖的套件suite封装。你将掌握 CI 合并前到底执行了什么、运行脚本 的内部工作原理、以mcp-streamable为参照的套件目录结构以及如何按七步流程为一次真实回归场景新增一个可自动发现、可复现、可清理的集成测试套件。一、为什么需要独立于单元测试的集成测试层单元测试擅长验证函数体内的纯逻辑但当多个 PR 各自修改相邻代码路径、问题只在各组件被拼装起来后才暴露时单元测试很容易漏掉。PicoClaw 的集成测试正是为了抓住这类回归而存在典型场景包括跨包边界的协议兼容性例如 MCP 客户端与服务器之间的 JSON-RPC 消息编排真实传输上的请求/响应行为HTTP、SSE、stdio、streamable 流式等传输语义子进程、CLI 或容器的装配依赖外部二进制、容器服务的启动与连接通过环境变量传递的配置配置项如何在进程边界间传播涉及多组件的启动、发现与拆除流程从连上服务器、列出工具、调用工具到关闭清理的完整生命周期。这些场景的共同特征是风险存在于交互之中这正是 integration/README.md 明确定义的集成测试边界。二、两层集成测试机制Go 测试实现与 Docker 套件封装PicoClaw 当前使用两套相关联的机制README 特别强调了两者的分工层次载体职责Go 集成测试*_integration_test.go文件首行//go:build integration测试实现本身以构建标签显式隔离Docker 套件integration/suites/ 下的suite.envdocker-compose*.yml让测试可复现、CI 安全的运行方式一句话概括tagged Go 测试是测什么Docker 套件是怎么跑得稳。需要说明的是并非所有带integration标签的测试都进入了 Docker 套件。例如 pkg/providers/cli/ 下的真实 CLI 冒烟测试依赖本机已安装的外部二进制属于**主动选择opt-in**的手工验证手段不参与 PR 合并门禁。三、CI 到底跑什么脚本、工作流与自动发现按 README 的说明.github/workflows/pr.yml与.github/workflows/build.yml中的集成测试任务都执行同一条命令bash ./scripts/run-integration-tests.sh这个设计的关键在于自动发现runner 脚本会遍历 integration/suites/ 下的每一个目录因此新增一个套件不需要改动 GitHub Actions 工作流文件——把目录放进去CI 就能感知到它。这也解释了为什么 README 强调任何想真正保护PR 之间的合并的测试都必须能从 scripts/run-integration-tests.sh 触达。3.1 Makefile 入口仓库根目录的 Makefile 提供了统一入口.PHONY: all build install uninstall clean help test integration-test build-all lint-docs integration-test: bash ./scripts/run-integration-tests.sh即make integration-test与直接执行脚本等价。四、Runner 工作原理脚本级剖析scripts/run-integration-tests.sh 是整个体系的调度中枢其核心流程如下校验基础文件检查integration/docker-compose.runner.yml与integration/suites目录是否存在缺失直接报错退出。收集套件目录未传参数时用find $SUITES_DIR -mindepth 1 -maxdepth 1 -type d | sort全量发现传入参数如mcp-streamable则按给定名称收集便于只跑单个套件。构造 compose 参数对每个套件生成独立的 Docker Compose 项目名picoclaw-int-套件名由sanitize_project_name统一转为小写、非字母数字替换为-并叠加加载基础 compose 文件与套件内所有docker-compose.yml/docker-compose.*.yml按文件名排序。加载清单在子 shell 中以set -asource $manifest方式导入suite.env同时导出INTEGRATION_REPO_ROOT指向仓库根目录供 compose 的build.context使用。强制校验TEST_COMMAND未定义则直接报错退出RUNNER_SERVICE缺省时取默认值integration-runner。启动依赖服务用docker compose config --services列出全部服务剔除 runner 自身后对依赖服务执行docker compose up -d --build --wait即构建并等待服务就绪依赖 healthcheck。执行测试命令docker compose run --rm $runner_service $TEST_COMMAND将TEST_COMMAND作为单个参数传给以bash -c为 entrypoint 的 runner 容器执行。自动清理通过trap cleanup EXIT保证无论成功失败都执行docker compose down -v --remove-orphans清掉容器、命名卷与孤儿资源。脚本本身也有针对性的单元测试integration/run_integration_tests_script_test.go 会在临时套件目录中写入一个suite.envTEST_COMMANDprintf runner-ok和一个含fake-dependency服务的 compose 文件再用 stubdocker二进制替换真实 docker 记录参数验证脚本确实把套件命令执行了起来。4.1 共享 runner 容器的环境约定integration/docker-compose.runner.yml 定义了所有套件共享的 runner 服务services: integration-runner: image: golang:1.25-bookworm working_dir: /workspace entrypoint: [bash, -c] volumes: - ${INTEGRATION_REPO_ROOT}:/workspace - picoclaw-integration-gocache:/go-build-cache - picoclaw-integration-gomodcache:/go-mod-cache environment: GOCACHE: /go-build-cache GOMODCACHE: /go-mod-cache GOTOOLCHAIN: local CGO_ENABLED: 0 GOFLAGS: -tagsgoolm,stdjson,integration其中最关键的一行是GOFLAGS: -tagsgoolm,stdjson,integration——它保证套件内运行的所有测试与 CI 使用完全相同的构建标签避免本机通过、CI 因标签不同而行为不一致的经典陷阱。同时通过命名卷复用 Go 构建与模块缓存GOCACHE、GOMODCACHE显著缩短多套件连续运行的时间GOTOOLCHAIN: local锁定本机工具链CGO_ENABLED: 0禁用 CGO 以保证镜像内可构建。五、参考套件 mcp-streamable 深度拆解integration/suites/mcp-streamable/ 是当前仓库的参考实现它同时示范了fixture 服务器 环境变量注入 真实服务连接测试的完整范式。5.1 套件清单与编排文件suite.env指定要执行的 Go 测试TEST_COMMANDgo test ./pkg/mcp -run TestIntegration_RealConfiguredServer -vdocker-compose.yml 完成两件事覆盖 runner 的环境变量注入以及定义真实依赖服务services: integration-runner: depends_on: mcp-streamable-server: condition: service_healthy environment: PICOCLAW_MCP_REAL_SERVER_JSON: - {enabled:true,type:http,url:http://mcp-streamable-server:8080/mcp} PICOCLAW_MCP_REAL_TOOL_NAME: echo PICOCLAW_MCP_REAL_TOOL_ARGS_JSON: - {message:hello from docker integration suite} PICOCLAW_MCP_REAL_EXPECT_SUBSTRING: hello from docker integration suite mcp-streamable-server: build: context: ${INTEGRATION_REPO_ROOT} dockerfile: integration/fixtures/mcp-streamable-server/Dockerfile environment: STREAMABLE_JSON_RESPONSE: true两点工程细节值得注意用 Docker 服务名代替硬编码端口runner 通过http://mcp-streamable-server:8080/mcp访问依赖服务而不是127.0.0.1:8080这符合 READMEprefer Docker service names over hard-coded host ports的建议依赖就绪控制depends_on: condition: service_healthy与 runner 脚本的up -d --build --wait配合确保健康检查通过后才启动测试。5.2 fixture 服务器最小可复现的 MCP 服务端fixture 位于 integration/fixtures/mcp-streamable-server/。main.go 基于官方github.com/modelcontextprotocol/go-sdk/mcp构建了一个最小 streamable MCP 服务器注册名为picoclaw-integration-streamable-server的实现并挂载一个echo工具接收message参数原样返回为文本内容通过mcp.NewStreamableHTTPHandler将/mcp挂载到 HTTP mux支持以STREAMABLE_JSON_RESPONSE环境变量默认true切换 JSON 响应模式额外提供/healthz健康检查端点直接返回ok供 Dockerfile 的 HEALTHCHECK 探活。配套 Dockerfile 采用多阶段构建golang:1.25-bookworm阶段构建二进制alpine:3.22阶段以非 root 用户appuser运行并声明HEALTHCHECK --interval5s --timeout3s --retries12 CMD wget -qO- http://127.0.0.1:8080/healthz || exit 1这与 runner 的--wait配合成为依赖服务就绪判定的机制来源。5.3 两个互补的集成测试进程内兼容性与真实服务装配pkg/mcp/manager_real_server_integration_test.go 中的TestIntegration_RealConfiguredServer真实服务装配路径。它从环境变量PICOCLAW_MCP_REAL_SERVER_JSON读取服务器配置经NewManager().ConnectServer连接、GetAllTools断言至少发现一个工具再通过CallTool调用指定工具并断言返回文本包含PICOCLAW_MCP_REAL_EXPECT_SUBSTRING。测试还支持PICOCLAW_MCP_REAL_EXPECT_TOOL_COUNT精确校验工具数量并预留了 stdio 子进程服务器如npx启动的 filesystem server的配置示例。对应 Docker 套件注入的环境变量即真实服务器地址http://mcp-streamable-server:8080/mcp、调用echo工具、参数{message:hello from docker integration suite}、期望子串hello from docker integration suite——一个完整闭环。pkg/mcp/manager_integration_test.go 中的TestIntegration_StreamableHTTPCompatibility协议行为路径。它用httptest.NewServer在进程内起一个可记录请求的服务端覆盖三种组合http JSON-only 响应、http 流式响应、streamable-http别名 JSON-only并借助requestRecorder验证协议级细节streamable 模式不允许出现独立的 GET 请求、必须存在带Mcp-Session-Id的 POST、结束时恰好一次带会话 ID 的 DELETE、所有请求都携带Authorization: Bearer integration-token且initialize/tools/list/tools/call三类 JSON-RPC 方法的响应 Content-Type 与预期一致application/json或text/event-stream。如 README 所述两个测试覆盖同一区域但互补一个在进程内验证协议行为一个验证真实服务的装配与数据通路共同构成协议 服务接线的双保险。六、套件布局与必需清单字段任何新增套件目录必须包含两类文件缺一不可integration/suites/my-suite/ ├── docker-compose.yml └── suite.envsuite.env由 runner 脚本 source必须定义字段是否必需说明TEST_COMMAND必需在集成 runner 容器内执行的 shell 命令通常是一条go testRUNNER_SERVICE可选覆盖默认 runner 服务名integration-runner最小示例TEST_COMMANDgo test ./pkg/mcp -run TestIntegration_RealConfiguredServer -v七、本地运行集成测试7.1 前置条件Docker docker compose插件Docker 套件必需Go 1.25仅当你选择在本机直接跑 tagged 集成测试、而非通过 Docker 时才有需要以 docker-compose.runner.yml 中golang:1.25-bookworm镜像所对应的工具链版本为准。7.2 三种运行粒度运行 CI 跑的全部套件make integration-test等价命令bash ./scripts/run-integration-tests.sh只跑单个套件复现 CI 中该套件的完整路径最快的方式bash ./scripts/run-integration-tests.sh mcp-streamable直接跑 tagged Go 测试编写测试时迭代最快免去 Docker 开销go test -tagsgoolm,stdjson,integration ./pkg/mcp -run TestIntegration_StreamableHTTPCompatibility -v也可以手动注入与 Docker 套件相同的环境变量直接运行真实服务器冒烟测试PICOCLAW_MCP_REAL_SERVER_JSON{enabled:true,type:http,url:http://127.0.0.1:8080/mcp} \ PICOCLAW_MCP_REAL_TOOL_NAMEecho \ PICOCLAW_MCP_REAL_TOOL_ARGS_JSON{message:hello} \ PICOCLAW_MCP_REAL_EXPECT_SUBSTRINGhello \ go test -tagsgoolm,stdjson,integration ./pkg/mcp -run TestIntegration_RealConfiguredServer -v两点注意事项README 明确强调避免-short当前集成测试在 short 模式下会跳过两个 MCP 集成测试均在入口处t.Skip(skipping integration test in short mode)先用go test做紧反馈循环提交前再用bash ./scripts/run-integration-tests.sh suite-name验证 Docker 套件端到端可用。八、何时该添加集成测试判断标准是风险是否在交互之中。适合上集成测试的场景跨越进程或容器边界的代码传输特定行为HTTP、SSE、stdio 或 streamable MCP 流依赖真实子进程执行的 CLI 解析与装配配置经文件、环境变量、请求头或服务发现传播的链路多个本身合理的 PR 合并后才显现的回归。而行为是纯函数、完全可控于进程内时优先写单元测试。九、添加新集成测试的七步流程第 1 步从你想防住的回归出发先写清楚合并后可能崩掉的真实工作流场景越尖锐测试越经得起时间。例如传输归一化改动后PicoClaw 仍能连上 streamable MCP 服务器。响应处理重构后provider 包装层仍能解析真实 CLI 的输出格式。第 2 步实现 Go 测试在所属包内新增或扩展*_integration_test.go文件首行加构建标签//go:build integration编写指南断言聚焦可观察行为使用有界的超时参考示例中的30*time.Second/10*time.Second优先用确定性 fixture避免依赖公网或共享外部状态仅当依赖是刻意可选的如本机安装的第三方 CLI才使用 skip。第 3 步决定它是否要卡 CI 合并经验法则只是手工冒烟检查 → tagged Go 测试可能就够要防止回归通过 PR 合并落地 →必须接进 Docker 套件。第 4 步复用或新增套件已有套件覆盖同一子系统则直接扩展否则新建integration/suites/name/ ├── docker-compose.yml └── suite.env可复用的 helper 服务或假服务器放进 integration/fixtures/。第 5 步定义套件命令在suite.env中用TEST_COMMAND指向要跑的 Go 测试TEST_COMMANDgo test ./pkg/mcp -run TestIntegration_RealConfiguredServer -vTEST_COMMANDgo test ./pkg/somepkg -run TestIntegration_MyScenario -v多个测试共享同一环境时可在一条命令中跑但套件要保持内聚、便于失败时定位。第 6 步在 Docker Compose 中建模依赖套件 compose 文件可以定义测试所需的依赖服务、扩展或覆盖共享的integration-runner、向 runner 注入测试消费的环境变量。实操建议用 Docker 服务名而不是硬编码主机端口依赖服务就绪依赖时加 healthcheck让套件自包含、确定性。第 7 步提交前本地验证go test -tagsgoolm,stdjson,integration ./path/to/package -run TestIntegration_Name -v bash ./scripts/run-integration-tests.sh suite-name前者服务于编写期后者证明 CI 路径端到端可用。十、新套件审查清单开 PR 前逐项核对新套件应当复现一个真实的多组件失败模式确定性与隔离性良好CI 中无需手工准备失败输出清晰运行时间合理通过常规 runner teardown自我清理。提交后套件会被 CI 集成任务自动发现无需改动任何工作流文件——这是这套体系以目录即配置的最终优势。补充说明本文涉及的版本与标签如goolm、stdjson、Go 1.25均以当前仓库 integration/docker-compose.runner.yml、Makefile 与 scripts/run-integration-tests.sh 中的实际内容为准若需要验证任意一步均可直接在仓库内对照上述路径的源码与测试执行。赞分享人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载相关推荐OnyxdanswerCoda 连接器集成测试套件实战指南从环境准备到 CI/CD 落地OnyxdanswerCoda 连接器集成测试套件实战指南从环境准备到 CI/CD 落地 本篇指南聚焦开源 AI 平台 Onyx原 danswer中AI 应用大模型RAGAI Agent后端前端Chainlink 本地 CRE 系统测试实战从 smoke 套件到 CI 维护的完整指南Chainlink 本地 CRE 系统测试实战从 smoke 套件到 CI 维护的完整指南 本指南围绕 Chainlink 仓库中 Local CRE本地链区块链Web3后端如何用Fasttracker 2 Clone创作专业电子音乐完整入门指南如何用Fasttracker 2 Clone创作专业电子音乐完整入门指南 想要制作复古风格的电子音乐但不知从何开始Fasttracker 2 Clone是你上一篇PhoneInfoga 多源数据聚合把 5 个数据源并排比着验证一个号码下一篇【限时免费】 《zinx的安装与使用教程》创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考