Tell us what you want and we will make it so: consumer-driven contract testing for messaging
Quite some time ago we have talked about consumer-driven contract testing from the perspective of the REST(ful) web APIs in general and their projection into Java (JAX-RS 2.0 specification) in particular. It would be fair to say that REST still dominates the web API landscape, at least with respect to public APIs, however the shift towards microservices or/and service-based architecture is changing the alignment of forces very fast. One of such disrupting trends is messaging.
Modern REST(ful) APIs are implemented mostly over HTTP 1.1 protocol and are constrained by its request/response communication style. The HTTP/2 is here to help out but still, not every use case fits into this communication model. Often the job could be performed asynchronously and the fact of its completion could be broadcasted to interested parties later on. This is how most of the things work in real life and using messaging is a perfect answer to that.
The messaging space is really crowded with astonishing amount of message brokers and brokerless options available. We are not going to talk about that instead focusing on another tricky subject: the message contracts. Once the producer emits message or event, it lands into the queue/topic/channel, ready to be consumed. It is here to stay for some time. Obviously, the producer knows what it publishes, but what about consumers? How would they know what to expect?
At this moment, many of us would scream: use schema-based serialization! And indeed, Apache Avro, Apache Thrift, Protocol Buffers, Message Pack, … are here to address that. At the end of the day, such messages and events become the part of the provider contract, along with the REST(ful) web APIs if any, and have to be communicated and evolved over time without breaking the consumers. But … you would be surprised to know how many organizations found their nirvana in JSON and use it to pass messages and events around, throwing such clobs at consumers, no schema whatsoever! In this post we are going to look at how consumer-driven contract testing technique could help us in such situation.
Let us consider a simple system with two services, Order Service and Shipment Service. The Order Service publishes the messages / events to the message queue and Shipment Service consumes them from there.
Since Order Service is implemented in Java, the events are just POJO classes, serialized into JSON before arriving to the message broker using one of the numerous libraries out there. OrderConfirmed is one of such events.
01 02 03 04 05 06 07 08 09 10 | public class OrderConfirmed { private UUID orderId; private UUID paymentId; private BigDecimal amount; private String street; private String city; private String state; private String zip; private String country;} |
As it often happens, the Shipment Service team was handed over the sample JSON snippet or pointed out some documentation piece, or reference Java class, and that is basically it. How Shipment Service team could kickoff the integration while being sure their interpretation is correct and the message’s data they need will not suddenly disappear? Consumer-driven contract testing to the rescue!
The Shipment Service team could (and should) start off by writing the test cases against the OrderConfirmed message, embedding the knowledge they have, and our old friend Pact framework (to be precise, Pact JVM) is the right tool for that. So how the test case may look like?
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | public class OrderConfirmedConsumerTest { private static final String PROVIDER_ID = "Order Service"; private static final String CONSUMER_ID = "Shipment Service"; @Rule public MessagePactProviderRule provider = new MessagePactProviderRule(this); private byte[] message; @Pact(provider = PROVIDER_ID, consumer = CONSUMER_ID) public MessagePact pact(MessagePactBuilder builder) { return builder .given("default") .expectsToReceive("an Order confirmation message") .withMetadata(Map.of("Content-Type", "application/json")) .withContent(new PactDslJsonBody() .uuid("orderId") .uuid("paymentId") .decimalType("amount") .stringType("street") .stringType("city") .stringType("state") .stringType("zip") .stringType("country")) .toPact(); } @Test @PactVerification(PROVIDER_ID) public void test() throws Exception { Assert.assertNotNull(message); } public void setMessage(byte[] messageContents) { message = messageContents; }} |
It is exceptionally simple and straightforward, no boilerplate added. The test case is designed right from the JSON representation of the OrderConfirmed message. But we are only half-way through, the Shipment Service team should somehow contribute their expectations back to the Order Service so the producer would keep track of who and how consumes the OrderConfirmed message. The Pact test harness takes care of that by generating the pact files (set of agreements, or pacts) out of the each JUnit test cases into the ‘target/pacts’ folder. Below is an example of the generated Shipment Service-Order Service.json pact file after running OrderConfirmedConsumerTest test suite.
001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100 101 102 103 104 105 106 107 108 109 | { "consumer": { "name": "Shipment Service" }, "provider": { "name": "Order Service" }, "messages": [ { "description": "an Order confirmation message", "metaData": { "contentType": "application/json" }, "contents": { "zip": "string", "country": "string", "amount": 100, "orderId": "e2490de5-5bd3-43d5-b7c4-526e33f71304", "city": "string", "paymentId": "e2490de5-5bd3-43d5-b7c4-526e33f71304", "street": "string", "state": "string" }, "providerStates": [ { "name": "default" } ], "matchingRules": { "body": { "$.orderId": { "matchers": [ { "match": "regex", "regex": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" } ], "combine": "AND" }, "$.paymentId": { "matchers": [ { "match": "regex", "regex": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" } ], "combine": "AND" }, "$.amount": { "matchers": [ { "match": "decimal" } ], "combine": "AND" }, "$.street": { "matchers": [ { "match": "type" } ], "combine": "AND" }, "$.city": { "matchers": [ { "match": "type" } ], "combine": "AND" }, "$.state": { "matchers": [ { "match": "type" } ], "combine": "AND" }, "$.zip": { "matchers": [ { "match": "type" } ], "combine": "AND" }, "$.country": { "matchers": [ { "match": "type" } ], "combine": "AND" } } } } ], "metadata": { "pactSpecification": { "version": "3.0.0" }, "pact-jvm": { "version": "4.0.2" } }} |
The next step for Shipment Service team is to share this pact file with Order Service team so these guys could run the provider-side Pact verifications as part of their test suites.
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | @RunWith(PactRunner.class)@Provider(OrderServicePactsTest.PROVIDER_ID)@PactFolder("pacts") public class OrderServicePactsTest { public static final String PROVIDER_ID = "Order Service"; @TestTarget public final Target target = new AmqpTarget(); private ObjectMapper objectMapper; @Before public void setUp() { objectMapper = new ObjectMapper(); } @State("default") public void toDefaultState() { } @PactVerifyProvider("an Order confirmation message") public String verifyOrderConfirmed() throws JsonProcessingException { final OrderConfirmed order = new OrderConfirmed(); order.setOrderId(UUID.randomUUID()); order.setPaymentId(UUID.randomUUID()); order.setAmount(new BigDecimal("102.33")); order.setStreet("1203 Westmisnter Blvrd"); order.setCity("Westminster"); order.setCountry("USA"); order.setState("MI"); order.setZip("92239"); return objectMapper.writeValueAsString(order); }} |
The test harness picks all the pact files from the @PactFolder and run the tests against the @TestTarget, in this case we are wiring AmqpTarget, provided out of the box, but your could plug your own specific target easily.
And this is basically it! The consumer (Shipment Service) have their expectations expressed in the test cases and shared with the producer (Order Service) in a shape of the pact files. The producers have own set of tests to make sure its model matches the consumers’ view. Both sides could continue to evolve independently, and trust each other, as far as pacts are not denounced (hopefully, never).
To be fair, Pact is not the only choice for doing consumer-driven contract testing, in the upcoming post (already in work) we are going to talk about yet another excellent option, Spring Cloud Contract.
As for today, the complete project sources are available on Github.
Published on Java Code Geeks with permission by Andrey Redko, partner at our JCG program. See the original article here: Tell us what you want and we will make it so: consumer-driven contract testing for messaging Opinions expressed by Java Code Geeks contributors are their own. |
