In this post, we will explain what contract testing is, why it is useful, and how to use PACT to write contract tests for\nyour applications.<\/p>\n
What is contract testing?<\/h2>\n
Contract testing is a way to test the interactions between two applications. It allows you to define a contract between\nthe two applications, which specifies how they should interact. This contract can then be used to test both systems in\nisolation, without the need for a full integration test.<\/p>\n
With contract testing, you achieve the simplicity and speed of unit tests while significantly improving coverage,\nbringing it closer to the level of integration tests, but without the associated complexity or overhead.<\/p>\n
![\"Venn](\"https:\/\/devblogs.microsoft.com\/ise\/wp-content\/uploads\/sites\/55\/2025\/06\/venn-comparison.png\")
<\/p>\n
What is PACT?<\/h2>\n
PACT<\/a> is a contract testing tool that allows you to define a contract between two applications.\nIt is a consumer-driven contract testing tool, which means that the consumer of the API defines the contract. The\nprovider of the API then uses this contract to test that it meets the requirements of the consumer. This allows you to\ntest the interactions between the two applications without the need for a full integration test.<\/p>\n PACT is available in multiple languages, including Java, JavaScript, Ruby, and Go. This means that you can use PACT to\ntest applications written in different languages, which is especially useful in microservices architectures where\ndifferent services may be written in different languages. However, we have found that the PACT libraries for each language\ndo not have feature parity. For example the Java version of PACT is much more mature than the Python version. So, ensure\nyou verify the level of support before committing to using PACT in a less-supported language. You can find the list of\nsupported languages here<\/a>.<\/p>\n PACT is not just limited to REST APIs. It also supports testing interactions with message brokers, such as Kafka.<\/p>\n PACT works by defining a contract between the consumer and provider of an API. The consumer defines the contract by\nwriting a unit test that specifies the expected interactions with the API. This test is then used to generate a contract\nfile, which is a JSON file that contains the details of the contract. The provider then uses this contract file to test\nthat it meets the requirements of the consumer.<\/p>\n You can see an example of a contract file below:<\/p>\n The contract file contains the details of the interactions between the consumer and provider. It specifies the request\nand response details, including the HTTP method, path, headers, and body. It also specifies the matching rules for the\nrequest and response bodies, which allows you to specify things such as date patterns. The matching rules specify how\nthe request and response bodies should be matched, which allows you to test that the provider meets the requirements of\nthe consumer. It also specifies the provider state, which can be used to set up the state of the provider before the\ninteraction is verified, for example creating a mock order with ID 88 in your database or in-memory store. This will\nensure that when the consumer sends a request for order ID 88, it will receive a valid response.<\/p>\n The consumer side of PACT is where you define the contract. The first step is to create a test class for your client\nthat will call the provider system:<\/p>\n You then define the contract using the Finally, you can use the The Pact starts a mock server that simulates the provider system. The The provider side of PACT is where you verify that the provider system meets the requirements of the consumer. The\nfirst step is to create a test class for your provider system that will verify the contract. In our example, the\nprovider system is a Spring Boot application, so we can use the We then need to setup the test context and specify the target URL of the provider system. As we’re starting up the\nSpring Boot application, we can use the The We now need to define our tests:<\/p>\n The In the examples above, we have used the Alternatively, you can use the PACT broker<\/a> to store the contract files. The PACT\nbroker is a service that stores the contracts. A Docker image<\/a> is\navailable for the PACT broker, as well as Helm charts<\/a> for\ndeployment to Kubernetes.<\/p>\n So to summarise, PACT is a fantastic contract testing tool that takes the pain out of hand crafting contracts. If\nintegration tests are overkill or too complex to set up, as was the case for our team working on a proof of concept,\nthen contract testing using PACT is a great alternative.<\/p>\nHow does PACT work?<\/h2>\n
The contract file<\/h3>\n
{\n \"consumer\": {\n \"name\": \"OrderConsumer\"\n },\n \"provider\": {\n \"name\": \"OrderProvider\"\n },\n \"interactions\": [\n {\n \"description\": \"a request for a order\",\n \"providerStates\": [\n {\n \"name\": \"order with ID 88 exists\"\n }\n ],\n \"request\": {\n \"method\": \"GET\",\n \"path\": \"\/order\/88\",\n \"headers\": {\n \"Accept\": \"application\/json\"\n }\n },\n \"response\": {\n \"status\": 200,\n \"headers\": {\n \"Content-Type\": \"application\/json\"\n },\n \"body\": {\n \"id\": 1,\n \"items\": [\n \"milkshake\",\n \"burger\"\n ],\n \"date\": \"2025-03-26T12:00:00Z\"\n }\n },\n \"matchingRules\": {\n \"body\": {\n \"$.id\": {\n \"combine\": \"AND\",\n \"matchers\": [\n {\n \"match\": \"type\"\n }\n ]\n },\n \"$.items\": {\n \"combine\": \"AND\",\n \"matchers\": [\n {\n \"match\": \"type\"\n }\n ]\n },\n \"$.date\": {\n \"combine\": \"AND\",\n \"matchers\": [\n {\n \"format\": \"yyyy-MM-dd'T'HH:mm:ss\",\n \"match\": \"date\"\n }\n ]\n }\n }\n }\n }\n ]\n}<\/code><\/pre>\nThe consumer side<\/h3>\n
package com.example.pactdemo.client;\n\nimport au.com.dius.pact.consumer.MockServer;\nimport au.com.dius.pact.consumer.dsl.LambdaDslJsonBody;\nimport au.com.dius.pact.consumer.dsl.PactDslWithProvider;\nimport au.com.dius.pact.consumer.junit5.PactConsumerTest;\nimport au.com.dius.pact.consumer.junit5.PactTestFor;\nimport au.com.dius.pact.core.model.V4Pact;\nimport au.com.dius.pact.core.model.annotations.Pact;\nimport au.com.dius.pact.core.model.annotations.PactDirectory;\n\n\/\/ full import list omitted\n\n@PactConsumerTest\n@PactDirectory(\"..\/pacts\")\n@PactTestFor(providerName = \"PactDemoProvider\")\npublic class OrderClientTest {<\/code><\/pre>\n@Pact<\/code> annotation. The PactDslWithProvider<\/code> class is used to define and build\nthe request and response details, including the HTTP method, path, headers, and body. The LambdaDslJsonBody<\/code> class is\nused to define the matching rules for the request and response bodies:<\/p>\n @Pact(provider = \"PactDemoProvider\", consumer = \"PactDemoConsumer\")\n public V4Pact orderPact(PactDslWithProvider builder) {\n LambdaDslJsonBody expectedResponseBody = newJsonBody((expectedOrder) -> {\n expectedOrder.stringType(\"id\", \"88\");\n expectedOrder.object(\"user\", (user) -> {\n user.stringType(\"id\", \"881985\");\n user.stringType(\"firstName\", \"Sam\");\n user.stringType(\"lastName\", \"Jones\");\n user.stringType(\"email\", \"sam.jones@hungry.com\");\n });\n expectedOrder.array(\"items\", (item) -> {\n item.object((itemObj) -> {\n itemObj.stringType(\"id\", \"1\");\n itemObj.stringType(\"name\", \"Milkshake\");\n itemObj.stringType(\"description\", \"A delicious milkshake made with real ice cream and topped with whipped cream.\");\n itemObj.numberType(\"price\", 5.99);\n });\n item.object((itemObj) -> {\n itemObj.stringType(\"id\", \"2\");\n itemObj.stringType(\"name\", \"Burger\");\n itemObj.stringType(\"description\", \"A juicy beef burger with lettuce, tomato, and cheese.\");\n itemObj.numberType(\"price\", 12.99);\n });\n });\n expectedOrder.numberType(\"totalPrice\", 18.98);\n expectedOrder.date(\"orderDate\", \"yyyy-MM-dd'T'HH:mm:ss\", Date.from(LocalDateTime.parse(\"2015-10-21T10:30:00\").toInstant(UTC)));\n });\n\n return builder\n .given(\"order with ID 88 exists\")\n .uponReceiving(\"a request to get an order by id\")\n .path(\"\/order\/88\")\n .method(\"GET\")\n .headers(\"Accept\", \"application\/json\")\n .willRespondWith()\n .status(200)\n .headers(Map.of(\"Content-Type\", \"application\/json\"))\n .body(expectedResponseBody.build())\n .toPact(V4Pact.class);\n }<\/code><\/pre>\n@PactTestFor<\/code> annotation to specify the provider system that you are testing against:<\/p>\n @Test\n @PactTestFor(pactMethod = \"orderPact\")\n void testGetOrder(MockServer mockServer) throws Exception {\n OrderClient orderClient = new OrderClient(mockServer.getUrl());\n\n Order order = orderClient.getOrder(\"88\");\n\n assertNotNull(order);\n }<\/code><\/pre>\n@PactTestFor<\/code> annotation specifies the provider system that you are testing against, orderPact<\/code> in this example.\nThis needs to match the name of the method that defines the contract.<\/p>\nMockServer<\/code> object is used to get the URL of the mock\nserver, which is then passed to the OrderClient<\/code> to test against.<\/p>\nThe provider side<\/h3>\n
@SpringBootTest<\/code> annotation to start the application\nand run the tests against it:<\/p>\npackage com.example.pactdemo;\n\nimport au.com.dius.pact.provider.junit5.HttpTestTarget;\nimport au.com.dius.pact.provider.junit5.PactVerificationContext;\nimport au.com.dius.pact.provider.junit5.PactVerificationInvocationContextProvider;\nimport au.com.dius.pact.provider.junitsupport.Provider;\nimport au.com.dius.pact.provider.junitsupport.State;\nimport au.com.dius.pact.provider.junitsupport.loader.PactFolder;\n\n\/\/ full import list omitted\n\n@Provider(\"PactDemoProvider\")\n@PactFolder(\"..\/pacts\")\n@ExtendWith(SpringExtension.class)\n@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)\nclass PactDemoApplicationTests {<\/code><\/pre>\n@LocalServerPort<\/code> annotation to get the port that the application is running on\nand then set the target URL in the setUp<\/code> method. However, you can also test against a real deployed service if you\nwish to be setting the target URL to the real service:<\/p>\n @LocalServerPort\n int port;\n\n @BeforeEach\n void setUp(PactVerificationContext context) {\n context.setTarget(new HttpTestTarget(\"localhost\", port, \"\/\"));\n }\n\n @TestTemplate\n @ExtendWith(PactVerificationInvocationContextProvider.class)\n void verifyPact(PactVerificationContext context) {\n context.verifyInteraction();\n }<\/code><\/pre>\n@TestTemplate<\/code> verifies the interactions defined in the contract file. You can also use this to add other things\nsuch as authentication or other headers that are required by the provider system.<\/p>\n @State({\n \"order with ID 88 exists\",\n \"order with ID 999 does not exist\"\n })\n void testPactWhenOrderWithIdRequestReceived() {\n \/\/ This method is used to set up the state of the provider before the interaction is verified.\n \/\/ You can use this method to create any necessary data or perform any actions needed to set up the state.\n \/\/ For example, you could create a mock order with ID 88 in your database or in-memory store.\n \/\/ This will ensure that when the consumer sends a request for order ID 88, it will receive a valid response.\n \/\/ Similarly, you can set up the state for order ID 999 to return a 404 response.\n }<\/code><\/pre>\n@State<\/code> annotation specifies the provider state that is required for the interaction to be verified. The rest of\nthe test is empty, as the @TestTemplate<\/code> will take care of verifying the interaction. But if you need to set up any\ndata or perform any actions needed to set up the state, you can do that here.<\/p>\nWhere to store the contract files<\/h3>\n
@PactDirectory<\/code> annotation to specify the location of the contract files. These\ncan then just be committed to git. However, unless you’re using a monorepo, you will need to store the contract files in\na shared location that is accessible to both the consumer and provider systems. This could be a dedicated contract file\nrepository, where the consumers will need to manually copy the contract files and the providers will need to test\nagainst a pre-deployed system.<\/p>\nConclusion<\/h2>\n