configure-api-tests

/configure:api-tests

检查并配置 API 契约测试基础设施，以验证 API 契约、架构和消费者-提供者协议。

适用场景

在以下情况下使用此技能……	在以下情况下采用其他方法……
设置 Pact 消费者/提供者契约测试	编写单个单元测试（/configure:tests）
配置 OpenAPI 请求/响应验证	手动验证单个 API 端点
添加 JSON Schema 或 Zod 架构测试	检查常规测试覆盖率（/configure:coverage）
在 CI 中检测 API 破坏性变更	审查 API 设计决策（code-review agent）
审计整个项目的 API 测试合规性	配置常规 CI/CD 工作流（/configure:workflows）

上下文

• 项目根目录：!pwd
• 包文件：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' \)
• Pact 依赖项：!find . -maxdepth 1 \( -name package.json -o -name pyproject.toml \) -exec grep -l 'pact' {} +
• OpenAPI 规范：!find . -maxdepth 1 \( -name 'openapi.yaml' -o -name 'openapi.json' -o -name 'swagger.json' \)
• Pact 目录：!find . -maxdepth 1 -type d -name 'pacts'
• 契约测试：!find tests -maxdepth 2 -type d -name 'contract'
• 项目标准：!find . -maxdepth 1 -name '.project-standards.yaml'

参数

从命令参数中解析：

• --check-only：仅报告合规状态，不做修改（CI/CD 模式）
• --fix：自动应用修复，不提示确认
• --type <pact|openapi|schema>：专注于特定类型

API 测试类型：

类型	用例
Pact	微服务、多个消费者、破坏性变更检测
OpenAPI	API 优先开发、文档驱动测试
Schema	简单验证、GraphQL API、单个服务

执行

执行此 API 测试合规性检查：

步骤 1：检测现有 API 测试基础设施

检查以下指标：

指标	组件	状态
依赖项中包含 pact	Pact 契约测试	已安装
openapi.yaml 或 swagger.json	OpenAPI 规范	已存在
@apidevtools/swagger-parser	OpenAPI 验证	已配置
依赖项中包含 ajv	JSON Schema 验证	已配置
pacts/ 目录	Pact 契约	已存在

步骤 2：分析当前状态

针对每个检测到的组件，检查其完整性：

契约测试（Pact）：

• 已安装 @pact-foundation/pact（JS）或 pact-python（Python）
• 已定义消费者测试
• 已配置提供者验证
• 已配置 Pact Broker 或 PactFlow（可选）
• 已集成 CI/CD 流水线

OpenAPI 验证：

• OpenAPI 规范文件存在
• 已配置请求验证中间件
• 已在测试中进行响应验证
• 已配置架构自动生成
• 已配置破坏性变更检测

架构测试：

• JSON Schema 定义存在
• 已安装 ajv 或类似验证器
• 已创建响应验证辅助工具
• 已制定架构版本管理策略

步骤 3：生成合规报告

输出格式化的合规报告：

API Testing Compliance Report
==============================
Project: [name]
API Type: [REST | GraphQL | gRPC]

Contract Testing (Pact):
  @pact-foundation/pact    package.json               [INSTALLED | MISSING]
  Consumer tests           tests/contract/consumer/   [FOUND | NONE]
  Provider tests           tests/contract/provider/   [FOUND | NONE]
  Pact Broker              CI configuration           [CONFIGURED | OPTIONAL]
  can-i-deploy             CI gate                    [CONFIGURED | OPTIONAL]

OpenAPI Validation:
  OpenAPI spec             openapi.yaml               [EXISTS | MISSING]
  Spec version             OpenAPI 3.1                [CURRENT | OUTDATED]
  Request validation       middleware                 [CONFIGURED | MISSING]
  Response validation      test helpers               [CONFIGURED | MISSING]
  Breaking change CI       oasdiff                    [CONFIGURED | OPTIONAL]

Schema Testing:
  JSON Schemas             schemas/                   [EXISTS | N/A]
  Schema validator         ajv/zod                    [INSTALLED | MISSING]
  Response validation      test helpers               [CONFIGURED | MISSING]

Overall: [X issues found]

Recommendations:
  - Add Pact consumer tests for service dependencies
  - Configure OpenAPI response validation in tests
  - Add breaking change detection to CI

如果使用 --check-only，请在此停止。

步骤 4：配置 API 测试（如果使用 --fix 或用户确认）

根据检测到的项目类型应用修复。使用 REFERENCE.md 中的模板来执行：

1. Pact 契约测试 - 安装依赖项并创建消费者/提供者测试文件
2. OpenAPI 验证 - 安装验证器并创建测试辅助工具
3. 使用 Zod 进行架构测试 - 安装 Zod 并创建架构定义
4. 破坏性变更检测 - 安装 oasdiff 并添加 CI 检查

对于 JavaScript/TypeScript 项目，使用 bun add --dev 安装。对于 Python，使用 uv add --group dev 安装。

步骤 5：配置 CI/CD 集成

创建 .github/workflows/api-tests.yml，并在其中配置以下任务：

• 消费者契约测试
• 提供者验证（如有需要，使用服务容器）
• OpenAPI 规范验证
• 在 PR 上检测破坏性变更

在 package.json 中添加 npm/bun 脚本，以便在本地进行测试。使用 REFERENCE.md 中的工作流模板。

步骤 6：更新标准跟踪

更新 .project-standards.yaml：

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  api_tests: "2025.1"
  api_tests_contract: "[pact|none]"
  api_tests_openapi: true
  api_tests_schema: "[zod|ajv|none]"
  api_tests_breaking_change_ci: true

步骤 7：打印最终报告

打印所有已应用更改、添加的脚本，以及用户验证配置的后续步骤摘要。

详细模板和代码示例请参阅 REFERENCE.md。

Agent 式优化

场景	命令
快速合规性检查	/configure:api-tests --check-only
自动修复所有问题	/configure:api-tests --fix
仅 Pact 契约	/configure:api-tests --fix --type pact
仅验证 OpenAPI	/configure:api-tests --fix --type openapi
仅测试 Schema	/configure:api-tests --fix --type schema

标志

标志	说明
--check-only	报告状态，但不提供修复方案
--fix	无需提示，自动应用所有修复
--type <type>	聚焦于特定类型（pact、openapi、schema）

示例

# Check compliance and offer fixes
/configure:api-tests

# Check only, no modifications
/configure:api-tests --check-only

# Auto-fix all issues
/configure:api-tests --fix

# Configure Pact only
/configure:api-tests --fix --type pact

# Configure OpenAPI validation only
/configure:api-tests --fix --type openapi

错误处理

• 未找到 OpenAPI 规范：提供创建模板的选项
• Pact 版本不匹配：建议升级方案
• Schema 验证失败：报告具体错误
• 未配置 Pact Broker：提供设置说明

另请参阅

• /configure:tests - 单元测试配置
• /configure:integration-tests - 集成测试
• /configure:all - 运行所有合规性检查
• Pact 文档：https://docs.pact.io
• OpenAPI 规范：https://swagger.io/specification
• Zod 文档：https://zod.dev