api-tests

/configure:api-tests

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

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他方法……
设置 API 契约测试（Pact、OpenAPI、架构）	运行现有 API 测试（直接使用 bun test 或测试运行器）
验证是否符合 OpenAPI 规范	编辑 OpenAPI 规范内容（直接使用编辑器）
在 CI 中添加破坏性变更检测	常规 CI 工作流设置（使用 /configure:workflows）
检查 API 测试基础设施状态	单元或集成测试设置（使用 /configure:tests 或 /configure:integration-tests）
配置 Pact 消费者/提供者工作流	调试特定 API 端点故障（使用带详细输出的测试运行器）

上下文

• 锁文件：!find . -maxdepth 1 \( -name 'bun.lockb' -o -name 'bun.lock' -o -name 'package-lock.json' -o -name 'yarn.lock' \)
• 项目文件：!find . -maxdepth 1 \( -name 'tsconfig.json' -o -name 'pyproject.toml' -o -name 'package.json' \)
• 已安装 Pact：!find . -maxdepth 1 \( -name package.json -o -name 'requirements*.txt' -o -name pyproject.toml \) -exec grep -l "pact-foundation/pact\|pact-python" {} +
• OpenAPI 规范：!find . -maxdepth 2 \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' -o -name 'swagger.json' -o -name 'swagger.yaml' \)
• 架构验证器：!find . -maxdepth 1 -name 'package.json' -exec grep -l '"ajv"\|"zod"' {} +
• OpenAPI 验证库：!find . -maxdepth 1 -name 'package.json' -exec grep -l "swagger-parser\|@apidevtools" {} +
• Pact 契约目录：!find . -maxdepth 1 -type d -name \'pacts\'
• 契约测试：!find . -maxdepth 3 -type d -name 'contract'
• API 测试文件：!find . -maxdepth 4 \( -name '*.pact.*' -o -name '*.openapi.*' -o -name '*.contract.*' \)
• CI 工作流：!find . -path '*/.github/workflows/*' -maxdepth 3 \( -name '*api*' -o -name '*contract*' -o -name '*pact*' \)

参数

解析 $ARGUMENTS 中的以下标志：

标志	说明	默认值
--check-only	仅报告状态，不进行更改	关闭
--fix	自动应用所有修复，不提示	关闭
--type <type>	聚焦于特定类型：pact、openapi 或 schema	所有类型

API 测试类型：

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

执行

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

第 1 步：检测项目基础设施

扫描项目，查找现有 API 测试标识：

标识	组件	检查内容
依赖中包含 pact	Pact 契约测试	package.json 或 pyproject.toml
openapi.yaml 或 swagger.json	OpenAPI 规范	根目录或 docs/ 目录
@apidevtools/swagger-parser	OpenAPI 验证	package.json 的 devDependencies
依赖中包含 ajv 或 zod	架构验证	package.json dependencies
pacts/ 目录	Pact 契约	项目根目录

如果指定了 --type，则仅检查相关组件。

第 2 步：分析当前状态

检查各 API 测试组件是否完整：

契约测试（Pact）：

1. 检查是否已安装 @pact-foundation/pact（JS/TS）或 pact-python（Python）
2. 查找 tests/contract/consumer/ 中的消费者测试
3. 查找 tests/contract/provider/ 中的提供者验证
4. 检查 CI 文件中的 Pact Broker 配置
5. 检查是否设置了 can-i-deploy CI 门禁

OpenAPI 验证：

1. 验证 OpenAPI 规范文件是否存在且有效
2. 检查是否有请求验证中间件
3. 检查测试中的响应验证
4. 查找破坏性变更检测（oasdiff）

Schema 测试：

1. 检查是否有 JSON Schema 或 Zod 定义
2. 验证是否已安装校验器（ajv 或 zod）
3. 查找响应验证测试辅助工具

第 3 步：生成合规报告

打印格式化的合规报告：

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

Contract Testing (Pact):
  Package:                   [INSTALLED | MISSING]
  Consumer tests:            [FOUND | NONE]
  Provider tests:            [FOUND | NONE]
  Pact Broker:               [CONFIGURED | OPTIONAL]

OpenAPI Validation:
  OpenAPI spec:              [EXISTS | MISSING]
  Spec version:              [CURRENT | OUTDATED]
  Request validation:        [CONFIGURED | MISSING]
  Response validation:       [CONFIGURED | MISSING]
  Breaking change CI:        [CONFIGURED | OPTIONAL]

Schema Testing:
  JSON Schemas:              [EXISTS | N/A]
  Schema validator:          [INSTALLED | MISSING]
  Response validation:       [CONFIGURED | MISSING]

Overall: [X issues found]
Recommendations: [list specific actions]

如果设置了 --check-only，则在此处停止。

第 4 步：应用配置

如果设置了 --fix 或用户确认，则为缺失的组件应用修复。使用 Context 中检测到的项目语言来选择 TypeScript 或 Python 模板。

对于每个缺失的组件，使用 REFERENCE.md 中的模板创建相应文件：

1. Pact 契约测试：安装依赖，创建消费者测试模板，创建提供者验证模板
2. OpenAPI 验证：安装验证库，创建 OpenAPI 校验器辅助工具，创建合规测试
3. Schema 测试（Zod）：安装 Zod，创建 Schema 定义，创建 Schema 验证测试
4. OpenAPI 破坏性变更检测：安装 oasdiff，添加 CI 步骤

第 5 步：配置 CI/CD 集成

创建或更新 .github/workflows/api-tests.yml，添加以下任务：

1. 消费者契约测试
2. 提供者验证（如有需要，配置数据库服务）
3. OpenAPI 规范验证和破坏性变更检测
4. Pact 工件发布（仅限主分支）

在 package.json 中添加测试脚本。使用 REFERENCE.md 中的 CI 工作流模板。

第 6 步：更新标准跟踪

使用 API 测试配置更新 .project-standards.yaml：

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 步：生成最终报告

打印所有已应用更改的摘要，包括：

• 创建的配置文件
• 已安装的依赖项
• 可用的测试命令（包含准确的 bun run / npm run 命令）
• 已配置的 CI/CD 任务
• 建议的后续验证步骤

Agentic 优化

场景	命令
快速检查状态	/configure:api-tests --check-only
自动修复所有问题	/configure:api-tests --fix
仅设置 Pact	/configure:api-tests --fix --type pact
仅设置 OpenAPI	/configure:api-tests --fix --type openapi
检查是否存在 OpenAPI 规范	find . -maxdepth 2 \( -name 'openapi.yaml' -o -name 'swagger.json' \) 2>/dev/null
检查是否已安装 Pact	grep -l "pact-foundation" package.json 2>/dev/null

示例

# 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 文档
• OpenAPI 规范
• Zod 文档