Contract Test Validator

Overview

Validate API contracts between services using consumer-driven contract testing to prevent breaking changes in microservice architectures. Supports Pact (the industry standard for CDC testing), Spring Cloud Contract (JVM), and OpenAPI-diff for specification comparison.

Prerequisites

• Contract testing framework installed (Pact JS/Python/JVM, or Spring Cloud Contract)
• Pact Broker running (or PactFlow SaaS) for contract storage and verification
• Consumer and provider services with clearly defined API boundaries
• Existing integration points documented (which consumers call which provider endpoints)
• CI pipeline configured for both consumer and provider repositories

Instructions

1. Identify consumer-provider relationships in the system:

• Map which services call which APIs (e.g., Frontend calls User API, Order API calls Payment API).
• Document each interaction: HTTP method, path, headers, request body, expected response.
• Prioritize contracts for the most critical and frequently changing integrations.

1. Write consumer-side contract tests (Pact consumer tests):

• Define the expected interaction: method, path, query parameters, headers, request body.
• Specify the expected response: status code, headers, and response body structure.
• Use matchers for flexible assertions (like(), eachLike(), term()) instead of exact values.
• Generate a Pact file (JSON contract) from the consumer test.

1. Publish consumer contracts to the Pact Broker:

• Run pact-broker publish with the consumer version and branch/tag.
• Enable webhooks to trigger provider verification when new contracts are published.
• Configure can-i-deploy checks in CI to gate deployments.

1. Write provider-side verification tests:

• Configure the Pact verifier to fetch contracts from the Pact Broker.
• Set up provider states (test data scenarios matching consumer expectations).
• Run verification against the actual provider implementation.
• Publish verification results back to the Pact Broker.

1. Handle contract evolution:

• Adding new fields: Safe -- consumers using matchers will not break.
• Removing fields: Breaking -- coordinate with all consumers before removal.
• Changing field types: Breaking -- requires consumer updates first.
• Use can-i-deploy to check compatibility before releasing either side.

1. For schema-based validation (non-Pact):

• Compare OpenAPI spec versions using openapi-diff to detect breaking changes.
• Flag removed endpoints, changed parameter types, and narrowed response schema