Contract Testing – what is it and why do you need it

Testing is a multilayered engineering activity required at many levels in the software architecture and development process. However, as companies look to design systems in a more modular fashion to allow for more rapid development and independent deployment cycles between delivery teams and services, the importance of contract testing has risen.

Contract testing is software testing that focuses on verifying and ensuring that two separate systems (usually services in a microservices architecture) can communicate with each other according to a predefined agreement, known as a "contract." This contract typically defines the expectations of the communication, including the structure of the requests and responses and the data types and values exchanged between the services.

This approach enables teams to create comprehensive automated tests for their services, incorporating effective mocking based on agreed-upon contracts. By doing so, teams can deploy with a high level of confidence, knowing that their dependencies haven't changed unexpectedly—otherwise, the contract tests would catch and flag these issues.

This method allows teams to develop software independently and with greater trust, while also alerting them to any unforeseen changes in dependencies, enabling them to address these proactively. Additionally, it significantly reduces the need for extensive and complex end-to-end testing. Although contract testing doesn't eliminate the need for end-to-end tests, it ensures that only minimal smoke-level integration tests are necessary, as the full functionality would already have been thoroughly validated within the pipelines using mocks.

Contract testing offers a structured, efficient, and scalable approach to ensuring that services in a distributed system can interact correctly and reliably. It provides significant advantages in terms of early issue detection, team independence, and overall system stability, making it a key practice for organizations adopting microservices or other service-oriented architectures.

Key Aspects of Contract Testing

Below are the key aspects of Contract Testing that it is important to know:

• Consumer-Driven Contracts: The tests are usually written by the consumers (clients) of a service, specifying what they expect from the service provider. The service provider then ensures that their API or service meets these expectations.
• Validation of Interactions: Contract testing validates that the provider and consumer can interact correctly. If the provider changes its API, contract tests will ensure these changes do not break the consumer's expectations.
• Isolation: Unlike end-to-end testing, which tests a full workflow involving multiple services, contract testing isolates the interaction between a single consumer and provider, making it faster and easier to maintain.
• Decoupling of Development: Since contract tests define clear expectations, both the provider and consumer teams can work independently as long as they adhere to the contract.

What problems does it solve:

Contract testing addresses several critical challenges in software development, particularly in environments where multiple services or components need to interact with one another. Here’s a breakdown of the key problems contract testing solves:

Integration Breakages Due to API Changes

• Problem: When a service provider (API) changes its interface (e.g., request/response formats, endpoints, data types), it can break the consumers (clients) that depend on it. These changes might not be immediately apparent, especially if end-to-end tests aren't run frequently or thoroughly enough.
• Solution: Contract testing ensures that any changes made to the provider's API are checked against the expectations of the consumers. If a change breaks the contract, the tests will fail, alerting developers to potential integration issues before they reach production.

Lack of Clear Communication and Expectations Between Services

• Problem: In distributed systems or microservices architectures, different teams often work on different services. Without clear communication, there can be misunderstandings about what each service should expect from the other, leading to integration issues.
• Solution: Contract testing formalizes the expectations between services in the form of a contract. This contract serves as a clear, agreed-upon specification that both the provider and consumer adhere to, reducing the risk of miscommunication and mismatched expectations.

Slow and Fragile End-to-End Testing

• Problem: End-to-end testing, which tests the entire system as a whole, can be slow, complex, and prone to flakiness. It also requires all components of the system to be up and running, which can be challenging in large, distributed systems.
• Solution: Contract testing isolates the testing of interactions between specific services, making the tests faster, more reliable, and easier to maintain. It reduces the dependency on slow and brittle end-to-end tests while still ensuring that services interact correctly.

Difficulty in Isolating and Diagnosing Integration Issues

• Problem: When an integration issue arises, it can be difficult to pinpoint the exact cause, especially in a system with many interconnected services. Traditional testing methods may not provide sufficient granularity to isolate the problem quickly.
• Solution: Contract testing isolates the interaction between specific consumers and providers, making it easier to diagnose which service is not meeting the agreed-upon expectations. This helps in quickly identifying and fixing the root cause of integration issues.

Dependency Hell in Service Development

• Problem: In microservices or distributed systems, services often depend on each other. If one service changes, all dependent services may need to be updated and tested, creating a bottleneck in development and deployment processes.
• Solution: Contract testing allows services to evolve independently as long as they adhere to the agreed contract. This decoupling reduces the dependency chain and allows teams to work in parallel without constantly needing to synchronize changes.

Regression Risks with Continuous Deployment

• Problem: In environments that practice continuous deployment, new features or changes are deployed rapidly. Without sufficient testing, there’s a risk that a change in one service could cause regressions in others.
• Solution: Contract tests are integrated into CI/CD pipelines, ensuring that any new code is automatically checked against the existing contracts before being deployed. This reduces the risk of regressions and ensures that services continue to work together as expected.

Challenges in Scaling Testing Across Large, Distributed Systems

• Problem: As systems grow, managing and scaling testing efforts becomes increasingly difficult. End-to-end tests become more complex, and the likelihood of issues slipping through the cracks increases.
• Solution: Contract testing scales well with distributed systems, allowing for the testing of individual service interactions without the overhead of testing the entire system at once. This makes it easier to maintain testing as the system grows.

Lack of Confidence in Service Integrations

• Problem: Teams may lack confidence that their service integrations will work as expected in production, leading to delays, extensive manual testing, or rollback of deployments.
• Solution: Contract testing builds confidence by providing a reliable, automated way to verify that services will integrate correctly. Teams can deploy changes with the assurance that they won’t break existing integrations.

Contract testing solves the critical problem of ensuring reliable and consistent communication between services in a distributed system. It addresses the challenges of integration breakages, unclear expectations, slow testing processes, and scaling in large systems, making it an essential practice for maintaining the health and stability of service-oriented architectures.

Benefits of Contract Testing

We’ve looked at the reason why it is needed and the problems Contract Testin can solve. Alongside this, though Contract testing offers several significant benefits, especially in complex, distributed systems like microservices architectures. Let’s delve deeper into these benefits:

Early Detection of Integration Issues

• Proactive Issue Identification: Contract testing allows developers to catch issues early in the development cycle. Since the contract defines the expectations for the interaction between services, any change that violates this contract will immediately cause the tests to fail.
• Pre-production Validation: By running contract tests in development and CI/CD pipelines, teams can prevent broken integrations from reaching production, reducing the risk of service disruptions.

Decoupling of Development Teams

• Independent Development: Contract testing enables different teams (e.g., those working on the consumer and provider services) to work independently. As long as both teams adhere to the agreed-upon contract, they can make changes to their services without constantly needing to coordinate.
• Clear Boundaries: Contracts act as formalized agreements between services, clarifying what each service expects from the other. This reduces misunderstandings and minimizes the need for constant cross-team communication.

Faster Feedback Loops

• Efficient Testing: Contract tests are generally faster to run than end-to-end tests because they focus on specific interactions between services rather than the entire workflow. This speed enables quicker feedback for developers, helping them identify and fix issues faster.
• Continuous Integration: Integrating contract tests into CI/CD pipelines ensures that changes are validated against the contract continuously, allowing for rapid iteration and deployment.

Reduced Need for Extensive End-to-End Tests

• Focused Testing: Since contract tests validate interactions between specific services, they reduce the reliance on extensive end-to-end tests. End-to-end tests, while valuable, can be slow, brittle, and challenging to maintain.
• Simplified Test Maintenance: With fewer end-to-end tests, teams can focus on maintaining smaller, more targeted contract tests that are easier to manage and update.

Enhanced Communication and Collaboration

• Shared Understanding: Contract testing fosters a shared understanding of the expectations between services. This shared contract serves as a single source of truth that both the consumer and provider agree on.
• Versioning and Evolution: Contracts can be versioned, allowing for smooth transitions when APIs evolve. Teams can manage backward compatibility by maintaining multiple versions of a contract, ensuring that new changes do not break existing consumers.

Improved Reliability and Stability

• Consistent Behavior: By ensuring that services adhere to their contracts, contract testing promotes consistent behavior across environments (development, staging, production). This consistency leads to more reliable and stable systems.
• Resilience to Changes: Since contract testing catches breaking changes early, it reduces the likelihood of unexpected failures when deploying new versions of services.

Documentation and Traceability

• Automatic Documentation: The contract itself serves as living documentation of the service’s expected behavior. This documentation is automatically kept up-to-date as the contract is modified.
• Traceability of Changes: Any changes to the contract are versioned and documented, providing a clear history of how the interaction between services has evolved over time.

Cost and Time Efficiency

• Reduced Rework: By catching issues early, contract testing minimizes the time and cost associated with reworking code after issues are discovered late in the development process or in production.
• Optimized Resources: Faster, targeted tests consume fewer computational resources compared to comprehensive end-to-end tests, optimizing the use of testing infrastructure.

Supports Microservices and Distributed Architectures

• Fit for Microservices: In microservices architectures, where services are loosely coupled but highly dependent on inter-service communication, contract testing is particularly beneficial. It ensures that services can evolve independently without causing disruptions to others.
• Scalable Testing Approach: As systems grow, contract testing scales well, allowing for the testing of interactions across a large number of services without the overhead of full-system integration tests.

Improved Consumer Confidence

• Trust in Provider Services: Consumers (clients) can develop trust in the provider services because contract tests guarantee that their expectations are consistently met.
• Facilitates Agile Practices: In agile environments, where rapid iteration and deployment are critical, contract testing ensures that new features or changes can be delivered quickly without compromising the quality of service interactions.

How to Implement Contract Testing

Below I will provide an example of how you can implement contract testing in your area with a specific example between two services. In this example, we will explain the difference between the two services what the contract will look like and provide some scripting examples of what the tests themselves will look like.

Example Scenario

For this example, we will consider the following two services:

• Service A (Consumer): A frontend service that fetches user details.
• Service B (Provider): A user service that provides user details via an API.

The Contract

The contract between Service A and Service B might specify:

• Request: Service A will send a GET request to /user/{id}.
• Response: Service B will respond with a JSON object containing id, name, and email.

Here’s a sample contract in JSON code:

{
  "request": {
    "method": "GET",
    "path": "/user/123",
    "headers": {
      "Accept": "application/json"
    }
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "id": "123",
      "name": "John Doe",
      "email": "[email protected]"
    }
  }
}        

Writing Contract Test Cases

There are many different tools available for contract testing, but for this example, we'll use Pact, which is a popular tool for consumer-driven contract testing. Look out for a future article about Pact.

Step 1: Writing Consumer Tests (Service A)

Service A will define its expectations in a contract. These expectations are written as unit tests using a Pact library.

Here’s an example using Pact with Java:

import au.com.dius.pact.consumer.dsl.PactDslWithProvider;
import au.com.dius.pact.consumer.PactProviderRule;
import au.com.dius.pact.consumer.PactVerification;
import au.com.dius.pact.consumer.PactVerificationResult;
import au.com.dius.pact.consumer.dsl.PactDslJsonBody;
import org.junit.Rule;
import org.junit.Test;
 
import static io.restassured.RestAssured.given;
import static org.junit.Assert.assertTrue;
 
public class UserServicePactTest {
 
    @Rule
    public PactProviderRule mockProvider = new PactProviderRule("UserService", this);
 
    @Pact(consumer = "UserFrontend")
    public RequestResponsePact createPact(PactDslWithProvider builder) {
        return builder
            .given("User 123 exists")
            .uponReceiving("A request for user 123")
                .path("/user/123")
                .method("GET")
                .willRespondWith()
                .status(200)
                .body(new PactDslJsonBody()
                    .stringType("id", "123")
                    .stringType("name", "John Doe")
                    .stringType("email", "[email protected]"))
            .toPact();
    }
 
    @Test
    @PactVerification
    public void runTest() {
        // Act: Making a request to the mock provider
        String response = given()
            .when()
            .get(mockProvider.getUrl() + "/user/123")
            .then()
            .extract()
            .asString();
 
        // Assert: Validate the response
        assertTrue(response.contains("John Doe"));
    }
}        

Step 2: Writing Provider Tests (Service B)

Service B will verify that it meets the expectations defined in the contract. This is done by running the contract against the actual service implementation.

Here’s an example using Pact with Spring Boot:

import au.com.dius.pact.provider.junit.PactProviderRule;
import au.com.dius.pact.provider.junit.State;
import au.com.dius.pact.provider.junit.loader.PactBroker;
import au.com.dius.pact.provider.junit.loader.PactFolder;
import au.com.dius.pact.provider.junit.provider.PactVerification;
import au.com.dius.pact.provider.junit.provider.PactVerificationInvocationContextProvider;
import org.junit.Rule;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
 
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@PactFolder("pacts") // or use @PactBroker(url = "http://broker.url")

public class UserServiceProviderTest {
 
    @Rule
    public PactProviderRule provider = new PactProviderRule("UserService", this);
 
    @State("User 123 exists")
    public void toUser123ExistsState() {
        // Set up data or mocks for user 123
    }
 
    @Test
    @PactVerification(value = "UserService")
    public void verifyContract() {
        // This will verify if the provider meets the expectations of the consumer
    }
}        

Workflow

1. Consumer Test Execution: The consumer (Service A) runs the contract tests and generates a contract. This contract is shared with the provider (Service B) through a Pact broker or a shared location.
2. Provider Test Execution: The provider (Service B) runs the contract against its implementation to ensure it meets the consumer's expectations. If the provider's API changes in a way that violates the contract, the test will fail, signalling that the provider needs to address the issue.

Benefits of This Approach

• Consumer-Driven: The consumer defines the expectations, ensuring that the provider meets the needs of the consumer.
• Automated Verification: The contract tests automatically verify the integration between services.
• Early Detection: Changes in the provider that might break the consumer are detected early in the development cycle.

Tools for Contract Testing

There are many different tools that can be used for contract testing, though below are some of the biggest ones.

Pact

• Overview: Pact is a consumer-driven contract testing tool that allows consumers to define the expectations of an API and share these contracts with providers.
• Languages Supported: Java, JavaScript, Python, Ruby, .NET, and more.
• Key Features: Pact broker for managing contracts, easy integration with CI/CD pipelines, support for asynchronous messaging.

Spring Cloud Contract

• Overview: Spring Cloud Contract is a contract testing tool specifically designed for the Spring ecosystem. It allows for the creation of contracts that can be used to generate both consumer and provider tests.
• Languages Supported: Primarily Java.
• Key Features: Seamless integration with Spring applications, supports REST and messaging, generates stubs for consumer tests.

Postman

• Overview: Postman is a popular API testing tool that also supports contract testing. It allows you to define and validate contracts through API schemas.
• Languages Supported: GUI-based tool, with scripting support in JavaScript.
• Key Features: API schema validation, extensive API testing capabilities, integration with CI/CD pipelines via Newman.

Hoverfly

• Overview: Hoverfly is a lightweight service virtualization tool that can also be used for contract testing. It simulates HTTP services and validates the interactions against expected behavior.
• Languages Supported: Compatible with any language that can make HTTP requests.
• Key Features: Simulates HTTP(S) services, supports capturing and replaying HTTP traffic, is lightweight, and easy to set up.

Contract First

• Overview: Contract First is an approach where the API contract is defined before any code is written. Tools like Swagger/OpenAPI are often used in this approach to ensure both consumer and provider adhere to the contract.
• Languages Supported: Multi-language support via Swagger/OpenAPI.
• Key Features: API-first design, automatic generation of client and server code, contract validation against OpenAPI/Swagger specifications.

Summary

Contract testing solves the critical problem of ensuring reliable and consistent communication between services in a distributed system. It addresses the challenges of integration breakages, unclear expectations, slow testing processes, and scaling in large systems, making it an essential practice for maintaining the health and stability of service-oriented architectures.