Contract Testing

What is Contract Testing in API-Driven Development?

Ensuring the reliability of applications is core to their usability and functionality. This has led to the development of various testing methodologies, one of them being contract testing. This approach calls for verifying and validating inter-system communication in order to confirm that the interactions between different applications or services fulfill certain pre-defined expectations or contracts. 

In the context of rapidly growing microservices architectures and escalating reliance on APIs, contract testing is a central tool to ensure that these services seamlessly interact with one another to avoid potential disruptions or errors.

What is Contract Testing?

Contract testing is a verification technique that confirms whether the interactions between different software systems are working as expected. It does this by defining a contract -- a set of rules that describe the requests and responses that an application's API will provide. By checking the contract, developers can ensure that their application will communicate correctly with other applications or services. 

When Would You Use Contract Testing? An Example

Contract testing is especially useful in service-oriented architecture, where individual microservices constantly interact. These independent systems often communicate via APIs, which is why it's critical to enforce a specific protocol of interaction to avoid service disruptions. Contract testing validates this inter-service interaction.

For example, assume we have two services in a web architecture: an account service (Service A) and a user service (Service B). Service A sends HTTP requests to Service B's API endpoint, specifically a GET request to "/users/{id}", expecting user details in a pre-defined JSON format:


    "id": 1,

    "name": "John Doe",

    "email": ""


In contract testing, developers write tests to ensure Service B's API always adheres to the contracted response format. If Service B alters its endpoint structure or the JSON payload without honoring the contract, the change could break Service A — the contract test captures this.

Through creating established contracts and conducting contract testing, microservices can efficiently interact without causing unexpected failures due to changes in APIs or services not aligned with the agreed 'contract'. Essentially, the protocol defined by these contracts is verified by the tests to preserve system integrity and prevent unexpected communication errors or service outages caused by underlying service modifications.

Is Contract Testing vs API Testing vs Integration Testing

Contract testing, API testing, and integration testing are all used to test how different software components interact and work together, but they are not entirely the same. 

  • API testing primarily focuses on assessing whether the APIs in a software work correctly, primarily by running tests on API requests and examining the responses. It targets the direct functionality of the API, such as whether it returns accurate data, handles errors correctly, and responds within expected timeframes. 
  • Contract testing is a subset of API testing. It verifies that different services or applications are effectively communicating with each other as defined in their contract. It ensures that the requests sent and responses received between these systems align with the agreed-upon specifications.  Therefore, while contract testing involves API testing to some extent, it is targeted at the integration point and how the API integrates with other applications or services.
  • Integration testing is a type of testing where individual software modules are combined and tested as a group. In this testing phase, the emphasis is on the coordination and communication between these modules. For instance, it might involve testing whether the database properly stores data when a request is sent from the front-end user interface. Contract testing emphasizes the validation of interactions based on agreed-upon contracts, while integration testing looks at the broader picture of whether or not the components work together as intended.

Using Mock APIs in Contract Testing

While contract testing ensures that inter-service interactions adhere to a specific 'contract', there can be scenarios when certain APIs that are integral to the testing process are not yet developed or are still evolving. In these cases, using mock APIs can be very helpfull.

Mock APIs simulate the behavior of a real API and are used to mimic their responses without requiring any actual back-end process. They can allow different teams to adhere to a contract, even when there are missing steps in the implementation of the API. 

(By the way, WireMock Cloud allows developers to create robust API mocks, simulating responses based on the requests it receives, which in turn allows the testing process to continue even if dependent services or APIs are not ready.)

Learn more about microservices mocking.

Back to glossary