Contract Testing Google Pub/Sub: Using AsyncAPI specs as Executable Contracts

Shift-Left the identification of integration issues in applications built with Event Driven Architecture (EDA) by leveraging AsyncAPI specs as Executable Contracts


The surge in popularity of microservices has revolutionized the way we think about software architecture. However, as systems grow and inter-service communication increases, the risk of integration issues can also rise. One such communication challenge appears when services interact through asynchronous messaging systems like Google Pub/Sub. To ensure reliability and adherence to predefined protocols, contract testing emerges as a crucial strategy. In this blog post, we’ll dive deeper into how Specmatic simplifies contract testing for services dependent on Google Pub/Sub, paving the way for faultless microservices communication through early identification of integration issues.

Github Repo:

See other demos of Specmatic in action with AsyncAPI:

Kafka Mocking with AsyncAPI using Specmatic
JMS Mocking with AsyncAPI using Specmatic

Understanding Google Pub/Sub and Contract Testing

Google Pub/Sub is a fully-managed real-time messaging service that allows applications to exchange messages effectively. A common scenario entails a service publishing a message to a topic, and another subscribing to that topic to receive the message. The challenge lies in ensuring that both parties agree on the message format—this is where contract testing comes into play.

Contract testing verifies interaction between service providers and consumers, confirming each side adheres to the agreed-upon contract. Specmatic, a tool adept at managing contract tests, uses the AsyncAPI specification to automate these tests using the provided schema of messages.

AsyncAPI Specifications and Specmatic

The AsyncAPI specification acts as a blueprint for your messaging API, defining the message structure, protocols, and channels used for communication. It’s what Specmatic relies on to ensure your Google Pub/Sub messages are both syntactically and functionally correct. Through the use of named examples within the AsyncAPI specification, Specmatic can publish and subscribe to messages, simulating the actions of actual services during the testing process.

Utilizing the Google Pub/Sub Emulator

Instead of interacting with a live instance of Google Pub/Sub, in this demo we opt for an emulator during testing. This approach accelerates the testing process and removes external dependencies, enabling local and CI pipeline-based executions that provide immediate feedback.

Specmatic Contract Test running as part of Github Action

Automating with Specmatic

In this demonstration of Specmatic’s capabilities, we see how Specmatic operates as an intelligent client for microservices. It sends messages and validates both the presence and correctness of the responses it receives. If requirements aren’t met, Specmatic flags the test as a failure, alerting developers to discrepancies between the service and the contract.

The Construction of a Contract Test with Specmatic

Constructing contract tests with Specmatic begins by pointing to the AsyncAPI specification within the `specmatic.json` file. Doing so allows Specmatic to generate tests automatically, fostering a seamless integration process.

The Value of Specmatic Testing

This testing approach facilitated by Specmatic offers a proactive measure for preventing integrations veering off-spec. The demonstration showcases a scenario where deliberately deviating from the AsyncAPI specification causes the contract test to fail. This illustrates Specmatic’s ability to catch errors early, preventing potential bugs from progressing down the deployment pipeline.

Specmatic’s Role in Maintaining Contract Integrity

Specmatic also ensures consistency across examples used within the AsyncAPI specification, associating messages across publish and subscribe operations via common naming conventions. This feature solidifies the link between message expectations, ensuring that changes in one area of the specification are consistently replicated throughout.

Collaborative and Efficient Development

Specmatic’s approach of treating AsyncAPI spec as the source of truth for the mutual agreement between microservice teams fosters a collaborative culture where all stakeholder teams can co-create how services interact with each other through asynchronous channels and capture the same as AsyncAPI spec in an iterative manner. This also allows for independent parallel development where teams can confidently build their respective components since Specmatic will ensure contract compatibility of services based on the AsyncAPI spec.


As services and their communication evolve, Specmatic’s approach to contract testing offers a scalable, efficient, and secure method for ensuring that all messages pass seamlessly between services, keeping the system in harmony. By automating contract tests utilizing the AsyncAPI specification to test Google Pub/Sub integrations, Specmatic allows developers to confidently build and maintain systems that are robust, reliable, and ready to communicate effectively. This exemplifies how automating and aligning software development practices with contract testing can vastly improve the overall software delivery lifecycle.