Prompt file imported from cdalsoniii/brightpath-coder (.cursor/commands/api-contract-test.md). Copyright stays with the author.

API Contract Test

Overview

Validate API contracts between producer and consumer services.

Steps

1. Identify API contracts

   • Extract request schemas from consumer code or specifications
   • Extract response schemas expected by consumers
   • Document all contract requirements (headers, query params, body structure)
   • Map contracts to specific API endpoints and operations
   • Create contract definitions in Pact or similar tool format

2. Implement consumer-driven contract tests

   • Write consumer contract tests using Pact or similar framework
   • Define expected request format (method, path, headers, body)
   • Define expected response format (status code, headers, body schema)
   • Generate contract files (Pact JSON files) from consumer tests
   • Include edge cases and error scenarios in contracts

3. Run contract tests against producer

   • Execute consumer contract tests against producer service
   • Verify producer matches consumer expectations (request/response)
   • Run provider verification tests using generated contract files
   • Validate all contract scenarios pass against producer implementation
   • Document any contract mismatches or failures

4. Verify backward compatibility for all consumers

   • Run all consumer contracts against current producer version
   • Test that existing consumers are not broken by producer changes
   • Verify new producer changes don't violate existing contracts
   • Check that deprecated fields still work for older consumers
   • Ensure all consumer versions are supported

5. Integrate contract testing into CI pipeline

   • Add contract test execution to CI/CD pipeline
   • Configure contract tests to run on producer changes
   • Set up contract publishing to shared contract repository
   • Implement contract verification as a required CI check
   • Add contract test results to deployment gates

Checklist

• API contracts are identified and documented (request/response schemas)
• Consumer-driven contract tests are implemented (Pact or similar)
• Contract tests run successfully against producer service
• Backward compatibility is verified for all consumers
• Contract testing is integrated into CI pipeline
• Contract mismatches are detected and resolved before deployment
• Contract repository is maintained and accessible to all teams

References

• Rules:
  • .cursor/rules/028-contract-testing.mdc
  • .cursor/rules/api-design-standards.mdc
• Plans:
  • .cursor/plans/api_design_versioning_strategy.plan.md
• Agents:
  • .cursor/agents/api-design-specialist.md