api-contract-tester

name	api-contract-tester
description	Generate and execute API contract tests from OpenAPI/Swagger specs. Use when the user wants contract tests or schema validation for an API.

API Contract Tester

Generate and execute API contract tests from OpenAPI/Swagger specifications.

Description

This skill reads OpenAPI/Swagger specifications (YAML or JSON) and generates comprehensive contract test scripts. It validates that API implementations match their documented contracts, detecting breaking changes and schema violations.

Instructions

When the user provides an API specification or endpoint details:

1. Parse Specification: Extract endpoints, methods, request/response schemas, and status codes
2. Generate Contract Tests: For each endpoint, create tests that validate:
   • Response status codes match specification
   • Response body matches defined schema (required fields, types, formats)
   • Request validation (required params, body schema)
   • Header requirements (Content-Type, Authorization)
   • Error response formats
3. Output Executable Scripts: Generate test scripts in the user's preferred format:
   • Shell scripts using curl + jq (default, zero dependencies)
   • Python using requests + jsonschema
   • JavaScript using fetch or axios
4. Include Assertions: Each test includes clear pass/fail assertions

Generated Test Structure

#!/bin/bash
# Contract Tests for [API Name]
# Generated by Claude QA Toolkit

BASE_URL="${BASE_URL:-https://api.example.com}"
PASS=0
FAIL=0

# Test: GET /endpoint returns correct schema
test_get_endpoint() {
  response=$(curl -s -w "\n%{http_code}" "$BASE_URL/endpoint")
  status=$(echo "$response" | tail -1)
  body=$(echo "$response" | sed '$d')

  # Assert status code
  if [ "$status" -eq 200 ]; then
    echo "PASS: GET /endpoint returns 200"
    ((PASS++))
  else
    echo "FAIL: GET /endpoint expected 200, got $status"
    ((FAIL++))
  fi

  # Assert required fields exist
  if echo "$body" | jq -e '.id, .name, .email' > /dev/null 2>&1; then
    echo "PASS: Response contains required fields"
    ((PASS++))
  else
    echo "FAIL: Response missing required fields"
    ((FAIL++))
  fi
}

# Run all tests
test_get_endpoint

echo "Results: $PASS passed, $FAIL failed"

Test Categories Generated

Schema Validation

• Required fields present in response
• Data types match specification
• Enum values are within allowed set
• Nullable fields handled correctly
• Array items match item schema

Status Code Validation

• Success codes (200, 201, 204) for valid requests
• Client error codes (400, 401, 403, 404) for invalid requests
• Proper error response body format

Header Validation

• Content-Type matches specification
• CORS headers present if specified
• Pagination headers for list endpoints
• Rate limit headers

Breaking Change Detection

• New required fields in requests
• Removed fields from responses
• Changed data types
• Modified enum values
• URL structure changes

Example Usage

Generate contract tests for this OpenAPI spec: [paste spec]
Use curl/bash scripts so the team doesn't need extra dependencies.

Compare these two API versions and generate tests that catch breaking changes:
V1: [spec]  V2: [spec]