au.com.dius:pact-jvm-provider-lein_2.11

# Leiningen plugin to verify a provider [version 2.2.14+, 3.0.3+] Leiningen plugin for verifying pacts against a provider. The plugin provides a `pact-verify` task which will verify all configured pacts against your provider. ## To Use It ### 1. Add the plugin to your project plugins, preferably in it's own profile. ```clojure :profiles { :pact { :plugins [[au.com.dius/pact-jvm-provider-lein_2.11 "3.2.11" :exclusions [commons-logging]]] :dependencies [[ch.qos.logback/logback-core "1.1.3"] [ch.qos.logback/logback-classic "1.1.3"] [org.apache.httpcomponents/httpclient "4.4.1"]] }}} ``` ### 2. Define the pacts between your consumers and providers You define all the providers and consumers within the `:pact` configuration element of your project. ```clojure :pact { :service-providers { ; You can define as many as you need, but each must have a unique name :provider1 { ; All the provider properties are optional, and have sensible defaults (shown below) :protocol "http" :host "localhost" :port 8080 :path "/" :has-pact-with { ; Again, you can define as many consumers for each provider as you need, but each must have a unique name :consumer1 { ; pact file can be either a path or an URL :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` ### 3. Execute `lein with-profile pact pact-verify` You will have to have your provider running for this to pass. ## Enabling insecure SSL For providers that are running on SSL with self-signed certificates, you need to enable insecure SSL mode by setting `:insecure true` on the provider. ```clojure :pact { :service-providers { :provider1 { :protocol "https" :host "localhost" :port 8443 :insecure true :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` ## Specifying a custom trust store For environments that are running their own certificate chains: ```clojure :pact { :service-providers { :provider1 { :protocol "https" :host "localhost" :port 8443 :trust-store "relative/path/to/trustStore.jks" :trust-store-password "changeme" :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` `:trust-store` is relative to the current working (build) directory. `:trust-store-password` defaults to `changeit`. NOTE: The hostname will still be verified against the certificate. ## Modifying the requests before they are sent Sometimes you may need to add things to the requests that can't be persisted in a pact file. Examples of these would be authentication tokens, which have a small life span. The Leiningen plugin provides a request filter that can be set to an anonymous function on the provider that will be called before the request is made. This function will receive the HttpRequest object as a parameter. ```clojure :pact { :service-providers { :provider1 { ; function that adds an Authorization header to each request :request-filter #(.addHeader % "Authorization" "oauth-token eyJhbGciOiJSUzI1NiIsIm...") :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` __*Important Note:*__ You should only use this feature for things that can not be persisted in the pact file. By modifying the request, you are potentially modifying the contract from the consumer tests! ## Modifying the HTTP Client Used The default HTTP client is used for all requests to providers (created with a call to `HttpClients.createDefault()`). This can be changed by specifying a function assigned to `:create-client` on the provider that returns a `CloseableHttpClient`. The function will receive the provider info as a parameter. ## Turning off URL decoding of the paths in the pact file [version 3.3.3+] By default the paths loaded from the pact file will be decoded before the request is sent to the provider. To turn this behaviour off, set the system property `pact.verifier.disableUrlPathDecoding` to `true`. __*Important Note:*__ If you turn off the url path decoding, you need to ensure that the paths in the pact files are correctly encoded. The verifier will not be able to make a request with an invalid encoded path. ## Plugin Properties The following plugin options can be specified on the command line: |Property|Description| |--------|-----------| |:pact.showStacktrace|This turns on stacktrace printing for each request. It can help with diagnosing network errors| |:pact.showFullDiff|This turns on displaying the full diff of the expected versus actual bodies [version 3.3.6+]| |:pact.filter.consumers|Comma seperated list of consumer names to verify| |:pact.filter.description|Only verify interactions whose description match the provided regular expression| |:pact.filter.providerState|Only verify interactions whose provider state match the provided regular expression. An empty string matches interactions that have no state| |:pact.verifier.publishResults|Publishing of verification results will be skipped unless this property is set to 'true' [version 3.5.18+]| |:pact.matching.wildcard|Enables matching of map values ignoring the keys when this property is set to 'true'| Example, to run verification only for a particular consumer: ``` $ lein with-profile pact pact-verify :pact.filter.consumers=consumer2 ``` ## Provider States For each provider you can specify a state change URL to use to switch the state of the provider. This URL will receive the `providerState` description from the pact file before each interaction via a POST. The `:state-change-uses-body` controls if the state is passed in the request body or as a query parameter. These values can be set at the provider level, or for a specific consumer. Consumer values take precedent if both are given. ```clojure :pact { :service-providers { :provider1 { :state-change-url "http://localhost:8080/tasks/pactStateChange" :state-change-uses-body false ; defaults to true :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` If the `:state-change-uses-body` is not specified, or is set to true, then the provider state description will be sent as JSON in the body of the request. If it is set to false, it will passed as a query parameter. As for normal requests (see Modifying the requests before they are sent), a state change request can be modified before it is sent. Set `:state-change-request-filter` to an anonymous function on the provider that will be called before the request is made. ## Filtering the interactions that are verified You can filter the interactions that are run using three properties: `:pact.filter.consumers`, `:pact.filter.description` and `:pact.filter.providerState`. Adding `:pact.filter.consumers=consumer1,consumer2` to the command line will only run the pact files for those consumers (consumer1 and consumer2). Adding `:pact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `:pact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `:pact.filter.providerState=` will match any interaction that does not have a provider state. ## Starting and shutting down your provider For the pact verification to run, the provider needs to be running. Leiningen provides a `do` task that can chain tasks together. So, by creating a `start-app` and `terminate-app` alias, you could so something like: $ lein with-profile pact do start-app, pact-verify, terminate-app However, if the pact verification fails the build will abort without running the `terminate-app` task. To have the start and terminate tasks always run regardless of the state of the verification, you can assign them to `:start-provider-task` and `:terminate-provider-task` on the provider. ```clojure :aliases {"start-app" ^{:doc "Starts the app"} ["tasks to start app ..."] ; insert tasks to start the app here "terminate-app" ^{:doc "Kills the app"} ["tasks to terminate app ..."] ; insert tasks to stop the app here } :pact { :service-providers { :provider1 { :start-provider-task "start-app" :terminate-provider-task "terminate-app" :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` Then you can just run: $ lein with-profile pact pact-verify and the `start-app` and `terminate-app` tasks will run before and after the provider verification. ## Specifying the provider hostname at runtime [3.0.4+] If you need to calculate the provider hostname at runtime (for instance it is run as a new docker container or AWS instance), you can give an anonymous function as the provider host that returns the host name. The function will receive the provider information as a parameter. ```clojure :pact { :service-providers { :provider1 { :host #(calculate-host-name %) :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ```


Keywords
consumer-driven-contracts, contract-testing, hacktoberfest, pact, smartbear-supported
License
Apache-2.0

Documentation

Pact-JVM

Pact-JVM Build Maven Central

JVM implementation of the consumer driven contract library pact.

From the Ruby Pact website:

Define a pact between service consumers and providers, enabling "consumer driven contract" testing.

Pact provides an RSpec DSL for service consumers to define the HTTP requests they will make to a service provider and the HTTP responses they expect back. These expectations are used in the consumers specs to provide a mock service provider. The interactions are recorded, and played back in the service provider specs to ensure the service provider actually does provide the response the consumer expects.

This allows testing of both sides of an integration point using fast unit tests.

This gem is inspired by the concept of "Consumer driven contracts". See https://martinfowler.com/articles/consumerDrivenContracts.html for more information.

Read Getting started with Pact for more information on how to get going.

Contact

Links

Tutorial (60 minutes)

Learn everything in Pact in 60 minutes: https://github.com/pact-foundation/pact-workshop-jvm-spring.

The workshop takes you through all of the key concepts of consumer and provider testing using a Spring boot application.

Documentation

Additional documentation can be found at docs.pact.io, in the Pact Wiki, and in the Pact-JVM wiki. Stack Overflow is also a good source of help, as is the Slack workspace.

Supported JDK and specification versions:

Branch Specification JDK Kotlin Version Latest Version Notes
4.6.x master V4 + plugins 17+ 1.8.22 4.6.6
4.5.x V4 + plugins 11+/17+(1) 1.7.20 4.5.8
4.1.x V3 8-12 1.3.72 4.1.42

Notes:

  • 1: Spring6 support library requires JDK 17+. The rest of Pact-JVM 4.5.x libs require 11+.

Previous versions (not actively supported)

Branch Specification JDK Kotlin Version Scala Versions Latest Version
4.4.x V4 + plugins 11+ 1.6.21 N/A 4.4.9
4.3.x V4 11+ 1.6.21 N/A 4.3.19
4.2.x V4 (1) 11-15 (2) 1.4.32 N/A 4.2.21
4.0.x V3 8-12 1.3.71 N/A 4.0.10
3.6.x V3 8 1.3.71 2.12 3.6.15
3.5.x V3 8 1.1.4-2 2.12, 2.11 3.5.25
3.5.x-jre7 V3 7 1.1.4-2 2.11 3.5.7-jre7.0
2.4.x V2 6 N/A 2.10, 2.11 2.4.20

Notes:

  • 1: V4 specification support is only partially implemented with 4.2.x
  • 2: v4.2.x may run on JDK 16, but the build for it does not.

NOTE: The JARs produced by this project have changed with 4.1.x to better align with Java 9 JPMS. The artefacts are now:

au.com.dius.pact:consumer
au.com.dius.pact.consumer:groovy
au.com.dius.pact.consumer:junit
au.com.dius.pact.consumer:junit5
au.com.dius.pact.consumer:java8
au.com.dius.pact.consumer:specs2_2.13
au.com.dius.pact:pact-jvm-server
au.com.dius.pact:provider
au.com.dius.pact.provider:scalatest_2.13
au.com.dius.pact.provider:spring
au.com.dius.pact.provider:maven
au.com.dius.pact:provider
au.com.dius.pact.provider:junit
au.com.dius.pact.provider:junit5
au.com.dius.pact.provider:scalasupport_2.13
au.com.dius.pact.provider:lein
au.com.dius.pact.provider:gradle
au.com.dius.pact.provider:specs2_2.13
au.com.dius.pact.provider:junit5spring
au.com.dius.pact.core:support
au.com.dius.pact.core:model
au.com.dius.pact.core:matchers
au.com.dius.pact.core:pactbroker

Service Consumers

Pact-JVM has a number of ways you can write your service consumer tests.

I Use Scala

You want to look at: pact4s or scala-pact

I Use Java

You want to look at: junit for JUnit 4 tests and junit5 for JUnit 5 tests. Also, if you are using Java 11 or above, there is an updated DSL for consumer tests.

NOTE: If you are using Java 8, there is no separate Java 8 support library anymore, see the above library.

I Use Groovy or Grails

You want to look at: groovy or junit

(Use Clojure I)

Clojure can call out to Java, so have a look at junit. For an example look at example_clojure_consumer_pact_test.clj.

I Use some other jvm language or test framework

You want to look at: Consumer

My Consumer interacts with a Message Queue

As part of the V3 pact specification, we have defined a new pact file for interactions with message queues. For an implementation of a Groovy consumer test with a message pact, have a look at PactMessageBuilderSpec.groovy.

Service Providers

Once you have run your consumer tests, you will have generated some Pact files. You can then verify your service providers with these files.

I am writing a provider and want to ...

verify pacts with SBT

You want to look at: pact4s or scala-pact

verify pacts with Gradle

You want to look at: pact gradle plugin

verify pacts with Maven

You want to look at: pact maven plugin

verify pacts with JUnit tests

You want to look at: junit provider support for JUnit 4 tests and junit5 for JUnit 5 tests

verify pacts with Leiningen

You want to look at: pact leiningen plugin

verify pacts with a Spring MVC project

Have a look at spring or Spring MVC Pact Test Runner (Not maintained).

I want to verify pacts but don't want to use sbt or gradle or leiningen

You want to look at: provider

verify interactions with a message queue

As part of the V3 pact specification, we have defined a new pact file for interactions with message queues. The Gradle pact plugin supports a mechanism where you can verify V3 message pacts, have a look at pact gradle plugin. The JUnit pact library also supports verification of V3 message pacts, have a look at junit.

I Use Ruby or Go or something else

The pact-jvm libraries are pure jvm technologies and do not have any native dependencies.

However, if you have a ruby provider, the json produced by this library is compatible with the ruby pact library. You'll want to look at: Ruby Pact.

For .Net, there is Pact-net.

For JS, there is Pact-JS.

For Go, there is Pact-go.

For Rust, there is Pact-Rust.

Have a look at implementations in other languages.

I Use something completely different

There's a limit to how much we can help, however check out pact-jvm-server

How do I transport my pacts from consumers to providers?

You want to look at: Pact Broker

Which is a project that aims at providing tooling to coordinate pact generation and delivery between projects.

I want to contribute

Documentation for contributors is here.

Test Analytics

We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.