/configure:api-tests Skill

/configure:api-tests

Check and configure API contract testing infrastructure for validating API contracts, schemas, and consumer-provider agreements.

When to Use This Skill

| Use this skill when... | Use another approach when... | |------------------------|------------------------------| | Setting up Pact consumer/provider contract tests | Writing individual unit tests (/configure:tests) | | Configuring OpenAPI request/response validation | Validating a single API endpoint manually | | Adding JSON Schema or Zod schema testing | Checking general test coverage (/configure:coverage) | | Detecting breaking API changes in CI | Reviewing API design decisions (code-review agent) | | Auditing API testing compliance across a project | Configuring general CI/CD workflows (/configure:workflows) |

Context

Project root: !pwd
Package files: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' \)
Pact deps: !find . -maxdepth 1 \( -name package.json -o -name pyproject.toml \) -exec grep -l 'pact' {} +
OpenAPI spec: !find . -maxdepth 1 \( -name 'openapi.yaml' -o -name 'openapi.json' -o -name 'swagger.json' \)
Pact dir: !find . -maxdepth 1 -type d -name 'pacts'
Contract tests: !find tests -maxdepth 2 -type d -name 'contract'
Project standards: !find . -maxdepth 1 -name '.project-standards.yaml'

Parameters

Parse from command arguments:

--check-only: Report compliance status without modifications (CI/CD mode)
--fix: Apply fixes automatically without prompting
--type <pact|openapi|schema>: Focus on specific type

API Testing Types:

| Type | Use Case | |------|----------| | Pact | Microservices, multiple consumers, breaking change detection | | OpenAPI | API-first development, documentation-driven testing | | Schema | Simple validation, GraphQL APIs, single service |

Execution

Execute this API testing compliance check:

Step 1: Detect existing API testing infrastructure

Check for these indicators:

| Indicator | Component | Status | |-----------|-----------|--------| | pact in dependencies | Pact contract testing | Installed | | openapi.yaml or swagger.json | OpenAPI specification | Present | | @apidevtools/swagger-parser | OpenAPI validation | Configured | | ajv in dependencies | JSON Schema validation | Configured | | pacts/ directory | Pact contracts | Present |

Step 2: Analyze current state

For each detected component, check completeness:

Contract Testing (Pact):

[ ] @pact-foundation/pact installed (JS) or pact-python (Python)
[ ] Consumer tests defined
[ ] Provider verification configured
[ ] Pact Broker or PactFlow configured (optional)
[ ] CI/CD pipeline integration

OpenAPI Validation:

[ ] OpenAPI specification file exists
[ ] Request validation middleware configured
[ ] Response validation in tests
[ ] Schema auto-generation configured
[ ] Breaking change detection

Schema Testing:

[ ] JSON Schema definitions exist
[ ] ajv or similar validator installed
[ ] Response validation helpers
[ ] Schema versioning strategy

Step 3: Generate compliance report

Print a formatted compliance report:

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

If --check-only, stop here.

Step 4: Configure API testing (if --fix or user confirms)

Apply fixes based on detected project type. Use templates from REFERENCE.md for:

Pact Contract Testing - Install dependencies and create consumer/provider test files
OpenAPI Validation - Install validator and create test helpers
Schema Testing with Zod - Install Zod and create schema definitions
Breaking Change Detection - Install oasdiff and add CI check

For JavaScript/TypeScript projects, install with bun add --dev. For Python, install with uv add --group dev.

Step 5: Configure CI/CD integration

Create .github/workflows/api-tests.yml with jobs for:

Consumer contract tests
Provider verification (with service containers if needed)
OpenAPI spec validation
Breaking change detection on PRs

Add npm/bun scripts to package.json for local testing. Use workflow templates from REFERENCE.md.

Step 6: Update standards tracking

Update .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

Step 7: Print final report

Print a summary of all changes applied, scripts added, and next steps for the user to verify the configuration.

For detailed templates and code examples, see REFERENCE.md.

Agentic Optimizations

| Context | Command | |---------|---------| | Quick compliance check | /configure:api-tests --check-only | | Auto-fix all issues | /configure:api-tests --fix | | Pact contracts only | /configure:api-tests --fix --type pact | | OpenAPI validation only | /configure:api-tests --fix --type openapi | | Schema testing only | /configure:api-tests --fix --type schema |

Flags

| Flag | Description | |------|-------------| | --check-only | Report status without offering fixes | | --fix | Apply all fixes automatically without prompting | | --type <type> | Focus on specific type (pact, openapi, schema) |

Examples

# 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

Error Handling

No OpenAPI spec found: Offer to create template
Pact version mismatch: Suggest upgrade path
Schema validation fails: Report specific errors
Pact Broker not configured: Provide setup instructions

Agent Skills: /configure:api-tests

Install this agent skill to your local

Skill Files