/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

configure-api-tests