The following scenario is implemented here.
The term contract is synonymous with pact.
The frontend as a consumer has a contract with the backend as a provider and a contract broker (pact broker) is used as the exchange and documentation place. The frontend requests fruits and the backend responds with a possibly empty list of fruits. The important thing with CDC is, that the tests are focusing on the exact definitions of both, the request and the response.
In general, the following applies to CDC: The contract covers only the communication between two participants, describing requests and responses. No functional testing is applied. The consumer defines the exact request it will make and the exact response it wants to receive. This forms the contract. The provider then gets the contract and verifies that it fulfills the contract.
- Git
- Java (Version >=17)
- Docker Compose V2 to run the Pact Broker
Start the pact broker (docker-compose.yml)
and then access it via http://localhost.
docker compose upThe consumers CDC test creates the contract file
consumer/build/pacts/Frontend-Backend.json at runtime.
So, we only need to run the test,
easily by building the consumer project for the first time via gradle.
Building via gradle is enough, because the gradle build task also
calls the gradle test task.
consumer/gradlew -p consumer build
If gradle skips the build, you can run the test explicitly.
consumer/gradlew -p consumer testThe Frontend CDC test does the following:
- it defines the contract
- tests the Frontend against a contract-compliant mock provider
- and if the test passed, it creates the contract file
The pact.io gradle plugin publishes the contract to the broker.
consumer/gradlew -p consumer pactPublish
As mentioned above, the gradle build task also calls the test task.
Verifying the provider means calling its CDC test.
Thus, building the provider will also test (verify) it.
And due to our configuration, the verification result is
immediately published to the broker.
provider/gradlew -p provider build
If gradle skips the build, you can run the test explicitly.
provider/gradlew -p provider testCan I Deploy is a broker tool, to check if a service can be deployed without breaking the contract partner. The check is based on previous verifications of two contract partners and under specification of corresponding version numbers of the contract partners. In a real life project we would additionally specify a deployment or release environment. But for the sake of simplicity, we only check the compatibility of service versions in general here. Without inclusion of environments.
You have several ways to interact with the broker in order to use the tool. Here are two of them.
docker run --rm --network="host" -e PACT_BROKER_BASE_URL=http://localhost \
pactfoundation/pact-cli:latest \
pact-broker can-i-deploy \
--pacticipant Backend --latest \
--pacticipant Frontend --latestconsumer/gradlew -p consumer canideploy -P pacticipant='Frontend' -P latest=trueprovider/gradlew -p provider canideploy -P pacticipant='Backend' -P latest=trueIn this example, we are always using the latest version of the consumer and producer.
You can select another existing version with the -P pacticipantVersion=<version> flag.
As can be seen here, CDC aims, among other things, to ensure that the contractual partners, i.e. the consumer team and the provider team, talk to each other. CDC brings people to the table.
- Tests should have a very small scope
- Only the communication itself is of interest
- Responses may have extra fields, but requests may not (Postel's law)
- You can make use of provider states
- Use helpful versioning.
For example, use your preferred versioning scheme together with a git hash (i.e.
0.0.1+58d9b448).
- The Pact Broker exposes a User Interface, on http://localhost in our case
- You can also interact with the broker via CLI i.e. to create environments or to tag resources