-
-
Notifications
You must be signed in to change notification settings - Fork 177
Overview
The Pact Broker is a service that supports contract testing by enabling the exchange of pacts and verification results.
- The consumer CI build generates and publishes pacts.
- The provider CI retrieves and verifies the pacts, and publishes the verification results.
- Consumer and provider CI deployment builds check with the broker before deploying to ensure the application version they are about deploy will be compatible with the versions of the other applications that are already deployed in that environment.
A pact is published using the consumer name, the provider name, and the consumer application version as an identifying key (PUT /pacts/provider/PROVIDER/consumer/CONSUMER/version/CONSUMER_APPLICATION_VERSION). The versioning of the pact content itself is done behind the scenes by the broker.
Consumer and provider applications are known as pacticipants (a bad pun which the pact broker author now regrets.) A pacticipant may be both a consumer and a provider. Pacticipants are automatically created when a pact is published for the first time. Pacticipant version resources are also automatically created.
When a pact is published, we know the provider, the consumer and the consumer version. We don't know the provider version until the pact is verified, and the verification results are published. A verification is published using the consumer name, the provider name, and the SHA of the pact content. This means that if a new pact is published with exactly the same content as a previously verified one, it will automatically inherit the verification results of the existing content.
Tags are used to "bookmark" important versions of an application (known as a pacticipant in the API). They are generally used for identifying stages (eg. dev, staging, prod) or branches (eg. feat-some-new-thing) of your application. For example you might tag version 1.2.3+c6d6a4 of application Foo as the prod version (PUT /pacticipants/PACTICIPANT/versions/VERSION/tags/TAG. A version can have multiple tags. While tags belongs to application versions, they are mostly used for retrieving pacts. For example, you can retrieve the latest prod pact (GET /pacts/provider/PROVIDER/consumer/CONSUMER/latest/TAG)
The Pact Broker API uses HAL (Hypertext Application Language) as its hypermedia implementation (that is, the method of providing links within a resource to navigate from that resource to related resources). The Broker comes with an embedded HAL browser that lets you navigate the API in your browser window by using the HAL relations in each resource. You can start with the index resource and navigate to almost any resource in the API just by clicking the GET button the appropriate relation. Any programmatic client of the Pact Broker will use these links rather than constructing URLs manually, to allow the API to evolve without breaking its clients.
Add explanation of can-i-deploy and webhooks.
- Pacts and verifications should only be published from CI builds, not developer local machines.
- Note that if you publish a pact, the consumer, provider and consumer version resources are automatically created, however, if you delete a pact, they are not automatically deleted, so you may have orphan data lying around that will give you inconsistent results when you query the broker.