接口 Mock 和契约测试

目的

定义接口如何 mock、fixture 如何管理、前后端如何并行开发。先保证人能在没有真实外部服务时开发和验证，后续 Agent 也复用同一套 mock 和 sandbox。

基本原则

  1. Mock 必须来自契约，不要凭空造数据。
  2. Mock 数据要覆盖正常、空状态、错误、权限不足、边界状态。
  3. Contract test 必须验证 mock 和真实 API 不漂移。
  4. 外部服务用 fake server 或 recorded fixture，不直接依赖生产。
  5. 后续自动化或 Agent run 默认使用 mock 或 sandbox，除非获得真实集成权限。

三角色 Mock 责任

角色 负责判断
产品负责人 mock 数据是否覆盖核心用户状态、空状态、错误状态
技术负责人 mock 是否来自契约，contract test 是否能防止漂移
平台 / 资深工程师 fake server、fixture、sandbox、smoke 命令是否可复现

契约来源

接口类型 契约来源
REST API OpenAPI / TypeScript schema / shared protocol
Webhook fixture + signature test
Runtime protocol packages/protocol 或 Go/TS shared schema
DB read model migration + query tests
External provider recorded fixture + smoke witness

如果仓库已有 packages/protocol 或 shared schema 包，应作为 runtime/API 协议的核心契约来源。

Mock 类型

类型 用途 工具建议
UI mock 前端无后端时开发页面 MSW、fixture JSON
API fake 后端外部依赖替身 fake server、Vitest fixture
Provider fake Codex/GitHub 等外部集成替身 witness fixture、fake daemon
DB seed 本地和测试数据 seed script、migration fixture
Contract fixture 协议回归 shared fixture + schema validation

前后端并行流程

定义 API 契约
-> 生成或手写 fixture
-> 前端用 MSW / mock client 开发
-> 后端实现真实 API
-> contract test 对齐 schema
-> integration test 验证真实 API

Mock 数据集

每个核心页面至少有：

  1. 正常数据。
  2. 空状态。
  3. 加载状态。
  4. 错误状态。
  5. 权限不足。
  6. 大量数据。
  7. 边界字段缺失。

外部接口 Mock

GitHub

需要覆盖：

如果仓库已有 scripts/github-*smoke* 等脚本，应继续作为真实集成 witness。Witness 和 smoke 的区别：

类型 依赖真实外部服务 验证重点 失败说明
Contract fixture 否 本地 schema、fixture、parser 是否兼容 代码和契约不一致
Witness test 通常否，或只使用录制/沙箱数据 webhook 签名、payload normalization、权限映射、错误分类 集成协议处理有问题
Smoke test 是，使用低风险真实账号或 sandbox 凭证、网络、provider API、adapter、状态回传是否端到端可用 真实集成路径失效

后续 Provider / Agent

需要覆盖：

参考命令包括 runtime:fake、runtime:test、smoke:codex，实际项目应替换为自己的 provider fake、runtime test 和 smoke。

命令语义 目的 示例命令
Fake provider 本地模拟 provider 响应，覆盖成功、失败、超时、权限不足 pnpm runtime:fake、fake server、recorded fixture
Runtime protocol test 验证 runtime daemon 的 claim、heartbeat、日志回传、artifact 上报 pnpm runtime:test、go test ./...
Real provider smoke 用真实或 sandbox provider 跑低风险闭环 pnpm smoke:codex、项目 provider smoke
Failure fixture 固定错误样本，验证 error classification 和 retry 策略 fixture-based test

后续 Agent 就绪要求

Agent 执行时应优先使用：

  1. Mock API。
  2. Fake daemon。
  3. Sandbox provider。
  4. Recorded fixture。
  5. Contract test。

只有在 scope、secret grant、approval 都满足时，才允许真实外部服务调用。

反模式

下一步阅读

读完或填完这份文档后，通常继续看：