|
Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
Learn how to test Java microservices with consumer-driven contracts in Open Liberty.
With a microservices-based architecture, you need robust testing to ensure that microservices that depend on one another are able to communicate effectively. Typically, to prevent multiple points of failure at different integration points, a combination of unit, integration, and end-to-end tests are used. While unit tests are fast, they are less trustworthy because they run in isolation and usually rely on mock data.
Integration tests address this issue by testing against real running services. However, they tend to be slow as the tests depend on other microservices and are less reliable because they are prone to external changes.
Usually, end-to-end tests are more trustworthy because they verify functionality from the perspective of a user. However, a graphical user interface (GUI) component is often required to perform end-to-end tests, and GUI components rely on third-party software, such as Selenium, which requires heavy computation time and resources.
What is contract testing?
Contract testing bridges the gaps among the shortcomings of these different testing methodologies. Contract testing is a technique for testing an integration point by isolating each microservice and checking whether the HTTP requests and responses that the microservice transmits conform to a shared understanding that is documented in a contract. This way, contract testing ensures that microservices can communicate with each other.
Pact is an open source contract testing tool for testing HTTP requests, responses, and message integrations by using contract tests.
The Pact Broker is an application for sharing Pact contracts and verification results. The Pact Broker is also an important piece for integrating Pact into continuous integration and continuous delivery (CI/CD) pipelines.
The two microservices you will interact with are called system and inventory. The system microservice returns the JVM system properties of its host. The inventory microservice retrieves specific properties from the system microservice.
You will learn how to use the Pact framework to write contract tests for the inventory microservice that will then be verified by the system microservice.
Before you begin, you need to install Docker if it is not already installed. For installation instructions, refer to the official Docker documentation. You will deploy the Pact Broker in a Docker container.
Start your Docker daemon before you proceed.
Run the following command to start the Pact Broker:
docker-compose -f "pact-broker/docker-compose.yml" up -d --buildWhen the Pact Broker is running, you’ll see the following output:
Creating pact-broker_postgres_1 ... done
Creating pact-broker_pact-broker_1 ... doneGo to the http://localhost:9292/ URL to confirm that you can access the user interface (UI) of the Pact Broker.
You can refer to the official Pact Broker documentation for more information about the components of the Docker Compose file.
Navigate to the start/inventory directory to begin.
Navigate back to the start directory.
Create the InventoryPactIT class file.
inventory/src/test/java/io/openliberty/guides/inventory/InventoryPactIT.java
InventoryPactIT.java
link:finish/inventory/src/test/java/io/openliberty/guides/inventory/InventoryPactIT.java[role=include]The InventoryPactIT class contains a PactProviderRule mock provider that mimics the HTTP responses from the system microservice. The @Pact annotation takes the name of the microservice as a parameter, which makes it easier to differentiate microservices from each other when you have multiple applications.
The createPactServer() method defines the minimal expected responses for a specific endpoint, which is known as an interaction. For each interaction, the expected request and the response are registered with the mock service by using the @PactVerification annotation.
The test sends a real request with the getUrl() method of the mock provider. The mock provider compares the actual request with the expected request and confirms whether the comparison is successful. Finally, the assertEquals() method confirms that the response is correct.
Replace the inventory Maven project file.
inventory/pom.xml
inventory/pom.xml
link:finish/inventory/pom.xml[role=include]The Pact framework provides a Maven plugin that can be added to the build section of the pom.xml file. The serviceProvider element defines the endpoint URL for the system microservice and the pactFileDirectory directory where you want to store the pact file. The pact-jvm-consumer-junit dependency provides the base test class that you can use with JUnit to build unit tests.
After you create the InventoryPactIT.java class and replace the pom.xml file, Open Liberty automatically reloads its configuration.
The contract between the inventory and system microservices is known as a pact. Each pact is a collection of interactions. In this guide, those interactions are defined in the InventoryPactIT class.
Press the enter/return key to run the tests and generate the pact file from the command-line session where you started the inventory microservice.
When completed, you’ll see a similar output to the following example:
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running io.openliberty.guides.inventory.InventoryPactIT
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.631 s - in io.openliberty.guides.inventory.InventoryPactIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0When you integrate the Pact framework in a CI/CD build pipeline, you can use the mvn failsafe:integration-test goal to generate the pact file. The Maven failsafe plug-in provides a lifecycle phase for running integration tests that run after unit tests. By default, it looks for classes that are suffixed with IT, which stands for Integration Test. You can refer to the Maven failsafe plug-in documentation for more information.
The generated pact file is named Inventory-System.json and is located in the inventory/target/pacts directory. The pact file contains the defined interactions in JSON format:
{
...
"interactions": [
{
"description": "a request for server name",
"request": {
"method": "GET",
"path": "/system/properties/key/wlp.server.name"
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/json"
},
"body": [
{
"wlp.server.name": "defaultServer"
}
]
},
"providerStates": [
{
"name": "wlp.server.name is defaultServer"
}
]
}
...
]
}
Now, navigate to the start/inventory directory again.
Publish the generated pact file to the Pact Broker by running the following command:
mvn pact:publishAfter the file is published, you’ll see a similar output to the following example:
--- maven:4.1.21:publish (default-cli) @ inventory ---
Publishing 'Inventory-System.json' with tags 'open-liberty-pact' ... OKRefresh the Pact Broker webpage at the http://localhost:9292/ URL to verify that a new entry exists. The last verified column doesn’t show a timestamp because the system microservice hasn’t verified the pact yet.
You can see detailed insights about each interaction by going to the http://localhost:9292/pacts/provider/System/consumer/Inventory/latest URL, as shown in the following image:
Open another command-line session and navigate to the start/system directory.
Start Open Liberty in dev mode for the system microservice:
mvn liberty:devAfter you see the following message, your Liberty instance is ready in dev mode:
************************************************************** * Liberty is running in dev mode.
Open another command-line session and navigate back to the start directory to continue.
Create the SystemBrokerIT class file.
system/src/test/java/it/io/openliberty/guides/system/SystemBrokerIT.java
SystemBrokerIT.java
link:finish/system/src/test/java/it/io/openliberty/guides/system/SystemBrokerIT.java[role=include]InventoryPactIT.java
link:finish/inventory/src/test/java/io/openliberty/guides/inventory/InventoryPactIT.java[role=include]The connection information for the Pact Broker is provided with the @PactBroker annotation. The dependency also provides a JUnit5 Invocation Context Provider with the pactVerificationTestTemplate() method to generate a test for each of the interactions.
The pact.verifier.publishResults property is set to true so that the results are sent to the Pact Broker after the tests are completed.
The test target is defined in the PactVerificationContext context to point to the running endpoint of the system microservice.
The @State annotation must match the given() parameter that was provided in the inventory test class so that Pact can identify which test case to run against which endpoint.
Replace the system Maven project file.
system/pom.xml
system/pom.xml
link:finish/system/pom.xml[role=include]The system microservice uses the junit5 pact provider dependency to connect to the Pact Broker and verify the pact file. Ideally, in a CI/CD build pipeline, the pact.provider.version element is dynamically set to the build number so that you can identify where a breaking change is introduced.
After you create the SystemBrokerIT.java class and replace the pom.xml file, Open Liberty automatically reloads its configuration.
In the command-line session where you started the system microservice, press the enter/return key to run the tests to verify the pact file. When you integrate the Pact framework into a CI/CD build pipeline, you can use the mvn failsafe:integration-test goal to verify the pact file from the Pact Broker.
The tests fail with the following errors:
[ERROR] Failures:
[ERROR] SystemBrokerIT.pactVerificationTestTemplate:28 Pact between Inventory (1.0-SNAPSHOT) and System - Upon a request for the version
Failures:
1) Verifying a pact between Inventory and System - a request for the version has a matching body
1.1) body: $.system.properties.version Expected "1.x" (String) to be a decimal number
[INFO]
[ERROR] Tests run: 4, Failures: 1, Errors: 0, Skipped: 0The test from the system microservice fails because the inventory microservice was expecting a decimal, 1.1, for the value of the system.properties.version property, but it received a string, "1.1".
Correct the value of the system.properties.version property to a decimal.
Replace the SystemResource class file.
system/src/main/java/io/openliberty/guides/system/SystemResource.java
SystemResource.java
link:finish/system/src/main/java/io/openliberty/guides/system/SystemResource.java[role=include]Press the enter/return key to rerun the tests from the command-line session where you started the system microservice.
If the tests are successful, you’ll see a similar output to the following example:
...
Verifying a pact between pact between Inventory (1.0-SNAPSHOT) and System
Notices:
1) The pact at http://localhost:9292/pacts/provider/System/consumer/Inventory/pact-version/XXX is being verified because it matches the following configured selection criterion: latest pact for a consumer version tagged 'open-liberty-pact'
[from Pact Broker http://localhost:9292/pacts/provider/System/consumer/Inventory/pact-version/XXX]
Given version is 1.1
a request for the version
returns a response which
has status code 200 (OK)
has a matching body (OK)
[main] INFO au.com.dius.pact.provider.DefaultVerificationReporter - Published verification result of 'au.com.dius.pact.core.pactbroker.TestResult$Ok@4d84dfe7' for consumer 'Consumer(name=Inventory)'
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.835 s - in it.io.openliberty.guides.system.SystemBrokerIT
...After the tests are complete, refresh the Pact Broker webpage at the http://localhost:9292/ URL to confirm that the last verified column now shows a timestamp:
The pact file that’s created by the inventory microservice was successfully verified by the system microservice through the Pact Broker. This ensures that responses from the system microservice meet the expectations of the inventory microservice.
When you are done checking out the service, exit dev mode by pressing CTRL+C in the command-line sessions where you ran the Liberty instances for the system and inventory microservices.
Navigate back to the /guide-contract-testing directory and run the following commands to remove the Pact Broker:
docker-compose -f "pact-broker/docker-compose.yml" down
docker rmi postgres:16.2
docker rmi pactfoundation/pact-broker:latest
docker volume rm pact-broker_postgres-volumeYou implemented contract testing in Java microservices by using Pact and verified the contract with the Pact Broker.
Learn more about the Pact framework.