contract-tester

Name: contract-tester
Author: vladm3105

github.com/vladm3105测试与质量1754 次安装1 天前更新

代码仓库

关于 contract-tester

contract-tester 面向需要验证 API 契约及提供方与消费者兼容性的团队，可检查契约文档、发现破坏性变更，并支持模拟服务与契约测试。

主要功能

01CTR YAML 架构验证
02OpenAPI、AsyncAPI、JSON Schema 与 GraphQL 检查
03版本兼容性与破坏性变更检测
04生成模拟 API 服务
05消费者驱动的契约测试
06生成 API 文档

适用场景

01部署前验证契约文档
02检查 API 变更的兼容性
03使用模拟 API 测试消费者
04依据契约验证提供方实现

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill contract-tester

安装后在 Claude Code 中输入/contract-tester确认已加载。

详细介绍

contract-tester

描述：API 契约验证、破坏性变更检测和消费者驱动的契约测试

类别：API 质量保证

复杂度：中高（架构验证 + 契约兼容性）

用途

根据 CTR（契约）文档验证 API 实现，检测破坏性变更，并确保提供方与消费者兼容。在部署前防止违反 API 契约。

功能

1. CTR YAML 架构验证

根据架构验证 YAML 结构
检查必填字段是否完整
验证数据类型是否正确
验证枚举值
检查格式规范（电子邮件、URL、UUID）

2. OpenAPI/AsyncAPI 合规性

将 CTR 转换为 OpenAPI 3.0/3.1 规范
根据 OpenAPI 架构进行验证
对事件驱动型 API 进行 AsyncAPI 验证
JSON Schema 验证
GraphQL 架构验证

3. 契约版本控制

语义化版本验证（MAJOR.MINOR.PATCH）
版本兼容性检查
弃用警告
迁移路径验证

4. 破坏性变更检测

已删除的端点/操作
已更改的请求/响应架构
已删除的必填字段
已更改的字段类型
更严格的验证规则
已更改的身份验证要求

5. Mock 服务生成

根据 CTR 生成 Mock API 服务
生成逼真的响应
可配置的响应延迟
错误场景模拟
有状态 API 的状态管理

6. 消费者驱动的契约测试

Pact 契约测试
提供方验证
消费者契约生成
双向契约测试
契约演进跟踪

7. 契约兼容性矩阵

提供方版本兼容性
消费者版本支持
弃用时间线跟踪
迁移要求

8. API 文档生成

根据 CTR 生成 API 文档
交互式 API 浏览器
多种语言的代码示例
身份验证指南

契约测试工作流

graph TD
    A[CTR Document] --> B[Parse YAML]
    B --> C{Valid YAML?}
    C -->|No| D[Report Parse Error]
    C -->|Yes| E[Schema Validation]

    E --> F{Schema Valid?}
    F -->|No| G[Report Schema Errors]
    F -->|Yes| H[Version Check]

    H --> I{Version Valid?}
    I -->|No| J[Report Version Error]
    I -->|Yes| K[Breaking Change Detection]

    K --> L{Previous Version Exists?}
    L -->|No| M[First Version]
    L -->|Yes| N[Compare Versions]

    N --> O{Breaking Changes?}
    O -->|Yes| P[Report Breaking Changes]
    O -->|No| Q[Compatible Change]

    M --> R[Generate Mock Server]
    Q --> R
    P --> R

    R --> S[Run Contract Tests]
    S --> T{Tests Pass?}
    T -->|No| U[Report Test Failures]
    T -->|Yes| V[Generate Documentation]

    V --> W[Validation Complete]

    D --> W
    G --> W
    J --> W
    U --> W

使用说明

验证 CTR 文档

contract-tester validate --file ctrs/CTR-USER-V1.yaml

输出：

=== Contract Validation Report: CTR-USER-V1 ===

Status: PASS

Schema Validation: ✓
- Service name: user-service
- Version: 1.0.0
- Protocol: REST
- Endpoints: 5
- Models: 3

OpenAPI Compliance: ✓
- Valid OpenAPI 3.1 specification
- All schemas properly defined
- Authentication specified (Bearer JWT)

Version Check: ✓
- Semantic versioning: 1.0.0
- No previous version (initial release)

Breaking Changes: N/A (initial release)

Warnings (1):
- Endpoint DELETE /users/{id} lacks rate limiting specification
  → Recommendation: Add rate limiting to prevent abuse

Summary: Contract is valid and ready for implementation

检测破坏性变更

contract-tester diff \
  --previous ctrs/CTR-USER-V1.yaml \
  --current ctrs/CTR-USER-V2.yaml

输出：

=== Breaking Change Analysis: V1 → V2 ===

BREAKING CHANGES (3):

1. [CRITICAL] Removed endpoint
   - DELETE /users/{id}
   - Impact: Consumers using this endpoint will fail
   - Migration: Use DELETE /users/{id}/deactivate instead

2. [CRITICAL] Changed response type
   - Endpoint: GET /users/{id}
   - Field: created_at
   - V1: string (format: date-time)
   - V2: integer (unix timestamp)
   - Impact: Date parsing will fail in consumers
   - Migration: Update consumers to handle unix timestamp

3. [MAJOR] Added required field
   - Endpoint: POST /users
   - Field: email_verified (boolean, required)
   - Impact: Existing POST requests missing this field will fail
   - Migration: Update all POST requests to include email_verified

NON-BREAKING CHANGES (2):

1. [MINOR] Added optional field
   - Endpoint: GET /users/{id}
   - Field: last_login (string, optional)
   - Impact: None (backward compatible)

2. [PATCH] Fixed typo in description
   - Model: User
   - Field: username
   - Impact: Documentation only

RECOMMENDATION: Version should be 2.0.0 (MAJOR bump due to breaking changes)
Current version: 1.1.0 ❌
Suggested version: 2.0.0 ✓

生成 Mock 服务

contract-tester mock \
  --file ctrs/CTR-USER-V1.yaml \
  --port 8080 \
  --response-delay 100ms

Mock 服务功能：

根据架构生成逼真的数据
可配置的响应延迟
注入错误场景
请求验证
响应日志记录

# Test against mock server
curl http://localhost:8080/api/users/123

# Response
{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "username": "john_doe",
  "email": "[email protected]",
  "created_at": "2025-01-15T10:30:00Z",
  "status": "active"
}

运行消费者契约测试

contract-tester test-consumer \
  --contract ctrs/CTR-USER-V1.yaml \
  --consumer user-frontend \
  --provider user-service \
  --output reports/contract-tests/

生成的 Pact 测试：

import pytest
from pact import Consumer, Provider, Like, EachLike, Term

@pytest.fixture
def pact():
    return Consumer('user-frontend').has_pact_with(
        Provider('user-service'),
        pact_dir='./pacts'
    )

def test_get_user_contract(pact):
    """Verify GET /users/{id} contract"""
    expected_response = {
        'user_id': Like('123e4567-e89b-12d3-a456-426614174000'),
        'username': Like('john_doe'),
        'email': Term(r'.+@.+\..+', '[email protected]'),
        'created_at': Like('2025-01-15T10:30:00Z'),
        'status': Term(r'active|inactive|suspended', 'active')
    }

    (pact
     .given('user with id 123 exists')
     .upon_receiving('a request for user 123')
     .with_request('GET', '/api/users/123')
     .will_respond_with(200, body=expected_response))

    with pact:
        result = user_api.get_user('123')
        assert result.status_code == 200
        assert 'user_id' in result.json()

验证提供方实现

contract-tester test-provider \
  --contract ctrs/CTR-USER-V1.yaml \
  --provider-url http://localhost:8000 \
  --output reports/provider-verification/

CTR 文档结构

完整 CTR 示例

# ctrs/CTR-USER-V1.yaml
contract_id: CTR-USER-V1
version: 1.0.0
service_name: user-service
protocol: REST
base_path: /api

metadata:
  description: User management API contract
  owner: backend-team
  consumers:
    - user-frontend
    - admin-dashboard
  traceability:
    requirements:
      - REQ-USER-001
      - REQ-USER-002
    specifications:
      - SPEC-API-V1

authentication:
  type: bearer
  scheme: JWT
  token_location: header
  header_name: Authorization

endpoints:
  - operation_id: get_user
    method: GET
    path: /users/{id}
    summary: Retrieve user by ID
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      200:
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      404:
        description: User not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
      401:
        description: Unauthorized
    rate_limit:
      requests: 100
      window: 60s

  - operation_id: create_user
    method: POST
    path: /users
    summary: Create new user
    request_body:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateUserRequest'
    responses:
      201:
        description: User created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      400:
        description: Invalid request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
      409:
        description: User already exists

  - operation_id: update_user
    method: PUT
    path: /users/{id}
    summary: Update user
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    request_body:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateUserRequest'
    responses:
      200:
        description: User updated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      404:
        description: User not found

  - operation_id: delete_user
    method: DELETE
    path: /users/{id}
    summary: Delete user
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    responses:
      204:
        description: User deleted
      404:
        description: User not found

  - operation_id: list_users
    method: GET
    path: /users
    summary: List all users
    parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
    responses:
      200:
        description: User list
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: array
                  items:
                    $ref: '#/components/schemas/User'
                pagination:
                  $ref: '#/components/schemas/Pagination'

components:
  schemas:
    User:
      type: object
      required:
        - user_id
        - username
        - email
        - created_at
        - status
      properties:
        user_id:
          type: string
          format: uuid
          description: Unique user identifier
        username:
          type: string
          minLength: 3
          maxLength: 20
          pattern: '^[a-zA-Z0-9_]+$'
          description: Unique username
        email:
          type: string
          format: email
          description: User email address
        full_name:
          type: string
          maxLength: 100
          description: User's full name
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        status:
          type: string
          enum: [active, inactive, suspended]
          description: Account status

    CreateUserRequest:
      type: object
      required:
        - username
        - email
        - password
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 20
          pattern: '^[a-zA-Z0-9_]+$'
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
          maxLength: 128
        full_name:
          type: string
          maxLength: 100

    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        full_name:
          type: string
          maxLength: 100
        status:
          type: string
          enum: [active, inactive, suspended]

    Error:
      type: object
      required:
        - error_code
        - message
      properties:
        error_code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details

    Pagination:
      type: object
      required:
        - page
        - limit
        - total
      properties:
        page:
          type: integer
          description: Current page number
        limit:
          type: integer
          description: Items per page
        total:
          type: integer
          description: Total number of items
        has_next:
          type: boolean
          description: Whether there are more pages

破坏性变更规则

MAJOR 版本变更（X.0.0）

已删除的端点

# V1
DELETE /users/{id}

# V2 (BREAKING)
# Endpoint removed

已删除的必填字段

# V1
required: [username, email, password]

# V2 (BREAKING)
required: [username, email]  # password removed

已更改的字段类型

# V1
user_id:
  type: string

# V2 (BREAKING)
user_id:
  type: integer

更严格的验证

# V1
username:
  type: string

# V2 (BREAKING)
username:
  type: string
  pattern: '^[a-zA-Z0-9_]+$'  # New constraint

已更改的身份验证

# V1
authentication:
  type: basic

# V2 (BREAKING)
authentication:
  type: bearer
  scheme: JWT

MINOR 版本变更（x.Y.0）

新增端点

# V1.0.0
GET /users

# V1.1.0 (Non-breaking)
GET /users
GET /users/search  # New endpoint

新增可选字段

# V1.0.0
properties:
  username: ...

# V1.1.0 (Non-breaking)
properties:
  username: ...
  nickname: ...  # New optional field

放宽验证

# V1.0.0
username:
  minLength: 5

# V1.1.0 (Non-breaking)
username:
  minLength: 3  # Less strict

PATCH 版本变更（x.y.Z）

文档更新
描述中的错误修正
拼写错误修正
示例更新

契约兼容性矩阵

Provider Version Compatibility:

V1.0.0 consumers can use:
- V1.0.0, V1.0.1, V1.1.0, V1.2.0 providers ✓
- V2.0.0 providers ❌ (breaking changes)

V1.1.0 consumers can use:
- V1.1.0, V1.1.1, V1.2.0 providers ✓
- V1.0.0 providers ⚠️ (missing optional features)
- V2.0.0 providers ❌ (breaking changes)

V2.0.0 consumers can use:
- V2.0.0, V2.0.1, V2.1.0 providers ✓
- V1.x.x providers ❌ (incompatible)

工具访问权限

所需工具：

Read：读取 CTR YAML 文件
Write：生成测试文件和文档
Bash：执行验证和测试工具
Grep：搜索契约模式

所需库：

pyyaml：YAML 解析
jsonschema：架构验证
openapi-spec-validator：OpenAPI 验证
pact-python：消费者驱动的契约测试
faker：Mock 数据生成

集成点

与 doc-flow 集成

在生成过程中验证 CTR 文档
确保可追溯至需求
在契约变更时更新文档

与 test-automation 集成

自动生成契约测试
集成到测试套件中
跟踪契约测试覆盖率

与 code-review 集成

根据契约验证 API 实现
检测代码中的契约违规
建议符合契约的修复方案

使用 devops-flow

在 CI/CD 流水线中验证契约
阻止包含破坏性变更的部署
生成 API 网关配置

最佳实践

语义化版本控制：严格遵循 MAJOR.MINOR.PATCH
向后兼容性：优先采用增量式变更
弃用通知：在移除功能前发出警告
使用方反馈：让使用方参与契约变更
文档：为破坏性变更提供清晰的迁移指南
测试：在发布前测试所有契约变更
版本策略：至少支持 N-1 个版本
变更日志：维护完整的契约变更日志

成功标准

契约验证覆盖率达到 100%
未检测到的破坏性变更为零
契约验证时间少于 5 分钟
同一 MAJOR 版本中，使用方与提供方的兼容性达到 100%
所有破坏性变更均附有迁移路径文档
所有契约均提供模拟服务
所有 CTR 文档均包含完整的文档控制部分，包括：
- 项目元数据（名称、版本、日期、负责人、编制者、状态）
- 记录所有契约变更的文档修订历史表

说明

契约测试会在部署前于 CI/CD 中运行
破坏性变更需要提升 MAJOR 版本号
提供方必须在 MAJOR 版本内保持向后兼容性
使用方应能妥善处理次要版本差异
契约变更会自动通知使用方

支持 Markdown

登录后评论

基本信息

作者: vladm3105
仓库: vladm3105/aidoc-flow-framework
分类: 测试与质量
安装次数: 54
GitHub Stars: 17

报告问题