IntegrationTesting

心智模型

集成测试通过真实 LLM API 调用验证 Agent 各组件能否正确协作、凭证是否有效、延迟是否可接受。由于 LLM 响应的非确定性，测试策略需不同于传统软件：分离测试套件、管理密钥、验证结构而非内容，并通过录制回放等手段控制成本与提升稳定性。

二级标题及内容

• 【分离测试】Separate unit and integration tests 用 @pytest.mark.integration 标记集成测试，在默认运行中排除，仅在 CI 或部署前执行，保持单元测试的快速反馈。

• 【管理密钥】Manage API keys 通过环境变量加载 API 凭证，在 conftest.py 中自动检查密钥可用性并跳过无密钥的测试。本地用 .env 管理，CI 用平台密钥注入。注意：.env 必须加入 .gitignore。

• 【验证结构而非内容】Assert on structure, not content LLM 响应每次不同，断言应针对消息类型、工具调用名称、参数形状、消息数量等结构属性，而非确切文本。

• 【降低成本与延迟】Reduce cost and latency 使用更小的模型、设置 max_tokens 限制响应长度、每个测试专注于单一行为、只在 CI 中运行集成测试。

• 【录制与回放】Record and replay HTTP calls 使用 vcrpy 和 pytest-recording 录制首次运行的 HTTP 交互为磁带文件，后续运行直接回放，消除重复的 API 成本与延迟。注意：修改提示词或工具后，磁带文件会失效，需删除并重新录制。

最佳实践

• 标记并分离测试：在 CI 或缺省运行中排除集成测试，避免因网络和慢调用拖慢开发循环。
• 保护密钥安全：密钥永远不硬编码，不提交到版本控制，通过环境变量和 CI 密钥管理注入。
• 结构断言更稳健：避免对 LLM 生成的自然语言做精确断言，转向可验证的结构特征来减少随机失败。
• 录制回放是缓存利器：在 CI 中频繁运行的测试，用录制回放可将外部依赖固化到磁带文件中，稳定且零成本。
• 磁带失效需主动维护：修改 Agent 行为后，必须删除旧磁带并重新录制，否则测试会失败。