integration-contract-testing

集成契约测试

使用此技能验证适配器边界是否符合应用所依赖的契约。

核心规则

• 测试边界契约，而非供应商实现。
• 验证成功和失败响应的形状。
• 保持测试夹具真实、精简且已脱敏。
• 优先在边界进行架构验证，并断言无效的供应商数据会被拒绝。
• 应用测试使用伪造对象，适配器行为则使用有针对性的集成测试。
• 确保 CI 具有确定性。联网测试需要明确选择启用、稳定的凭据和清晰的跳过行为。

契约测试层

1. 映射测试：将外部测试夹具映射为内部类型。
2. 错误规范化测试：将供应商故障转换为应用错误。
3. 适配器接缝测试：验证适配器发送了预期的命令/请求，并正确处理响应。
4. 可选的在线冒烟测试：在受控环境中确认凭据、端点和一项安全操作。

测试夹具规则

• 将已脱敏的测试夹具存放在适配器测试附近。
• 按行为命名测试夹具：customer-success.json、customer-missing-required-field.json。
• 至少包含一个格式错误或不完整的响应测试夹具。
• 除非完整结构就是契约，否则避免使用大型黄金文件。
• 对令牌、凭据、个人数据和专有负载详情进行脱敏。

测试检查清单

• 成功响应会映射为内部契约。
• 缺少必填字段时会清晰报错。
• 会妥善处理意外的枚举值/状态。
• 超时或网络故障会映射为可重试/不可用错误。
• 身份验证/授权失败不会作为暂时性故障重试。
• 分页会正确停止，并保留游标/检查点。
• 在可用时保留请求 ID 等可观测性字段。

伪造对象与模拟对象

测试用例时使用行为伪造对象：

class FakeCustomerGateway implements CustomerGateway {
  customers = new Map<string, Customer>();

  async getCustomer(id: string) {
    return this.customers.get(id);
  }
}

仅在测试适配器本身时，才在 SDK/HTTP 接缝处使用范围明确的模拟对象。

常见错误

• 只测试是否调用了模拟对象，却不测试调用后的行为。
• 只测试成功路径的测试夹具。
• 允许原始供应商字段泄漏到领域断言中。
• 让所有测试都依赖外部在线服务。
• 未对测试夹具数据进行脱敏。