Download JAR files tagged by dpact with all dependencies

pact-jvm-consumer-junit5 ======================== JUnit 5 support for Pact consumer tests ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-junit5_2.12` * version-id = `3.6.x` ## Usage ### 1. Add the Pact consumer test extension to the test class. To write Pact consumer tests with JUnit 5, you need to add `@ExtendWith(PactConsumerTestExt)` to your test class. This replaces the `PactRunner` used for JUnit 4 tests. The rest of the test follows a similar pattern as for JUnit 4 tests. ```java @ExtendWith(PactConsumerTestExt.class) class ExampleJavaConsumerPactTest { ``` ### 2. create a method annotated with `@Pact` that returns the interactions for the test For each test (as with JUnit 4), you need to define a method annotated with the `@Pact` annotation that returns the interactions for the test. ```java @Pact(provider="ArticlesProvider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/articles.json") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` ### 3. Link the mock server with the interactions for the test with `@PactTestFor` Then the final step is to use the `@PactTestFor` annotation to tell the Pact extension how to setup the Pact test. You can either put this annotation on the test class, or on the test method. For examples see [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) and [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy). The `@PactTestFor` annotation allows you to control the mock server in the same way as the JUnit 4 `PactProviderRule`. It allows you to set the hostname to bind to (default is `localhost`) and the port (default is to use a random port). You can also set the Pact specification version to use (default is V3). ```java @ExtendWith(PactConsumerTestExt.class) @PactTestFor(providerName = "ArticlesProvider") public class ExampleJavaConsumerPactTest { ``` **NOTE on the hostname**: The mock server runs in the same JVM as the test, so the only valid values for hostname are: | hostname | result | | -------- | ------ | | `localhost` | binds to the address that localhost points to (normally the loopback adapter) | | `127.0.0.1` or `::1` | binds to the loopback adapter | | host name | binds to the default interface that the host machines DNS name resolves to | | `0.0.0.0` or `::` | binds to the all interfaces on the host machine | #### Matching the interactions by provider name If you set the `providerName` on the `@PactTestFor` annotation, then the first method with a `@Pact` annotation with the same provider name will be used. See [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) for an example. #### Matching the interactions by method name If you set the `pactMethod` on the `@PactTestFor` annotation, then the method with the provided name will be used (it still needs a `@Pact` annotation). See [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy) for an example. ### Injecting the mock server into the test You can get the mock server injected into the test method by adding a `MockServer` parameter to the test method. ```java @Test void test(MockServer mockServer) throws IOException { HttpResponse httpResponse = Request.Get(mockServer.getUrl() + "/articles.json").execute().returnResponse(); assertThat(httpResponse.getStatusLine().getStatusCode(), is(equalTo(200))); } ``` This helps with getting the base URL of the mock server, especially when a random port is used. ## Changing the directory pact files are written to By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.build.directory}</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` ### Using `@PactFolder` annotation [3.6.2+] You can override the directory the pacts are written in a test by adding the `@PactFolder` annotation to the test class. ## Forcing pact files to be overwritten (3.6.5+) By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. ## Unsupported The current implementation does not support tests with multiple providers. This will be added in a later release. # Having values injected from provider state callbacks (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods all you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/${id}", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ```

pact-jvm-consumer-junit5 ======================== JUnit 5 support for Pact consumer tests ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-junit5` * version-id = `4.0.x` ## Usage ### 1. Add the Pact consumer test extension to the test class. To write Pact consumer tests with JUnit 5, you need to add `@ExtendWith(PactConsumerTestExt)` to your test class. This replaces the `PactRunner` used for JUnit 4 tests. The rest of the test follows a similar pattern as for JUnit 4 tests. ```java @ExtendWith(PactConsumerTestExt.class) class ExampleJavaConsumerPactTest { ``` ### 2. create a method annotated with `@Pact` that returns the interactions for the test For each test (as with JUnit 4), you need to define a method annotated with the `@Pact` annotation that returns the interactions for the test. ```java @Pact(provider="ArticlesProvider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/articles.json") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` ### 3. Link the mock server with the interactions for the test with `@PactTestFor` Then the final step is to use the `@PactTestFor` annotation to tell the Pact extension how to setup the Pact test. You can either put this annotation on the test class, or on the test method. For examples see [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) and [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy). The `@PactTestFor` annotation allows you to control the mock server in the same way as the JUnit 4 `PactProviderRule`. It allows you to set the hostname to bind to (default is `localhost`) and the port (default is to use a random port). You can also set the Pact specification version to use (default is V3). ```java @ExtendWith(PactConsumerTestExt.class) @PactTestFor(providerName = "ArticlesProvider") public class ExampleJavaConsumerPactTest { ``` **NOTE on the hostname**: The mock server runs in the same JVM as the test, so the only valid values for hostname are: | hostname | result | | -------- | ------ | | `localhost` | binds to the address that localhost points to (normally the loopback adapter) | | `127.0.0.1` or `::1` | binds to the loopback adapter | | host name | binds to the default interface that the host machines DNS name resolves to | | `0.0.0.0` or `::` | binds to the all interfaces on the host machine | #### Matching the interactions by provider name If you set the `providerName` on the `@PactTestFor` annotation, then the first method with a `@Pact` annotation with the same provider name will be used. See [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) for an example. #### Matching the interactions by method name If you set the `pactMethod` on the `@PactTestFor` annotation, then the method with the provided name will be used (it still needs a `@Pact` annotation). See [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy) for an example. ### Injecting the mock server into the test You can get the mock server injected into the test method by adding a `MockServer` parameter to the test method. ```java @Test void test(MockServer mockServer) throws IOException { HttpResponse httpResponse = Request.Get(mockServer.getUrl() + "/articles.json").execute().returnResponse(); assertThat(httpResponse.getStatusLine().getStatusCode(), is(equalTo(200))); } ``` This helps with getting the base URL of the mock server, especially when a random port is used. ## Changing the directory pact files are written to By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.build.directory}</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` ### Using `@PactFolder` annotation You can override the directory the pacts are written in a test by adding the `@PactFolder` annotation to the test class. ## Forcing pact files to be overwritten (3.6.5+) By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. ## Unsupported The current implementation does not support tests with multiple providers. This will be added in a later release. # Having values injected from provider state callbacks (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods all you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/${id}", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ```

Maven plugin to verify a provider ================================= Maven plugin for verifying pacts against a provider. The Maven plugin provides a `verify` goal which will verify all configured pacts against your provider. ## To Use It ### 1. Add the pact-jvm-provider-maven plugin to your `build` section of your pom file. ```xml <build> [...] <plugins> [...] <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> </plugin> [...] </plugins> [...] </build> ``` ### 2. Define the pacts between your consumers and providers You define all the providers and consumers within the configuration element of the maven plugin. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <consumers> <!-- Again, you can define as many consumers for each provider as you need, but each must have a unique name --> <consumer> <name>consumer1</name> <!-- currently supports a file path using pactFile or a URL using pactUrl --> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### 3. Execute `mvn pact:verify` You will have to have your provider running for this to pass. ## Verifying all pact files in a directory for a provider You can specify a directory that contains pact files, and the Pact plugin will scan for all pact files that match that provider and define a consumer for each pact file in the directory. Consumer name is read from contents of pact file. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <pactFileDirectory>path/to/pacts</pactFileDirectory> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying all pact files from multiple directories for a provider [3.5.18+] If you want to specify multiple directories, you can use `pactFileDirectories`. The plugin will only fail the build if no pact files are loaded after processing all the directories in the list. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.18</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectories> <pactFileDirectory>path/to/pacts1</pactFileDirectory> <pactFileDirectory>path/to/pacts2</pactFileDirectory> </pactFileDirectories> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## 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</insecure>` on the provider. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <insecure>true</insecure> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Specifying a custom trust store For environments that are running their own certificate chains: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <trustStore>relative/path/to/trustStore.jks</trustStore> <trustStorePassword>changeit</trustStorePassword> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` `trustStore` is either relative to the current working (build) directory. `trustStorePassword` 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 Pact Maven plugin provides a request filter that can be set to a Groovy script on the provider that will be called before the request is made. This script will receive the HttpRequest bound to a variable named `request` prior to it being executed. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <requestFilter> // This is a Groovy script that adds an Authorization header to each request request.addHeader('Authorization', 'oauth-token eyJhbGciOiJSUzI1NiIsIm...') </requestFilter> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` __*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 closure assigned to createClient on the provider that returns a CloseableHttpClient. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <createClient> // This is a Groovy script that will enable the client to accept self-signed certificates import org.apache.http.ssl.SSLContextBuilder import org.apache.http.conn.ssl.NoopHostnameVerifier import org.apache.http.impl.client.HttpClients HttpClients.custom().setSSLHostnameVerifier(new NoopHostnameVerifier()) .setSslcontext(new SSLContextBuilder().loadTrustMaterial(null, { x509Certificates, s -> true }) .build()) .build() </createClient> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Turning off URL decoding of the paths in the pact file 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 properties can be specified with `-Dproperty=value` on the command line or in the configuration section: |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| |pact.filter.consumers|Comma separated 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 in the configuration section: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <configuration> <pact.showStacktrace>true</pact.showStacktrace> </configuration> </configuration> </plugin> ``` ## 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 and parameters from the pact file before each interaction via a POST. The stateChangeUsesBody controls if the state is passed in the request body or as query parameters. These values can be set at the provider level, or for a specific consumer. Consumer values take precedent if both are given. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> <stateChangeUrl>http://localhost:8080/tasks/pactStateChangeForConsumer1</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` If the `stateChangeUsesBody` is not specified, or is set to true, then the provider state description and parameters will be sent as JSON in the body of the request. If it is set to false, they will passed as query parameters. As for normal requests (see Modifying the requests before they are sent), a state change request can be modified before it is sent. Set `stateChangeRequestFilter` to a Groovy script on the provider that will be called before the request is made. #### Teardown calls for state changes You can enable teardown state change calls by setting the property `<stateChangeTeardown>true</stateChangeTeardown>` on the provider. This will add an `action` parameter to the state change call. The setup call before the test will receive `action=setup`, and then a teardown call will be made afterwards to the state change URL with `action=teardown`. ## Verifying pact files from a pact broker You can setup your build to validate against the pacts stored in a pact broker. The pact plugin will query the pact broker for all consumers that have a pact with the provider based on its name. To use it, just configure the `pactBrokerUrl` or `pactBroker` value for the provider with the base URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBrokerUrl>http://pact-broker:5000/</pactBrokerUrl> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an authenticated pact broker If your pact broker requires authentication (basic authentication is only supported), you can configure the username and password to use by configuring the `authentication` element of the `pactBroker` element of your provider. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <authentication> <username>test</username> <password>test</password> </authentication> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` #### Using the Maven servers configuration [version 3.5.6+] From version 3.5.6, you can use the servers setup in the Maven settings. To do this, setup a server as per the [Maven Server Settings](https://maven.apache.org/settings.html#Servers). Then set the server ID in the pact broker configuration in your POM. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.6</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <serverId>test-pact-broker</serverId> <!-- This must match the server id in the maven settings --> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an pact broker that match particular tags If your pacts in your pact broker have been tagged, you can set the tags to fetch by configuring the `tags` element of the `pactBroker` element of your provider. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <tags> <tag>TEST</tag> <tag>DEV</tag> </tags> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` This example will fetch and validate the pacts for the TEST and DEV tags. ## 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 `-Dpact.filter.consumers=consumer1,consumer2` to the command line or configuration section will only run the pact files for those consumers (consumer1 and consumer2). Adding `-Dpact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `-Dpact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `-Dpact.filter.providerState=` will match any interaction that does not have a provider state. ## Not failing the build if no pact files are found [version 3.5.19+] By default, if there are no pact files to verify, the plugin will raise an exception. This is to guard against false positives where the build is passing but nothing has been verified due to mis-configuration. To disable this behaviour, set the `failIfNoPactsFound` parameter to `false`. # Verifying a message provider The Maven plugin has been updated to allow invoking test methods that can return the message contents from a message producer. To use it, set the way to invoke the verification to `ANNOTATED_METHOD`. This will allow the pact verification task to scan for test methods that return the message contents. Add something like the following to your maven pom file: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <!-- packagesToScan is optional, but leaving it out will result in the entire test classpath being scanned. Set it to the packages where your annotated test method can be found. --> <packagesToScan> <packageToScan>au.com.example.messageprovider.*</packageToScan> </packagesToScan> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` Now when the pact verify task is run, will look for methods annotated with `@PactVerifyProvider` in the test classpath that have a matching description to what is in the pact file. ```groovy class ConfirmationKafkaMessageBuilderTest { @PactVerifyProvider('an order confirmation message') String verifyMessageForOrder() { Order order = new Order() order.setId(10000004) order.setExchange('ASX') order.setSecurityCode('CBA') order.setPrice(BigDecimal.TEN) order.setUnits(15) order.setGst(new BigDecimal('15.0')) odrer.setFees(BigDecimal.TEN) def message = new ConfirmationKafkaMessageBuilder() .withOrder(order) .build() JsonOutput.toJson(message) } } ``` It will then validate that the returned contents matches the contents for the message in the pact file. ## Changing the class path that is scanned By default, the test classpath is scanned for annotated methods. You can override this by setting the `classpathElements` property: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <classpathElements> <classpathElement> build/classes/test </classpathElement> </classpathElements> </configuration> </plugin> ``` # Publishing pact files to a pact broker The pact maven plugin provides a `publish` mojo that can publish all pact files in a directory to a pact broker. To use it, you need to add a publish configuration to the POM that defines the directory where the pact files are and the URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts --> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} --> <trimSnapshot>true</trimSnapshot> <!-- Defaults to false --> </configuration> </plugin> ``` You can now execute `mvn pact:publish` to publish the pact files. _NOTE:_ The pact broker requires a version for all published pacts. The `publish` task will use the version of the project by default, but can be overwritten with the `projectVersion` property. Make sure you have set one otherwise the broker will reject the pact files. _NOTE_: By default, the pact broker has issues parsing `SNAPSHOT` versions. You can configure the publisher to automatically remove `-SNAPSHOT` from your version number by setting `trimSnapshot` to true. This setting does not modify non-snapshot versions. You can set any tags that the pacts should be published with by setting the `tags` list property (version 3.5.12+). A common use of this is setting the tag to the current source control branch. This supports using pact with feature branches. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.12</version> <configuration> <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts --> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} --> <tags> <tag>feature/feature_name</tag> </tags> </configuration> </plugin> ``` ## Publishing to an authenticated pact broker For an authenticated pact broker, you can pass in the credentials with the `pactBrokerUsername` and `pactBrokerPassword` properties. Currently it only supports basic authentication. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerUsername>USERNAME</pactBrokerUsername> <pactBrokerPassword>PASSWORD</pactBrokerPassword> </configuration> </plugin> ``` #### Using the Maven servers configuration [version 3.5.6+] From version 3.5.6, you can use the servers setup in the Maven settings. To do this, setup a server as per the [Maven Server Settings](https://maven.apache.org/settings.html#Servers). Then set the server ID in the pact broker configuration in your POM. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.5.19</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerServerId>test-pact-broker</pactBrokerServerId> <!-- This must match the server id in the maven settings --> </configuration> </plugin> ``` ## Excluding pacts from being published [version 3.5.19+] You can exclude some of the pact files from being published by providing a list of regular expressions that match against the base names of the pact files. For example: ```groovy pact { publish { pactBrokerUrl = 'https://mypactbroker.com' excludes = [ '.*\\-\\d+$' ] // exclude all pact files that end with a dash followed by a number in the name } } ``` ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.19</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <excludes> <exclude>.*\\-\\d+$</exclude> <!-- exclude pact files where the name ends in a dash followed by a number --> </excludes> </configuration> </plugin> ``` # Publishing verification results to a Pact Broker [version 3.5.4+] For pacts that are loaded from a Pact Broker, the results of running the verification can be published back to the broker against the URL for the pact. You will be able to then see the result on the Pact Broker home screen. To turn on the verification publishing, set the system property `pact.verifier.publishResults` to `true` in the pact maven plugin, not surefire, configuration. # Enabling other verification reports [version 3.5.20+] By default the verification report is written to the console. You can also enable a JSON or Markdown report by setting the `reports` configuration list. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.20</version> <configuration> <reports> <report>console</report> <report>json</report> <report>markdown</report> </reports> </configuration> </plugin> ``` These reports will be written to `target/reports/pact`.

Maven plugin to verify a provider [version 2.1.9+] ================================================== Maven plugin for verifying pacts against a provider. The Maven plugin provides a `verify` goal which will verify all configured pacts against your provider. ## To Use It ### 1. Add the pact-jvm-provider-maven plugin to your `build` section of your pom file. ```xml <build> [...] <plugins> [...] <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> </plugin> [...] </plugins> [...] </build> ``` ### 2. Define the pacts between your consumers and providers You define all the providers and consumers within the configuration element of the maven plugin. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <consumers> <!-- Again, you can define as many consumers for each provider as you need, but each must have a unique name --> <consumer> <name>consumer1</name> <!-- currently supports a file path using pactFile or a URL using pactUrl --> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### 3. Execute `mvn pact:verify` You will have to have your provider running for this to pass. ## Verifying all pact files in a directory for a provider. [2.1.10+] You can specify a directory that contains pact files, and the Pact plugin will scan for all pact files that match that provider and define a consumer for each pact file in the directory. Consumer name is read from contents of pact file. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <pactFileDirectory>path/to/pacts</pactFileDirectory> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Enabling insecure SSL [version 2.2.8+] For providers that are running on SSL with self-signed certificates, you need to enable insecure SSL mode by setting `<insecure>true</insecure>` on the provider. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <insecure>true</insecure> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Specifying a custom trust store [version 2.2.8+] For environments that are running their own certificate chains: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <trustStore>relative/path/to/trustStore.jks</trustStore> <trustStorePassword>changeit</trustStorePassword> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` `trustStore` is either relative to the current working (build) directory. `trustStorePassword` 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 Pact Maven plugin provides a request filter that can be set to a Groovy script on the provider that will be called before the request is made. This script will receive the HttpRequest bound to a variable named `request` prior to it being executed. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <requestFilter> // This is a Groovy script that adds an Authorization header to each request request.addHeader('Authorization', 'oauth-token eyJhbGciOiJSUzI1NiIsIm...') </requestFilter> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` __*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 [version 2.2.4+] 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 closure assigned to createClient on the provider that returns a CloseableHttpClient. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <createClient> // This is a Groovy script that will enable the client to accept self-signed certificates import org.apache.http.ssl.SSLContextBuilder import org.apache.http.conn.ssl.NoopHostnameVerifier import org.apache.http.impl.client.HttpClients HttpClients.custom().setSSLHostnameVerifier(new NoopHostnameVerifier()) .setSslcontext(new SSLContextBuilder().loadTrustMaterial(null, { x509Certificates, s -> true }) .build()) .build() </createClient> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## 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 properties can be specified with `-Dproperty=value` on the command line or in the configuration section: |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| Example in the configuration section: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <configuration> <pact.showStacktrace>true</pact.showStacktrace> </configuration> </configuration> </plugin> ``` ## 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 stateChangeUsesBody 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. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> <stateChangeUrl>http://localhost:8080/tasks/pactStateChangeForConsumer1</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` If the `stateChangeUsesBody` 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 `stateChangeRequestFilter` to a Groovy script on the provider that will be called before the request is made. #### Teardown calls for state changes [version 3.2.5/2.4.7+] You can enable teardown state change calls by setting the property `<stateChangeTeardown>true</stateChangeTeardown>` on the provider. This will add an `action` parameter to the state change call. The setup call before the test will receive `action=setup`, and then a teardown call will be made afterwards to the state change URL with `action=teardown`. ## Verifying pact files from a pact broker [version 3.1.1+/2.3.1+] You can setup your build to validate against the pacts stored in a pact broker. The pact plugin will query the pact broker for all consumers that have a pact with the provider based on its name. To use it, just configure the `pactBrokerUrl` or `pactBroker` value for the provider with the base URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBrokerUrl>http://pact-broker:5000/</pactBrokerUrl> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an authenticated pact broker [version 3.3.5+] If your pact broker requires authentication (basic authentication is only supported), you can configure the username and password to use by configuring the `authentication` element of the `pactBroker` element of your provider. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <authentication> <username>test</username> <password>test</password> </authentication> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an pact broker that match particular tags [version 3.3.5+] If your pacts in your pact broker have been tagged, you can set the tags to fetch by configuring the `tags` element of the `pactBroker` element of your provider. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <tags> <tag>TEST</tag> <tag>DEV</tag> </tags> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` This example will fetch and validate the pacts for the TEST and DEV tags. ## 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 `-Dpact.filter.consumers=consumer1,consumer2` to the command line or configuration section will only run the pact files for those consumers (consumer1 and consumer2). Adding `-Dpact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `-Dpact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `-Dpact.filter.providerState=` will match any interaction that does not have a provider state. # Verifying a message provider [version 2.2.12+] The Maven plugin has been updated to allow invoking test methods that can return the message contents from a message producer. To use it, set the way to invoke the verification to `ANNOTATED_METHOD`. This will allow the pact verification task to scan for test methods that return the message contents. Add something like the following to your maven pom file: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <!-- packagesToScan is optional, but leaving it out will result in the entire test classpath being scanned. Set it to the packages where your annotated test method can be found. --> <packagesToScan> <packageToScan>au.com.example.messageprovider.*</packageToScan> </packagesToScan> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` Now when the pact verify task is run, will look for methods annotated with `@PactVerifyProvider` in the test classpath that have a matching description to what is in the pact file. ```groovy class ConfirmationKafkaMessageBuilderTest { @PactVerifyProvider('an order confirmation message') String verifyMessageForOrder() { Order order = new Order() order.setId(10000004) order.setExchange('ASX') order.setSecurityCode('CBA') order.setPrice(BigDecimal.TEN) order.setUnits(15) order.setGst(new BigDecimal('15.0')) odrer.setFees(BigDecimal.TEN) def message = new ConfirmationKafkaMessageBuilder() .withOrder(order) .build() JsonOutput.toJson(message) } } ``` It will then validate that the returned contents matches the contents for the message in the pact file. ## Changing the class path that is scanned By default, the test classpath is scanned for annotated methods. You can override this by setting the `classpathElements` property: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <classpathElements> <classpathElement> build/classes/test </classpathElement> </classpathElements> </configuration> </plugin> ``` # Publishing pact files to a pact broker [version 3.2.0+] The pact maven plugin provides a `publish` mojo that can publish all pact files in a directory to a pact broker. To use it, you need to add a publish configuration to the POM that defines the directory where the pact files are and the URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.8</version> <configuration> <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts --> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} --> <trimSnapshot>true</trimSnapshot> <!-- Defaults to false --> </configuration> </plugin> ``` You can now execute `mvn pact:publish` to publish the pact files. _NOTE:_ The pact broker requires a version for all published pacts. The `publish` task will use the version of the project by default, but can be overwritten with the `projectVersion` property. Make sure you have set one otherwise the broker will reject the pact files. _NOTE_: By default, the pact broker has issues parsing `SNAPSHOT` versions. You can configure the publisher to automatically remove `-SNAPSHOT` from your version number by setting `trimSnapshot` to true. This setting does not modify non-snapshot versions. ## Publishing to an authenticated pact broker [version 3.3.9+] For an authenticated pact broker, you can pass in the credentials with the `pactBrokerUsername` and `pactBrokerPassword` properties. Currently it only supports basic authentication. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.3.9</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerUsername>USERNAME</pactBrokerUsername> <pactBrokerPassword>PASSWORD</pactBrokerPassword> </configuration> </plugin> ```

Maven plugin to verify a provider ================================= Maven plugin for verifying pacts against a provider. The Maven plugin provides a `verify` goal which will verify all configured pacts against your provider. ## To Use It ### 1. Add the pact-jvm-provider-maven plugin to your `build` section of your pom file. ```xml <build> [...] <plugins> [...] <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> </plugin> [...] </plugins> [...] </build> ``` ### 2. Define the pacts between your consumers and providers You define all the providers and consumers within the configuration element of the maven plugin. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <consumers> <!-- Again, you can define as many consumers for each provider as you need, but each must have a unique name --> <consumer> <name>consumer1</name> <!-- currently supports a file path using pactFile or a URL using pactUrl --> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### 3. Execute `mvn pact:verify` You will have to have your provider running for this to pass. ## Verifying all pact files in a directory for a provider You can specify a directory that contains pact files, and the Pact plugin will scan for all pact files that match that provider and define a consumer for each pact file in the directory. Consumer name is read from contents of pact file. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <pactFileDirectory>path/to/pacts</pactFileDirectory> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying all pact files from multiple directories for a provider [3.5.18+] If you want to specify multiple directories, you can use `pactFileDirectories`. The plugin will only fail the build if no pact files are loaded after processing all the directories in the list. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.18</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectories> <pactFileDirectory>path/to/pacts1</pactFileDirectory> <pactFileDirectory>path/to/pacts2</pactFileDirectory> </pactFileDirectories> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## 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</insecure>` on the provider. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <insecure>true</insecure> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Specifying a custom trust store For environments that are running their own certificate chains: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <trustStore>relative/path/to/trustStore.jks</trustStore> <trustStorePassword>changeit</trustStorePassword> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` `trustStore` is either relative to the current working (build) directory. `trustStorePassword` 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 Pact Maven plugin provides a request filter that can be set to a Groovy script on the provider that will be called before the request is made. This script will receive the HttpRequest bound to a variable named `request` prior to it being executed. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <requestFilter> // This is a Groovy script that adds an Authorization header to each request request.addHeader('Authorization', 'oauth-token eyJhbGciOiJSUzI1NiIsIm...') </requestFilter> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` __*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 closure assigned to createClient on the provider that returns a CloseableHttpClient. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <createClient> // This is a Groovy script that will enable the client to accept self-signed certificates import org.apache.http.ssl.SSLContextBuilder import org.apache.http.conn.ssl.NoopHostnameVerifier import org.apache.http.impl.client.HttpClients HttpClients.custom().setSSLHostnameVerifier(new NoopHostnameVerifier()) .setSslcontext(new SSLContextBuilder().loadTrustMaterial(null, { x509Certificates, s -> true }) .build()) .build() </createClient> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Turning off URL decoding of the paths in the pact file 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 properties can be specified with `-Dproperty=value` on the command line or in the configuration section: |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| |pact.filter.consumers|Comma separated 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`| |pact.verifier.disableUrlPathDecoding|Disables decoding of request paths| |pact.pactbroker.httpclient.usePreemptiveAuthentication|Enables preemptive authentication with the pact broker when set to `true`| |`pact.consumer.tags`|Overrides the tags used when publishing pacts [version 4.0.7+]| Example in the configuration section: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <configuration> <pact.showStacktrace>true</pact.showStacktrace> </configuration> </configuration> </plugin> ``` ## 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 and parameters from the pact file before each interaction via a POST. The stateChangeUsesBody controls if the state is passed in the request body or as query parameters. These values can be set at the provider level, or for a specific consumer. Consumer values take precedent if both are given. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> <stateChangeUrl>http://localhost:8080/tasks/pactStateChangeForConsumer1</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` If the `stateChangeUsesBody` is not specified, or is set to true, then the provider state description and parameters will be sent as JSON in the body of the request. If it is set to false, they will passed as query parameters. As for normal requests (see Modifying the requests before they are sent), a state change request can be modified before it is sent. Set `stateChangeRequestFilter` to a Groovy script on the provider that will be called before the request is made. #### Teardown calls for state changes You can enable teardown state change calls by setting the property `<stateChangeTeardown>true</stateChangeTeardown>` on the provider. This will add an `action` parameter to the state change call. The setup call before the test will receive `action=setup`, and then a teardown call will be made afterwards to the state change URL with `action=teardown`. #### Returning values that can be injected (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. There are methods on the consumer DSLs that can provider an expression that contains variables (like '/api/user/${id}' for the path). The provider state callback can then return a map for values, and the `id` attribute from the map will be expanded in the expression. For URL callbacks, the values need to be returned as JSON in the response body. ## Verifying pact files from a pact broker You can setup your build to validate against the pacts stored in a pact broker. The pact plugin will query the pact broker for all consumers that have a pact with the provider based on its name. To use it, just configure the `pactBrokerUrl` or `pactBroker` value for the provider with the base URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBrokerUrl>http://pact-broker:5000/</pactBrokerUrl> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an authenticated pact broker If your pact broker requires authentication (basic authentication is only supported), you can configure the username and password to use by configuring the `authentication` element of the `pactBroker` element of your provider. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <authentication> <username>test</username> <password>test</password> </authentication> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` Preemptive Authentication can be enabled by setting the `pact.pactbroker.httpclient.usePreemptiveAuthentication` Java system property to `true`. #### Using the Maven servers configuration [version 3.5.6+] From version 3.5.6, you can use the servers setup in the Maven settings. To do this, setup a server as per the [Maven Server Settings](https://maven.apache.org/settings.html#Servers). Then set the server ID in the pact broker configuration in your POM. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.6</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <serverId>test-pact-broker</serverId> <!-- This must match the server id in the maven settings --> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an pact broker that match particular tags If your pacts in your pact broker have been tagged, you can set the tags to fetch by configuring the `tags` element of the `pactBroker` element of your provider. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <tags> <tag>TEST</tag> <tag>DEV</tag> </tags> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` This example will fetch and validate the pacts for the TEST and DEV tags. ## 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 `-Dpact.filter.consumers=consumer1,consumer2` to the command line or configuration section will only run the pact files for those consumers (consumer1 and consumer2). Adding `-Dpact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `-Dpact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `-Dpact.filter.providerState=` will match any interaction that does not have a provider state. ## Not failing the build if no pact files are found [version 3.5.19+] By default, if there are no pact files to verify, the plugin will raise an exception. This is to guard against false positives where the build is passing but nothing has been verified due to mis-configuration. To disable this behaviour, set the `failIfNoPactsFound` parameter to `false`. # Verifying a message provider The Maven plugin has been updated to allow invoking test methods that can return the message contents from a message producer. To use it, set the way to invoke the verification to `ANNOTATED_METHOD`. This will allow the pact verification task to scan for test methods that return the message contents. Add something like the following to your maven pom file: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <!-- packagesToScan is optional, but leaving it out will result in the entire test classpath being scanned. Set it to the packages where your annotated test method can be found. --> <packagesToScan> <packageToScan>au.com.example.messageprovider.*</packageToScan> </packagesToScan> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` Now when the pact verify task is run, will look for methods annotated with `@PactVerifyProvider` in the test classpath that have a matching description to what is in the pact file. ```groovy class ConfirmationKafkaMessageBuilderTest { @PactVerifyProvider('an order confirmation message') String verifyMessageForOrder() { Order order = new Order() order.setId(10000004) order.setExchange('ASX') order.setSecurityCode('CBA') order.setPrice(BigDecimal.TEN) order.setUnits(15) order.setGst(new BigDecimal('15.0')) odrer.setFees(BigDecimal.TEN) def message = new ConfirmationKafkaMessageBuilder() .withOrder(order) .build() JsonOutput.toJson(message) } } ``` It will then validate that the returned contents matches the contents for the message in the pact file. ## Changing the class path that is scanned By default, the test classpath is scanned for annotated methods. You can override this by setting the `classpathElements` property: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <classpathElements> <classpathElement> build/classes/test </classpathElement> </classpathElements> </configuration> </plugin> ``` # Publishing pact files to a pact broker The pact maven plugin provides a `publish` mojo that can publish all pact files in a directory to a pact broker. To use it, you need to add a publish configuration to the POM that defines the directory where the pact files are and the URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts --> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} --> <trimSnapshot>true</trimSnapshot> <!-- Defaults to false --> </configuration> </plugin> ``` You can now execute `mvn pact:publish` to publish the pact files. _NOTE:_ The pact broker requires a version for all published pacts. The `publish` task will use the version of the project by default, but can be overwritten with the `projectVersion` property. Make sure you have set one otherwise the broker will reject the pact files. _NOTE_: By default, the pact broker has issues parsing `SNAPSHOT` versions. You can configure the publisher to automatically remove `-SNAPSHOT` from your version number by setting `trimSnapshot` to true. This setting does not modify non-snapshot versions. You can set any tags that the pacts should be published with by setting the `tags` list property (version 3.5.12+). A common use of this is setting the tag to the current source control branch. This supports using pact with feature branches. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.12</version> <configuration> <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts --> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} --> <tags> <tag>feature/feature_name</tag> </tags> </configuration> </plugin> ``` You can also specify the tags using the `pact.consumer.tags` Java system property [version 4.0.7+]. ## Publishing to an authenticated pact broker For an authenticated pact broker, you can pass in the credentials with the `pactBrokerUsername` and `pactBrokerPassword` properties. Currently it only supports basic authentication. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerUsername>USERNAME</pactBrokerUsername> <pactBrokerPassword>PASSWORD</pactBrokerPassword> </configuration> </plugin> ``` Or to use a bearer token: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerToken>TOKEN</pactBrokerToken> <!-- Replace TOKEN with the actual token --> <pactBrokerAuthenticationScheme>Bearer</pactBrokerAuthenticationScheme> </configuration> </plugin> ``` #### Using the Maven servers configuration [version 3.5.6+] From version 3.5.6, you can use the servers setup in the Maven settings. To do this, setup a server as per the [Maven Server Settings](https://maven.apache.org/settings.html#Servers). Then set the server ID in the pact broker configuration in your POM. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.11</artifactId> <version>3.5.19</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerServerId>test-pact-broker</pactBrokerServerId> <!-- This must match the server id in the maven settings --> </configuration> </plugin> ``` ## Excluding pacts from being published [version 3.5.19+] You can exclude some of the pact files from being published by providing a list of regular expressions that match against the base names of the pact files. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.19</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <excludes> <exclude>.*\\-\\d+$</exclude> <!-- exclude pact files where the name ends in a dash followed by a number --> </excludes> </configuration> </plugin> ``` # Publishing verification results to a Pact Broker [version 3.5.4+] For pacts that are loaded from a Pact Broker, the results of running the verification can be published back to the broker against the URL for the pact. You will be able to then see the result on the Pact Broker home screen. To turn on the verification publishing, set the system property `pact.verifier.publishResults` to `true` in the pact maven plugin, not surefire, configuration. # Enabling other verification reports [version 3.5.20+] By default the verification report is written to the console. You can also enable a JSON or Markdown report by setting the `reports` configuration list. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.20</version> <configuration> <reports> <report>console</report> <report>json</report> <report>markdown</report> </reports> </configuration> </plugin> ``` These reports will be written to `target/reports/pact`.

pact-jvm-consumer-junit ======================= Provides a DSL and a base test class for use with Junit to build consumer tests. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-junit_2.12` * version-id = `3.5.x` ## Usage ### Using the base ConsumerPactTest To write a pact spec extend ConsumerPactTest. This base class defines the following four methods which must be overridden in your test class. * *providerName:* Returns the name of the API provider that Pact will mock * *consumerName:* Returns the name of the API consumer that we are testing. * *createFragment:* Returns the PactFragment containing the interactions that the test setup using the ConsumerPactBuilder DSL * *runTest:* The actual test run. It receives the URL to the mock server as a parameter. Here is an example: ```java import au.com.dius.pact.consumer.dsl.PactDslWithProvider; import au.com.dius.pact.consumer.exampleclients.ConsumerClient; import au.com.dius.pact.consumer.ConsumerPactTest; import au.com.dius.pact.model.PactFragment; import org.junit.Assert; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static org.junit.Assert.assertEquals; public class ExampleJavaConsumerPactTest extends ConsumerPactTest { @Override protected RequestResponsePact createFragment(PactDslWithProvider builder) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); return builder .given("test state") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/") .method("GET") .headers(headers) .willRespondWith() .status(200) .headers(headers) .body("{\"responsetest\": true, \"name\": \"harry\"}") .given("test state 2") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest second test interaction") .method("OPTIONS") .headers(headers) .path("/second") .body("") .willRespondWith() .status(200) .headers(headers) .body("") .toPact(); } @Override protected String providerName() { return "test_provider"; } @Override protected String consumerName() { return "test_consumer"; } @Override protected void runTest(MockServer mockServer, PactTestExecutionContext context) throws IOException { Assert.assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 200); Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); expectedResponse.put("name", "harry"); assertEquals(new ConsumerClient(mockServer.getUrl()).getAsMap("/", ""), expectedResponse); assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 200); } } ``` ### Using the Pact JUnit Rule Thanks to [@warmuuh](https://github.com/warmuuh) we have a JUnit rule that simplifies running Pact consumer tests. To use it, create a test class and then add the rule: #### 1. Add the Pact Rule to your test class to represent your provider. ```java @Rule public PactProviderRule mockProvider = new PactProviderRule("test_provider", "localhost", 8080, this); ``` The hostname and port are optional. If left out, it will default to 127.0.0.1 and a random available port. You can get the URL and port from the pact provider rule. #### 2. Annotate a method with Pact that returns a pact fragment for the provider and consumer ```java @Pact(provider="test_provider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` ##### Versions 3.0.2/2.2.13+ You can leave the provider name out. It will then use the provider name of the first mock provider found. I.e., ```java @Pact(consumer="test_consumer") // will default to the provider name from mockProvider public RequestResponsePact createFragment(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` #### 3. Annotate your test method with PactVerification to have it run in the context of the mock server setup with the appropriate pact from step 1 and 2 ```java @Test @PactVerification("test_provider") public void runTest() { Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient(mockProvider.getUrl()).get("/"), expectedResponse); } ``` ##### Versions 3.0.2/2.2.13+ You can leave the provider name out. It will then use the provider name of the first mock provider found. I.e., ```java @Test @PactVerification public void runTest() { // This will run against mockProvider Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient("http://localhost:8080").get("/"), expectedResponse); } ``` For an example, have a look at [ExampleJavaConsumerPactRuleTest](src/test/java/au/com/dius/pact/consumer/examples/ExampleJavaConsumerPactRuleTest.java) ### Requiring a test with multiple providers The Pact Rule can be used to test with multiple providers. Just add a rule to the test class for each provider, and then include all the providers required in the `@PactVerification` annotation. For an example, look at [PactMultiProviderTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactMultiProviderTest.java). Note that if more than one provider fails verification for the same test, you will only receive a failure for one of them. Also, to have multiple tests in the same test class, the providers must be setup with random ports (i.e. don't specify a hostname and port). Also, if the provider name is left out of any of the annotations, the first one found will be used (which may not be the first one defined). ### Requiring the mock server to run with HTTPS [versions 3.2.7/2.4.9+] From versions 3.2.7/2.4.9+ the mock server can be started running with HTTPS using a self-signed certificate instead of HTTP. To enable this set the `https` parameter to `true`. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, PactSpecVersion.V2, this); // ^^^^ ``` For an example test doing this, see [PactProviderHttpsTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderHttpsTest.java). **NOTE:** The provider will start handling HTTPS requests using a self-signed certificate. Most HTTP clients will not accept connections to a self-signed server as the certificate is untrusted. You may need to enable insecure HTTPS with your client for this test to work. For an example of how to enable insecure HTTPS client connections with Apache Http Client, have a look at [InsecureHttpsRequest](src/test/java/org/apache/http/client/fluent/InsecureHttpsRequest.java). ### Requiring the mock server to run with HTTPS with a keystore [versions 3.4.1+] From versions 3.4.1+ the mock server can be started running with HTTPS using a keystore. To enable this set the `https` parameter to `true`, set the keystore path/file, and the keystore's password. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, "/path/to/your/keystore.jks", "your-keystore-password", PactSpecVersion.V2, this); ``` For an example test doing this, see [PactProviderHttpsKeystoreTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderHttpsKeystoreTest.java). ### Setting default expected request and response values [versions 3.5.10+] If you have a lot of tests that may share some values (like headers), you can setup default values that will be applied to all the expected requests and responses for the tests. To do this, you need to create a method that takes single parameter of the appropriate type (`PactDslRequestWithoutPath` or `PactDslResponse`) and annotate it with the default marker annotation (`@DefaultRequestValues` or `@DefaultResponseValues`). For example: ```java @DefaultRequestValues public void defaultRequestValues(PactDslRequestWithoutPath request) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); request.headers(headers); } @DefaultResponseValues public void defaultResponseValues(PactDslResponse response) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testresheader", "testresheadervalue"); response.headers(headers); } ``` For an example test that uses these, have a look at [PactProviderWithMultipleFragmentsTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderWithMultipleFragmentsTest.java) ### Note on HTTP clients and persistent connections Some HTTP clients may keep the connection open, based on the live connections settings or if they use a connection cache. This could cause your tests to fail if the client you are testing lives longer than an individual test, as the mock server will be started and shutdown for each test. This will result in the HTTP client connection cache having invalid connections. For an example of this where the there was a failure for every second test, see [Issue #342](https://github.com/DiUS/pact-jvm/issues/342). ### Using the Pact DSL directly Sometimes it is not convenient to use the ConsumerPactTest as it only allows one test per test class. The DSL can be used directly in this case. Example: ```java import au.com.dius.pact.consumer.ConsumerPactBuilder; import au.com.dius.pact.consumer.PactVerificationResult; import au.com.dius.pact.consumer.exampleclients.ProviderClient; import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.RequestResponsePact; import org.junit.Test; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static au.com.dius.pact.consumer.ConsumerPactRunnerKt.runConsumerTest; import static org.junit.Assert.assertEquals; /** * Sometimes it is not convenient to use the ConsumerPactTest as it only allows one test per test class. * The DSL can be used directly in this case. */ public class DirectDSLConsumerPactTest { @Test public void testPact() { RequestResponsePact pact = ConsumerPactBuilder .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request to say Hello") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .toPact(); MockProviderConfig config = MockProviderConfig.createDefault(); PactVerificationResult result = runConsumerTest(pact, config, (mockServer, context) -> { Map expectedResponse = new HashMap(); expectedResponse.put("hello", "harry"); try { assertEquals(new ProviderClient(mockServer.getUrl()).hello("{\"name\": \"harry\"}"), expectedResponse); } catch (IOException e) { throw new RuntimeException(e); } }); if (result instanceof PactVerificationResult.Error) { throw new RuntimeException(((PactVerificationResult.Error)result).getError()); } assertEquals(PactVerificationResult.Ok.INSTANCE, result); } } ``` ### The Pact JUnit DSL The DSL has the following pattern: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .given("a certain state on the provider") .uponReceiving("a request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .uponReceiving("another request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") . . . .toPact() ``` You can define as many interactions as required. Each interaction starts with `uponReceiving` followed by `willRespondWith`. The test state setup with `given` is a mechanism to describe what the state of the provider should be in before the provider is verified. It is only recorded in the consumer tests and used by the provider verification tasks. ### Building JSON bodies with PactDslJsonBody DSL **NOTE:** If you are using Java 8, there is [an updated DSL for consumer tests](../pact-jvm-consumer-java8). The body method of the ConsumerPactBuilder can accept a PactDslJsonBody, which can construct a JSON body as well as define regex and type matchers. For example: ```java PactDslJsonBody body = new PactDslJsonBody() .stringType("name") .booleanType("happy") .hexValue("hexCode") .id() .ipAddress("localAddress") .numberValue("age", 100) .timestamp(); ``` #### DSL Matching methods The following matching methods are provided with the DSL. In most cases, they take an optional value parameter which will be used to generate example values (i.e. when returning a mock response). If no example value is given, a random one will be generated. | method | description | |--------|-------------| | string, stringValue | Match a string value (using string equality) | | number, numberValue | Match a number value (using Number.equals)\* | | booleanValue | Match a boolean value (using equality) | | stringType | Will match all Strings | | numberType | Will match all numbers\* | | integerType | Will match all numbers that are integers (both ints and longs)\* | | decimalType | Will match all real numbers (floating point and decimal)\* | | booleanType | Will match all boolean values (true and false) | | stringMatcher | Will match strings using the provided regular expression | | timestamp | Will match string containing timestamps. If a timestamp format is not given, will match an ISO timestamp format | | date | Will match string containing dates. If a date format is not given, will match an ISO date format | | time | Will match string containing times. If a time format is not given, will match an ISO time format | | ipAddress | Will match string containing IP4 formatted address. | | id | Will match all numbers by type | | hexValue | Will match all hexadecimal encoded strings | | uuid | Will match strings containing UUIDs | | includesStr | Will match strings containing the provided string | | equalsTo | Will match using equals | | matchUrl | Defines a matcher for URLs, given the base URL path and a sequence of path fragments. The path fragments could be strings or regular expression matchers | _\* Note:_ JSON only supports double precision floating point values. Depending on the language implementation, they may parsed as integer, floating point or decimal numbers. #### Ensuring all items in a list match an example (2.2.0+) Lots of the time you might not know the number of items that will be in a list, but you want to ensure that the list has a minimum or maximum size and that each item in the list matches a given example. You can do this with the `arrayLike`, `minArrayLike` and `maxArrayLike` functions. | function | description | |----------|-------------| | `eachLike` | Ensure that each item in the list matches the provided example | | `maxArrayLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `minArrayLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java DslPart body = new PactDslJsonBody() .minArrayLike("users", 1) .id() .stringType("name") .closeObject() .closeArray(); ``` This will ensure that the users list is never empty and that each user has an identifier that is a number and a name that is a string. __Version 3.2.4/2.4.6+__ You can specify the number of example items to generate in the array. The default is 1. ```java DslPart body = new PactDslJsonBody() .minArrayLike("users", 1, 2) .id() .stringType("name") .closeObject() .closeArray(); ``` This will generate the example body with 2 items in the users list. #### Root level arrays that match all items (version 2.2.11+) If the root of the body is an array, you can create PactDslJsonArray classes with the following methods: | function | description | |----------|-------------| | `arrayEachLike` | Ensure that each item in the list matches the provided example | | `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java PactDslJsonArray.arrayEachLike() .date("clearedDate", "mm/dd/yyyy", date) .stringType("status", "STATUS") .decimalType("amount", 100.0) .closeObject() ``` This will then match a body like: ```json [ { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 } ] ``` __Version 3.2.4/2.4.6+__ You can specify the number of example items to generate in the array. The default is 1. #### Matching JSON values at the root (Version 3.2.2/2.4.3+) For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request for a basic JSON value") .path("/hello") .willRespondWith() .status(200) .body(PactDslJsonRootValue.integerType()) ``` #### Matching any key in a map (3.3.1/2.5.0+) The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/313). In this case you can use the `eachKeyLike` method, which takes an example key as a parameter. For example: ```java DslPart body = new PactDslJsonBody() .object("one") .eachKeyLike("001", PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher .closeObject() .object("two") .eachKeyLike("001-A") // key like an id where the value is matched by the following example .stringType("description", "Some Description") .closeObject() .closeObject() .object("three") .eachKeyMappedToAnArrayLike("001") // key like an id mapped to an array where each item is matched by the following example .id("someId", 23456L) .closeObject() .closeArray() .closeObject(); ``` For an example, have a look at [WildcardKeysTest](src/test/java/au/com/dius/pact/consumer/WildcardKeysTest.java). **NOTE:** The `eachKeyLike` method adds a `*` to the matching path, so the matching definition will be applied to all keys of the map if there is not a more specific matcher defined for a particular key. Having more than one `eachKeyLike` condition applied to a map will result in only one being applied when the pact is verified (probably the last). **Further Note: From version 3.5.22 onwards pacts with wildcards applied to map keys will require the Java system property "pact.matching.wildcard" set to value "true" when the pact file is verified.** #### Combining matching rules with AND/OR Matching rules can be combined with AND/OR. There are two methods available on the DSL for this. For example: ```java DslPart body = new PactDslJsonBody() .numberValue("valueA", 100) .and("valueB","AB", PM.includesStr("A"), PM.includesStr("B")) // Must match both matching rules .or("valueC", null, PM.date(), PM.nullValue()) // will match either a valid date or a null value ``` The `and` and `or` methods take a variable number of matchers (varargs). ### Matching on paths (version 2.1.5+) You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide a real path as a second value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .matchPath("/transaction/[0-9]+") // or .matchPath("/transaction/[0-9]+", "/transaction/1234567890") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ### Matching on headers (version 2.2.2+) You can use regular expressions to match request and response headers. The DSL has a `matchHeader` method for this. You can provide an example header value to use when generating requests and responses, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchHeader("testreqheader", "test.*value") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .matchHeader("Location", ".*/hello/[0-9]+", "/hello/1234") ``` ### Matching on query parameters (version 3.3.7+) You can use regular expressions to match request query parameters. The DSL has a `matchQuery` method for this. You can provide an example value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchQuery("a", "\\d+", "100") .matchQuery("b", "[A-Z]", "X") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ## Debugging pact failures When the test runs, Pact will start a mock provider that will listen for requests and match them against the expectations you setup in `createFragment`. If the request does not match, it will return a 500 error response. Each request received and the generated response is logged using [SLF4J](http://www.slf4j.org/). Just enable debug level logging for au.com.dius.pact.consumer.UnfilteredMockProvider. Most failures tend to be mismatched headers or bodies. ## Changing the directory pact files are written to (2.1.9+) By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.build.directory}</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` ### Using `@PactFolder` annotation [3.6.2+] You can override the directory the pacts are written in a test by adding the `@PactFolder` annotation to the test class. ## Forcing pact files to be overwritten (3.6.5+) By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. # Publishing your pact files to a pact broker If you use Gradle, you can use the [pact Gradle plugin](https://github.com/DiUS/pact-jvm/tree/master/pact-jvm-provider-gradle#publishing-pact-files-to-a-pact-broker) to publish your pact files. # Pact Specification V3 Version 3 of the pact specification changes the format of pact files in the following ways: * Query parameters are stored in a map form and are un-encoded (see [#66](https://github.com/DiUS/pact-jvm/issues/66) and [#97](https://github.com/DiUS/pact-jvm/issues/97) for information on what this can cause). * Introduces a new message pact format for testing interactions via a message queue. * Multiple provider states can be defined with data parameters. ## Generating V2 spec pact files (3.1.0+, 2.3.0+) To have your consumer tests generate V2 format pacts, you can set the specification version to V2. If you're using the `ConsumerPactTest` base class, you can override the `getSpecificationVersion` method. For example: ```java @Override protected PactSpecVersion getSpecificationVersion() { return PactSpecVersion.V2; } ``` If you are using the `PactProviderRule`, you can pass the version into the constructor for the rule. ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", PactSpecVersion.V2, this); ``` ## Consumer test for a message consumer For testing a consumer of messages from a message queue, the `MessagePactProviderRule` rule class works in much the same way as the `PactProviderRule` class for Request-Response interactions, but will generate a V3 format message pact file. For an example, look at [ExampleMessageConsumerTest](https://github.com/DiUS/pact-jvm/blob/master/pact-jvm-consumer-junit%2Fsrc%2Ftest%2Fjava%2Fau%2Fcom%2Fdius%2Fpact%2Fconsumer%2Fv3%2FExampleMessageConsumerTest.java) # Having values injected from provider state callbacks (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods all you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/${id}", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ```

Maven plugin to verify a provider ================================= Maven plugin for verifying pacts against a provider. The Maven plugin provides a `verify` goal which will verify all configured pacts against your provider. ## To Use It ### 1. Add the pact-jvm-provider-maven plugin to your `build` section of your pom file. ```xml <build> [...] <plugins> [...] <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> </plugin> [...] </plugins> [...] </build> ``` ### 2. Define the pacts between your consumers and providers You define all the providers and consumers within the configuration element of the maven plugin. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <consumers> <!-- Again, you can define as many consumers for each provider as you need, but each must have a unique name --> <consumer> <name>consumer1</name> <!-- currently supports a file path using pactFile or a URL using pactUrl --> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### 3. Execute `mvn pact:verify` You will have to have your provider running for this to pass. ## Verifying all pact files in a directory for a provider You can specify a directory that contains pact files, and the Pact plugin will scan for all pact files that match that provider and define a consumer for each pact file in the directory. Consumer name is read from contents of pact file. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <!-- You can define as many as you need, but each must have a unique name --> <serviceProvider> <name>provider1</name> <!-- All the provider properties are optional, and have sensible defaults (shown below) --> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <path>/</path> <pactFileDirectory>path/to/pacts</pactFileDirectory> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying all pact files from multiple directories for a provider If you want to specify multiple directories, you can use `pactFileDirectories`. The plugin will only fail the build if no pact files are loaded after processing all the directories in the list. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectories> <pactFileDirectory>path/to/pacts1</pactFileDirectory> <pactFileDirectory>path/to/pacts2</pactFileDirectory> </pactFileDirectories> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## 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</insecure>` on the provider. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <insecure>true</insecure> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Specifying a custom trust store For environments that are running their own certificate chains: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <pactFileDirectory>path/to/pacts</pactFileDirectory> <trustStore>relative/path/to/trustStore.jks</trustStore> <trustStorePassword>changeit</trustStorePassword> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` `trustStore` is either relative to the current working (build) directory. `trustStorePassword` 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 Pact Maven plugin provides a request filter that can be set to a Groovy script on the provider that will be called before the request is made. This script will receive the HttpRequest bound to a variable named `request` prior to it being executed. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <requestFilter> // This is a Groovy script that adds an Authorization header to each request request.addHeader('Authorization', 'oauth-token eyJhbGciOiJSUzI1NiIsIm...') </requestFilter> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` __*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 closure assigned to createClient on the provider that returns a CloseableHttpClient. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <createClient> // This is a Groovy script that will enable the client to accept self-signed certificates import org.apache.http.ssl.SSLContextBuilder import org.apache.http.conn.ssl.NoopHostnameVerifier import org.apache.http.impl.client.HttpClients HttpClients.custom().setSSLHostnameVerifier(new NoopHostnameVerifier()) .setSslcontext(new SSLContextBuilder().loadTrustMaterial(null, { x509Certificates, s -> true }) .build()) .build() </createClient> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ## Turning off URL decoding of the paths in the pact file 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 properties can be specified with `-Dproperty=value` on the command line or in the configuration section: |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| |`pact.filter.consumers`|Comma separated 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.filter.pacturl`|This filter allows just the just the changed pact specified in a webhook to be run. It should be used in conjunction with `pact.filter.consumers`| |`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`| |`pact.verifier.disableUrlPathDecoding`|Disables decoding of request paths| |`pact.pactbroker.httpclient.usePreemptiveAuthentication`|Enables preemptive authentication with the pact broker when set to `true`| |`pact.consumer.tags`|Overrides the tags used when publishing pacts [version 4.0.7+]| Example in the configuration section: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <configuration> <pact.showStacktrace>true</pact.showStacktrace> </configuration> </configuration> </plugin> ``` ## 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 and parameters from the pact file before each interaction via a POST. The stateChangeUsesBody controls if the state is passed in the request body or as query parameters. These values can be set at the provider level, or for a specific consumer. Consumer values take precedent if both are given. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/provider1-consumer1-pact.json</pactFile> <stateChangeUrl>http://localhost:8080/tasks/pactStateChangeForConsumer1</stateChangeUrl> <stateChangeUsesBody>false</stateChangeUsesBody> <!-- defaults to true --> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` If the `stateChangeUsesBody` is not specified, or is set to true, then the provider state description and parameters will be sent as JSON in the body of the request. If it is set to false, they will passed as query parameters. As for normal requests (see Modifying the requests before they are sent), a state change request can be modified before it is sent. Set `stateChangeRequestFilter` to a Groovy script on the provider that will be called before the request is made. #### Teardown calls for state changes You can enable teardown state change calls by setting the property `<stateChangeTeardown>true</stateChangeTeardown>` on the provider. This will add an `action` parameter to the state change call. The setup call before the test will receive `action=setup`, and then a teardown call will be made afterwards to the state change URL with `action=teardown`. #### Returning values that can be injected (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. There are methods on the consumer DSLs that can provider an expression that contains variables (like '/api/user/${id}' for the path). The provider state callback can then return a map for values, and the `id` attribute from the map will be expanded in the expression. For URL callbacks, the values need to be returned as JSON in the response body. ## Verifying pact files from a pact broker You can setup your build to validate against the pacts stored in a pact broker. The pact plugin will query the pact broker for all consumers that have a pact with the provider based on its name. To use it, just configure the `pactBrokerUrl` or `pactBroker` value for the provider with the base URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBrokerUrl>http://pact-broker:5000/</pactBrokerUrl> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an authenticated pact broker If your pact broker requires authentication (basic and bearer authentication are supported), you can configure the username and password to use by configuring the `authentication` element of the `pactBroker` element of your provider. For example, here is how you configure the plugin to use basic authentication for verifying pacts: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.1</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <authentication> <scheme>basic</scheme> <username>test</username> <password>test</password> </authentication> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` Here is how you configure the plugin to use bearer token authentication for verifying pacts ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.1</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <authentication> <scheme>bearer</scheme> <token>TOKEN</token> </authentication> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` Preemptive Authentication can be enabled by setting the `pact.pactbroker.httpclient.usePreemptiveAuthentication` Java system property to `true`. ### Allowing just the changed pact specified in a webhook to be verified [4.0.6+] When a consumer publishes a new version of a pact file, the Pact broker can fire off a webhook with the URL of the changed pact file. To allow only the changed pact file to be verified, you can override the URL by using the `pact.filter.consumers` and `pact.filter.pacturl` Java system properties. For example, running: ```console mvn pact:verify -Dpact.filter.consumers='Foo Web Client' -Dpact.filter.pacturl=https://test.pact.dius.com.au/pacts/provider/Activity%20Service/consumer/Foo%20Web%20Client/version/1.0.1 ``` will only run the verification for Foo Web Client with the given pact file URL. #### Using the Maven servers configuration You can use the servers setup in the Maven settings. To do this, setup a server as per the [Maven Server Settings](https://maven.apache.org/settings.html#Servers). Then set the server ID in the pact broker configuration in your POM. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <serverId>test-pact-broker</serverId> <!-- This must match the server id in the maven settings --> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` ### Verifying pacts from an pact broker that match particular tags If your pacts in your pact broker have been tagged, you can set the tags to fetch by configuring the `tags` element of the `pactBroker` element of your provider. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>provider1</name> <stateChangeUrl>http://localhost:8080/tasks/pactStateChange</stateChangeUrl> <pactBroker> <url>http://pactbroker:1234</url> <tags> <tag>TEST</tag> <tag>DEV</tag> </tags> </pactBroker> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` This example will fetch and validate the pacts for the TEST and DEV tags. ## 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 `-Dpact.filter.consumers=consumer1,consumer2` to the command line or configuration section will only run the pact files for those consumers (consumer1 and consumer2). Adding `-Dpact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `-Dpact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `-Dpact.filter.providerState=` will match any interaction that does not have a provider state. ## Not failing the build if no pact files are found By default, if there are no pact files to verify, the plugin will raise an exception. This is to guard against false positives where the build is passing but nothing has been verified due to mis-configuration. To disable this behaviour, set the `failIfNoPactsFound` parameter to `false`. # Verifying a message provider The Maven plugin has been updated to allow invoking test methods that can return the message contents from a message producer. To use it, set the way to invoke the verification to `ANNOTATED_METHOD`. This will allow the pact verification task to scan for test methods that return the message contents. Add something like the following to your maven pom file: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <!-- packagesToScan is optional, but leaving it out will result in the entire test classpath being scanned. Set it to the packages where your annotated test method can be found. --> <packagesToScan> <packageToScan>au.com.example.messageprovider.*</packageToScan> </packagesToScan> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> </configuration> </plugin> ``` Now when the pact verify task is run, will look for methods annotated with `@PactVerifyProvider` in the test classpath that have a matching description to what is in the pact file. ```groovy class ConfirmationKafkaMessageBuilderTest { @PactVerifyProvider('an order confirmation message') String verifyMessageForOrder() { Order order = new Order() order.setId(10000004) order.setExchange('ASX') order.setSecurityCode('CBA') order.setPrice(BigDecimal.TEN) order.setUnits(15) order.setGst(new BigDecimal('15.0')) odrer.setFees(BigDecimal.TEN) def message = new ConfirmationKafkaMessageBuilder() .withOrder(order) .build() JsonOutput.toJson(message) } } ``` It will then validate that the returned contents matches the contents for the message in the pact file. ## Changing the class path that is scanned By default, the test classpath is scanned for annotated methods. You can override this by setting the `classpathElements` property: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <serviceProviders> <serviceProvider> <name>messageProvider</name> <verificationType>ANNOTATED_METHOD</verificationType> <consumers> <consumer> <name>consumer1</name> <pactFile>path/to/messageprovider-consumer1-pact.json</pactFile> </consumer> </consumers> </serviceProvider> </serviceProviders> <classpathElements> <classpathElement> build/classes/test </classpathElement> </classpathElements> </configuration> </plugin> ``` # Publishing pact files to a pact broker The pact maven plugin provides a `publish` mojo that can publish all pact files in a directory to a pact broker. To use it, you need to add a publish configuration to the POM that defines the directory where the pact files are and the URL to the pact broker. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts --> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} --> <trimSnapshot>true</trimSnapshot> <!-- Defaults to false --> <skipPactPublish>false</skipPactPublish> <!-- Defaults to false --> </configuration> </plugin> ``` You can now execute `mvn pact:publish` to publish the pact files. _NOTE:_ The pact broker requires a version for all published pacts. The `publish` task will use the version of the project by default, but can be overwritten with the `projectVersion` property. Make sure you have set one otherwise the broker will reject the pact files. _NOTE_: By default, the pact broker has issues parsing `SNAPSHOT` versions. You can configure the publisher to automatically remove `-SNAPSHOT` from your version number by setting `trimSnapshot` to true. This setting does not modify non-snapshot versions. You can set any tags that the pacts should be published with by setting the `tags` list property. A common use of this is setting the tag to the current source control branch. This supports using pact with feature branches. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <pactDirectory>path/to/pact/files</pactDirectory> <!-- Defaults to ${project.build.directory}/pacts --> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <projectVersion>1.0.100</projectVersion> <!-- Defaults to ${project.version} --> <tags> <tag>feature/feature_name</tag> </tags> </configuration> </plugin> ``` You can also specify the tags using the `pact.consumer.tags` Java system property [version 4.0.7+]. ## Publishing to an authenticated pact broker For an authenticated pact broker, you can pass in the credentials with the `pactBrokerUsername` and `pactBrokerPassword` properties. Currently it only supports basic authentication. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerUsername>USERNAME</pactBrokerUsername> <pactBrokerPassword>PASSWORD</pactBrokerPassword> </configuration> </plugin> ``` Or to use a bearer token: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven_2.12</artifactId> <version>3.5.11</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerToken>TOKEN</pactBrokerToken> <!-- Replace TOKEN with the actual token --> <pactBrokerAuthenticationScheme>Bearer</pactBrokerAuthenticationScheme> </configuration> </plugin> ``` #### Using the Maven servers configuration You can use the servers setup in the Maven settings. To do this, setup a server as per the [Maven Server Settings](https://maven.apache.org/settings.html#Servers). Then set the server ID in the pact broker configuration in your POM. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <pactBrokerServerId>test-pact-broker</pactBrokerServerId> <!-- This must match the server id in the maven settings --> </configuration> </plugin> ``` ## Excluding pacts from being published You can exclude some of the pact files from being published by providing a list of regular expressions that match against the base names of the pact files. For example: ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <pactBrokerUrl>http://pactbroker:1234</pactBrokerUrl> <excludes> <exclude>.*\\-\\d+$</exclude> <!-- exclude pact files where the name ends in a dash followed by a number --> </excludes> </configuration> </plugin> ``` # Publishing verification results to a Pact Broker For pacts that are loaded from a Pact Broker, the results of running the verification can be published back to the broker against the URL for the pact. You will be able to then see the result on the Pact Broker home screen. To turn on the verification publishing, set the system property `pact.verifier.publishResults` to `true` in the pact maven plugin, not surefire, configuration. ## Tagging the provider before verification results are published [4.0.1+] You can have a tag pushed against the provider version before the verification results are published. To do this you need set the `pact.provider.tag` JVM system property to the tag value. # Enabling other verification reports By default the verification report is written to the console. You can also enable a JSON or Markdown report by setting the `reports` configuration list. ```xml <plugin> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-provider-maven</artifactId> <version>4.0.0</version> <configuration> <reports> <report>console</report> <report>json</report> <report>markdown</report> </reports> </configuration> </plugin> ``` These reports will be written to `target/reports/pact`.

pact-jvm-provider-gradle ======================== Gradle plugin for verifying pacts against a provider. The Gradle plugin creates a task `pactVerify` to your build which will verify all configured pacts against your provider. __*Important Note: Any properties that need to be set when using the Gradle plugin need to be provided with `-P` and not `-D` as with the other Pact-JVM modules!*__ ## To Use It ### For Gradle versions prior to 2.1 #### 1.1. Add the pact-jvm-provider-gradle jar file to your build script class path: ```groovy buildscript { repositories { mavenCentral() } dependencies { classpath 'au.com.dius:pact-jvm-provider-gradle:4.0.0' } } ``` #### 1.2. Apply the pact plugin ```groovy apply plugin: 'au.com.dius.pact' ``` ### For Gradle versions 2.1+ ```groovy plugins { id "au.com.dius.pact" version "4.0.0" } ``` ### 2. Define the pacts between your consumers and providers ```groovy pact { serviceProviders { // 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 = '/' // Again, you can define as many consumers for each provider as you need, but each must have a unique name hasPactWith('consumer1') { // currently supports a file path using file() or a URL using url() pactSource = file('path/to/provider1-consumer1-pact.json') } // Or if you have many pact files in a directory hasPactsWith('manyConsumers') { // Will define a consumer for each pact file in the directory. // Consumer name is read from contents of pact file pactFileLocation = file('path/to/pacts') } } } } ``` ### 3. Execute `gradle pactVerify` ## Specifying the provider hostname at runtime If you need to calculate the provider hostname at runtime, you can give a Closure as the provider `host`. ```groovy pact { serviceProviders { provider1 { host = { lookupHostName() } hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` You can also give a Closure as the provider `port`. ## Specifying the pact file or URL at runtime If you need to calculate the pact file or URL at runtime, you can give a Closure as the provider `pactFile`. ```groovy pact { serviceProviders { provider1 { host = 'localhost' hasPactWith('consumer1') { pactFile = { lookupPactFile() } } } } } ``` ## Starting and shutting down your provider If you need to start-up or shutdown your provider, define Gradle tasks for each action and set `startProviderTask` and `terminateProviderTask` properties of each provider. You could use the jetty tasks here if you provider is built as a WAR file. ```groovy // This will be called before the provider task task('startTheApp') { doLast { // start up your provider here } } // This will be called after the provider task task('killTheApp') { doLast { // kill your provider here } } pact { serviceProviders { provider1 { startProviderTask = startTheApp terminateProviderTask = killTheApp hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` Following typical Gradle behaviour, you can set the provider task properties to the actual tasks, or to the task names as a string (for the case when they haven't been defined yet). ## Preventing the chaining of provider verify task to `pactVerify` Normally a gradle task named `pactVerify_${provider.name}` is created and added as a task dependency for `pactVerify`. You can disable this dependency on a provider by setting `isDependencyForPactVerify` to `false` (defaults to `true`). ```groovy pact { serviceProviders { provider1 { isDependencyForPactVerify = false hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` To run this task, you would then have to explicitly name it as in ```gradle pactVerify_provider1```, a normal ```gradle pactVerify``` would skip it. This can be useful when you want to define two providers, one with `startProviderTask`/`terminateProviderTask` and as second without, so you can manually start your provider (to debug it from your IDE, for example) but still want a `pactVerify` to run normally from your CI build. ## 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. ```groovy pact { serviceProviders { provider1 { insecure = true // allow SSL with a self-signed cert hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` ## Specifying a custom trust store For environments that are running their own certificate chains: ```groovy pact { serviceProviders { provider1 { trustStore = new File('relative/path/to/trustStore.jks') trustStorePassword = 'changeit' hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` `trustStore` is either relative to the current working (build) directory. `trustStorePassword` defaults to `changeit`. NOTE: The hostname will still be verified against the certificate. ## 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 closure assigned to createClient on the provider that returns a CloseableHttpClient. For example: ```groovy pact { serviceProviders { provider1 { createClient = { provider -> // This will enable the client to accept self-signed certificates HttpClients.custom().setSSLHostnameVerifier(new NoopHostnameVerifier()) .setSslcontext(new SSLContextBuilder().loadTrustMaterial(null, { x509Certificates, s -> true }) .build()) .build() } hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` ## 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 Pact Gradle plugin provides a request filter that can be set to a closure on the provider that will be called before the request is made. This closure will receive the HttpRequest prior to it being executed. ```groovy pact { serviceProviders { provider1 { requestFilter = { req -> // Add an authorization header to each request req.addHeader('Authorization', 'OAUTH eyJhbGciOiJSUzI1NiIsImN0eSI6ImFw...') } hasPactWith('consumer1') { pactFile = 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! ## Turning off URL decoding of the paths in the pact file 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 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. ## Project Properties The following project properties can be specified with `-Pproperty=value` 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| |`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.filter.pacturl`|This filter allows just the just the changed pact specified in a webhook to be run. It should be used in conjunction with `pact.filter.consumers` | |`pact.verifier.publishResults`|Publishing of verification results will be skipped unless this property is set to 'true'| |`pact.matching.wildcard`|Enables matching of map values ignoring the keys when this property is set to 'true'| |`pact.verifier.disableUrlPathDecoding`|Disables decoding of request paths| |`pact.pactbroker.httpclient.usePreemptiveAuthentication`|Enables preemptive authentication with the pact broker when set to `true`| |`pact.provider.tag`|Sets the provider tag to push before publishing verification results| ## Provider States For a description of what provider states are, see the pact documentations: http://docs.pact.io/documentation/provider_states.html ### Using a state change URL 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 and all the parameters from the pact file before each interaction via a POST. As for normal requests, a request filter (`stateChangeRequestFilter`) can also be set to manipulate the request before it is sent. ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') stateChangeUrl = url('http://localhost:8001/tasks/pactStateChange') stateChangeUsesBody = false // defaults to true stateChangeRequestFilter = { req -> // Add an authorization header to each request req.addHeader('Authorization', 'OAUTH eyJhbGciOiJSUzI1NiIsImN0eSI6ImFw...') } } // or hasPactsWith('consumers') { pactFileLocation = file('path/to/pacts') stateChangeUrl = url('http://localhost:8001/tasks/pactStateChange') stateChangeUsesBody = false // defaults to true } } } } ``` If the `stateChangeUsesBody` is not specified, or is set to true, then the provider state description and parameters will be sent as JSON in the body of the request : ```json { "state" : "a provider state description", "params": { "a": "1", "b": "2" } } ``` If it is set to false, they will be passed as query parameters. #### Teardown calls for state changes You can enable teardown state change calls by setting the property `stateChangeTeardown = true` on the provider. This will add an `action` parameter to the state change call. The setup call before the test will receive `action=setup`, and then a teardown call will be made afterwards to the state change URL with `action=teardown`. ### Using a Closure You can set a closure to be called before each verification with a defined provider state. The closure will be called with the state description and parameters from the pact file. ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') // Load a fixture file based on the provider state and then setup some database // data. Does not require a state change request so returns false stateChange = { providerState -> // providerState is an instance of ProviderState def fixture = loadFixtuerForProviderState(providerState) setupDatabase(fixture) } } } } } ``` #### Teardown calls for state changes You can enable teardown state change calls by setting the property `stateChangeTeardown = true` on the provider. This will add an `action` parameter to the state change closure call. The setup call before the test will receive `setup`, as the second parameter, and then a teardown call will be made afterwards with `teardown` as the second parameter. ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') // Load a fixture file based on the provider state and then setup some database // data. Does not require a state change request so returns false stateChange = { providerState, action -> if (action == 'setup') { def fixture = loadFixtuerForProviderState(providerState) setupDatabase(fixture) } else { cleanupDatabase() } false } } } } } ``` #### Returning values that can be injected You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. There are methods on the consumer DSLs that can provider an expression that contains variables (like '/api/user/${id}' for the path). The provider state callback can then return a map for values, and the `id` attribute from the map will be expanded in the expression. For URL callbacks, the values need to be returned as JSON in the response body. ## Filtering the interactions that are verified You can filter the interactions that are run using three project properties: `pact.filter.consumers`, `pact.filter.description` and `pact.filter.providerState`. Adding `-Ppact.filter.consumers=consumer1,consumer2` to the command line will only run the pact files for those consumers (consumer1 and consumer2). Adding `-Ppact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `-Ppact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `-Ppact.filter.providerState=` will match any interaction that does not have a provider state. ## Verifying pact files from a pact broker You can setup your build to validate against the pacts stored in a pact broker. The pact gradle plugin will query the pact broker for all consumers that have a pact with the provider based on its name. For example: ```groovy pact { serviceProviders { provider1 { // You can get the latest pacts from the broker hasPactsFromPactBroker('http://pact-broker:5000/') // And/or you can get the latest pact with a specific tag hasPactsFromPactBrokerWithTag('http://pact-broker:5000/',"tagname") } } } ``` This will verify all pacts found in the pact broker where the provider name is 'provider1'. If you need to set any values on the consumers from the pact broker, you can add a Closure to configure them. ```groovy pact { serviceProviders { provider1 { hasPactsFromPactBroker('http://pact-broker:5000/') { consumer -> stateChange = { providerState -> /* state change code here */ true } } } } } ``` **NOTE: Currently the pacts are fetched from the broker during the configuration phase of the build. This means that if the broker is not available, you will not be able to run any Gradle tasks.** This should be fixed in a forth coming release. In the mean time, to only load the pacts when running the validate task, you can do something like: ```groovy pact { serviceProviders { provider1 { // Only load the pacts from the broker if the start tasks from the command line include pactVerify if ('pactVerify' in gradle.startParameter.taskNames) { hasPactsFromPactBroker('http://pact-broker:5000/') { consumer -> stateChange = { providerState -> /* state change code here */ true } } } } } } ``` ### Using an authenticated Pact Broker You can add the authentication details for the Pact Broker like so: ```groovy pact { serviceProviders { provider1 { hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Basic', pactBrokerUser, pactBrokerPassword]) } } } ``` `pactBrokerUser` and `pactBrokerPassword` can be defined in the gradle properties. Or with a bearer token: ```groovy pact { serviceProviders { provider1 { hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Bearer', pactBrokerToken]) } } } ``` Preemptive Authentication can be enabled by setting the `pact.pactbroker.httpclient.usePreemptiveAuthentication` property to `true`. ### Allowing just the changed pact specified in a webhook to be verified [4.0.6+] When a consumer publishes a new version of a pact file, the Pact broker can fire off a webhook with the URL of the changed pact file. To allow only the changed pact file to be verified, you can override the URL by using the `pact.filter.consumers` and `pact.filter.pacturl` project properties. For example, running: ```console gradle pactVerify -Ppact.filter.consumers='Foo Web Client' -Ppact.filter.pacturl=https://test.pact.dius.com.au/pacts/provider/Activity%20Service/consumer/Foo%20Web%20Client/version/1.0.1 ``` will only run the verification for Foo Web Client with the given pact file URL. ## Verifying pact files from a S3 bucket **NOTE:** You will need to add the Amazon S3 SDK jar file to your project. Pact files stored in an S3 bucket can be verified by using an S3 URL to the pact file. I.e., ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = 's3://bucketname/path/to/provider1-consumer1-pact.json' } } } } ``` **NOTE:** you can't use the `url` function with S3 URLs, as the URL and URI classes from the Java SDK don't support URLs with the s3 scheme. # Publishing pact files to a pact broker The pact gradle plugin provides a `pactPublish` task that can publish all pact files in a directory to a pact broker. To use it, you need to add a publish configuration to the pact configuration that defines the directory where the pact files are and the URL to the pact broker. For example: ```groovy pact { publish { pactDirectory = '/pact/dir' // defaults to $buildDir/pacts pactBrokerUrl = 'http://pactbroker:1234' } } ``` You can set any tags that the pacts should be published with by setting the `tags` property. A common use of this is setting the tag to the current source control branch. This supports using pact with feature branches. ```groovy pact { publish { pactDirectory = '/pact/dir' // defaults to $buildDir/pacts pactBrokerUrl = 'http://pactbroker:1234' tags = [project.pactBrokerTag] } } ``` _NOTE:_ The pact broker requires a version for all published pacts. The `pactPublish` task will use the version of the gradle project by default. You can override this with the `providerVersion` property. Make sure you have set one otherwise the broker will reject the pact files. ## Publishing to an authenticated pact broker To publish to a broker protected by basic auth, include the username/password in the `pactBrokerUrl`. For example: ```groovy pact { publish { pactBrokerUrl = 'https://username:[email protected]' } } ``` You can add the username and password as properties. ```groovy pact { publish { pactBrokerUrl = 'https://mypactbroker.com' pactBrokerUsername = 'username' pactBrokerPassword = 'password' } } ``` or with a bearer token ```groovy pact { publish { pactBrokerUrl = 'https://mypactbroker.com' pactBrokerToken = 'token' } } ``` ## Excluding pacts from being published You can exclude some of the pact files from being published by providing a list of regular expressions that match against the base names of the pact files. For example: ```groovy pact { publish { pactBrokerUrl = 'https://mypactbroker.com' excludes = [ '.*\\-\\d+$' ] // exclude all pact files that end with a dash followed by a number in the name } } ``` # Verifying a message provider The Gradle plugin has been updated to allow invoking test methods that can return the message contents from a message producer. To use it, set the way to invoke the verification to `ANNOTATED_METHOD`. This will allow the pact verification task to scan for test methods that return the message contents. Add something like the following to your gradle build file: ```groovy pact { serviceProviders { messageProvider { verificationType = 'ANNOTATED_METHOD' packagesToScan = ['au.com.example.messageprovider.*'] // This is optional, but leaving it out will result in the entire // test classpath being scanned hasPactWith('messageConsumer') { pactFile = url('url/to/messagepact.json') } } } } ``` Now when the `pactVerify` task is run, will look for methods annotated with `@PactVerifyProvider` in the test classpath that have a matching description to what is in the pact file. ```groovy class ConfirmationKafkaMessageBuilderTest { @PactVerifyProvider('an order confirmation message') String verifyMessageForOrder() { Order order = new Order() order.setId(10000004) order.setExchange('ASX') order.setSecurityCode('CBA') order.setPrice(BigDecimal.TEN) order.setUnits(15) order.setGst(new BigDecimal('15.0')) order.setFees(BigDecimal.TEN) def message = new ConfirmationKafkaMessageBuilder() .withOrder(order) .build() JsonOutput.toJson(message) } } ``` It will then validate that the returned contents matches the contents for the message in the pact file. ## Publishing to the Gradle Community Portal To publish the plugin to the community portal: $ ./gradlew :pact-jvm-provider-gradle_2.11:publishPlugins # Verification Reports The default behaviour is to display the verification being done to the console, and pass or fail the build via the normal Gradle mechanism. Additional reports can be generated from the verification. ## Enabling additional reports The verification reports can be controlled by adding a reports section to the pact configuration in the gradle build file. For example: ```groovy pact { reports { defaultReports() // adds the standard console output markdown // report in markdown format json // report in json format } } ``` Any report files will be written to "build/reports/pact". ## Additional Reports The following report types are available in addition to console output (which is enabled by default): `markdown`, `json`. # Publishing verification results to a Pact Broker For pacts that are loaded from a Pact Broker, the results of running the verification can be published back to the broker against the URL for the pact. You will be able to see the result on the Pact Broker home screen. To turn on the verification publishing, set the project property `pact.verifier.publishResults` to `true`. By default, the Gradle project version will be used as the provider version. You can override this by setting the `providerVersion` property. ```groovy pact { serviceProviders { provider1 { providerVersion = { branchName() + '-' + abbreviatedId() } hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Basic', pactBrokerUser, pactBrokerPassword]) } } } ``` ## Tagging the provider before verification results are published [4.0.1+] You can have a tag pushed against the provider version before the verification results are published. There are two ways to do this with the Gradle plugin. You can provide a closure in a similar way to the provider version, i.e. ```groovy pact { serviceProviders { provider1 { providerVersion = { branchName() + '-' + abbreviatedId() } providerTag = { branchName() } hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Basic', pactBrokerUser, pactBrokerPassword]) } } } ``` or you can set the `pact.provider.tag` JVM system property. For example: ```console $ ./gradlew -d pactverify -Ppact.verifier.publishResults=true -Dpact.provider.tag=Test2 ```

pact-jvm-consumer-junit ======================= Provides a DSL and a base test class for use with Junit to build consumer tests. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-junit` * version-id = `4.0.x` ## Usage ### Using the base ConsumerPactTest To write a pact spec extend ConsumerPactTest. This base class defines the following four methods which must be overridden in your test class. * *providerName:* Returns the name of the API provider that Pact will mock * *consumerName:* Returns the name of the API consumer that we are testing. * *createFragment:* Returns the PactFragment containing the interactions that the test setup using the ConsumerPactBuilder DSL * *runTest:* The actual test run. It receives the URL to the mock server as a parameter. Here is an example: ```java import au.com.dius.pact.consumer.dsl.PactDslWithProvider; import au.com.dius.pact.consumer.exampleclients.ConsumerClient; import au.com.dius.pact.consumer.ConsumerPactTest; import au.com.dius.pact.model.PactFragment; import org.junit.Assert; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static org.junit.Assert.assertEquals; public class ExampleJavaConsumerPactTest extends ConsumerPactTest { @Override protected RequestResponsePact createFragment(PactDslWithProvider builder) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); return builder .given("test state") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/") .method("GET") .headers(headers) .willRespondWith() .status(200) .headers(headers) .body("{\"responsetest\": true, \"name\": \"harry\"}") .given("test state 2") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest second test interaction") .method("OPTIONS") .headers(headers) .path("/second") .body("") .willRespondWith() .status(200) .headers(headers) .body("") .toPact(); } @Override protected String providerName() { return "test_provider"; } @Override protected String consumerName() { return "test_consumer"; } @Override protected void runTest(MockServer mockServer, PactTestExecutionContext context) throws IOException { Assert.assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 200); Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); expectedResponse.put("name", "harry"); assertEquals(new ConsumerClient(mockServer.getUrl()).getAsMap("/", ""), expectedResponse); assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 200); } } ``` ### Using the Pact JUnit Rule Thanks to [@warmuuh](https://github.com/warmuuh) we have a JUnit rule that simplifies running Pact consumer tests. To use it, create a test class and then add the rule: #### 1. Add the Pact Rule to your test class to represent your provider. ```java @Rule public PactProviderRule mockProvider = new PactProviderRule("test_provider", "localhost", 8080, this); ``` The hostname and port are optional. If left out, it will default to 127.0.0.1 and a random available port. You can get the URL and port from the pact provider rule. #### 2. Annotate a method with Pact that returns a pact fragment for the provider and consumer ```java @Pact(provider="test_provider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` You can leave the provider name out. It will then use the provider name of the first mock provider found. I.e., ```java @Pact(consumer="test_consumer") // will default to the provider name from mockProvider public RequestResponsePact createFragment(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` #### 3. Annotate your test method with PactVerification to have it run in the context of the mock server setup with the appropriate pact from step 1 and 2 ```java @Test @PactVerification("test_provider") public void runTest() { Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient(mockProvider.getUrl()).get("/"), expectedResponse); } ``` You can leave the provider name out. It will then use the provider name of the first mock provider found. I.e., ```java @Test @PactVerification public void runTest() { // This will run against mockProvider Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient("http://localhost:8080").get("/"), expectedResponse); } ``` For an example, have a look at [ExampleJavaConsumerPactRuleTest](src/test/java/au/com/dius/pact/consumer/examples/ExampleJavaConsumerPactRuleTest.java) ### Requiring a test with multiple providers The Pact Rule can be used to test with multiple providers. Just add a rule to the test class for each provider, and then include all the providers required in the `@PactVerification` annotation. For an example, look at [PactMultiProviderTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactMultiProviderTest.java). Note that if more than one provider fails verification for the same test, you will only receive a failure for one of them. Also, to have multiple tests in the same test class, the providers must be setup with random ports (i.e. don't specify a hostname and port). Also, if the provider name is left out of any of the annotations, the first one found will be used (which may not be the first one defined). ### Requiring the mock server to run with HTTPS The mock server can be started running with HTTPS using a self-signed certificate instead of HTTP. To enable this set the `https` parameter to `true`. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, PactSpecVersion.V2, this); // ^^^^ ``` For an example test doing this, see [PactProviderHttpsTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderHttpsTest.java). **NOTE:** The provider will start handling HTTPS requests using a self-signed certificate. Most HTTP clients will not accept connections to a self-signed server as the certificate is untrusted. You may need to enable insecure HTTPS with your client for this test to work. For an example of how to enable insecure HTTPS client connections with Apache Http Client, have a look at [InsecureHttpsRequest](src/test/java/org/apache/http/client/fluent/InsecureHttpsRequest.java). ### Requiring the mock server to run with HTTPS with a keystore The mock server can be started running with HTTPS using a keystore. To enable this set the `https` parameter to `true`, set the keystore path/file, and the keystore's password. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, "/path/to/your/keystore.jks", "your-keystore-password", PactSpecVersion.V2, this); ``` For an example test doing this, see [PactProviderHttpsKeystoreTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderHttpsKeystoreTest.java). ### Setting default expected request and response values If you have a lot of tests that may share some values (like headers), you can setup default values that will be applied to all the expected requests and responses for the tests. To do this, you need to create a method that takes single parameter of the appropriate type (`PactDslRequestWithoutPath` or `PactDslResponse`) and annotate it with the default marker annotation (`@DefaultRequestValues` or `@DefaultResponseValues`). For example: ```java @DefaultRequestValues public void defaultRequestValues(PactDslRequestWithoutPath request) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); request.headers(headers); } @DefaultResponseValues public void defaultResponseValues(PactDslResponse response) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testresheader", "testresheadervalue"); response.headers(headers); } ``` For an example test that uses these, have a look at [PactProviderWithMultipleFragmentsTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderWithMultipleFragmentsTest.java) ### Note on HTTP clients and persistent connections Some HTTP clients may keep the connection open, based on the live connections settings or if they use a connection cache. This could cause your tests to fail if the client you are testing lives longer than an individual test, as the mock server will be started and shutdown for each test. This will result in the HTTP client connection cache having invalid connections. For an example of this where the there was a failure for every second test, see [Issue #342](https://github.com/DiUS/pact-jvm/issues/342). ### Using the Pact DSL directly Sometimes it is not convenient to use the ConsumerPactTest as it only allows one test per test class. The DSL can be used directly in this case. Example: ```java import au.com.dius.pact.consumer.ConsumerPactBuilder; import au.com.dius.pact.consumer.PactVerificationResult; import au.com.dius.pact.consumer.exampleclients.ProviderClient; import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.RequestResponsePact; import org.junit.Test; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static au.com.dius.pact.consumer.ConsumerPactRunnerKt.runConsumerTest; import static org.junit.Assert.assertEquals; /** * Sometimes it is not convenient to use the ConsumerPactTest as it only allows one test per test class. * The DSL can be used directly in this case. */ public class DirectDSLConsumerPactTest { @Test public void testPact() { RequestResponsePact pact = ConsumerPactBuilder .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request to say Hello") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .toPact(); MockProviderConfig config = MockProviderConfig.createDefault(); PactVerificationResult result = runConsumerTest(pact, config, (mockServer, context) -> { Map expectedResponse = new HashMap(); expectedResponse.put("hello", "harry"); try { assertEquals(new ProviderClient(mockServer.getUrl()).hello("{\"name\": \"harry\"}"), expectedResponse); } catch (IOException e) { throw new RuntimeException(e); } }); if (result instanceof PactVerificationResult.Error) { throw new RuntimeException(((PactVerificationResult.Error)result).getError()); } assertEquals(PactVerificationResult.Ok.INSTANCE, result); } } ``` ### The Pact JUnit DSL The DSL has the following pattern: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .given("a certain state on the provider") .uponReceiving("a request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .uponReceiving("another request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") . . . .toPact() ``` You can define as many interactions as required. Each interaction starts with `uponReceiving` followed by `willRespondWith`. The test state setup with `given` is a mechanism to describe what the state of the provider should be in before the provider is verified. It is only recorded in the consumer tests and used by the provider verification tasks. ### Building JSON bodies with PactDslJsonBody DSL **NOTE:** If you are using Java 8, there is [an updated DSL for consumer tests](../pact-jvm-consumer-java8). The body method of the ConsumerPactBuilder can accept a PactDslJsonBody, which can construct a JSON body as well as define regex and type matchers. For example: ```java PactDslJsonBody body = new PactDslJsonBody() .stringType("name") .booleanType("happy") .hexValue("hexCode") .id() .ipAddress("localAddress") .numberValue("age", 100) .timestamp(); ``` #### DSL Matching methods The following matching methods are provided with the DSL. In most cases, they take an optional value parameter which will be used to generate example values (i.e. when returning a mock response). If no example value is given, a random one will be generated. | method | description | |--------|-------------| | string, stringValue | Match a string value (using string equality) | | number, numberValue | Match a number value (using Number.equals)\* | | booleanValue | Match a boolean value (using equality) | | stringType | Will match all Strings | | numberType | Will match all numbers\* | | integerType | Will match all numbers that are integers (both ints and longs)\* | | decimalType | Will match all real numbers (floating point and decimal)\* | | booleanType | Will match all boolean values (true and false) | | stringMatcher | Will match strings using the provided regular expression | | timestamp | Will match string containing timestamps. If a timestamp format is not given, will match an ISO timestamp format | | date | Will match string containing dates. If a date format is not given, will match an ISO date format | | time | Will match string containing times. If a time format is not given, will match an ISO time format | | ipAddress | Will match string containing IP4 formatted address. | | id | Will match all numbers by type | | hexValue | Will match all hexadecimal encoded strings | | uuid | Will match strings containing UUIDs | | includesStr | Will match strings containing the provided string | | equalsTo | Will match using equals | | matchUrl | Defines a matcher for URLs, given the base URL path and a sequence of path fragments. The path fragments could be strings or regular expression matchers | _\* Note:_ JSON only supports double precision floating point values. Depending on the language implementation, they may parsed as integer, floating point or decimal numbers. #### Ensuring all items in a list match an example Lots of the time you might not know the number of items that will be in a list, but you want to ensure that the list has a minimum or maximum size and that each item in the list matches a given example. You can do this with the `arrayLike`, `minArrayLike` and `maxArrayLike` functions. | function | description | |----------|-------------| | `eachLike` | Ensure that each item in the list matches the provided example | | `maxArrayLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `minArrayLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java DslPart body = new PactDslJsonBody() .minArrayLike("users", 1) .id() .stringType("name") .closeObject() .closeArray(); ``` This will ensure that the users list is never empty and that each user has an identifier that is a number and a name that is a string. You can specify the number of example items to generate in the array. The default is 1. ```java DslPart body = new PactDslJsonBody() .minArrayLike("users", 1, 2) .id() .stringType("name") .closeObject() .closeArray(); ``` This will generate the example body with 2 items in the users list. #### Root level arrays that match all items If the root of the body is an array, you can create PactDslJsonArray classes with the following methods: | function | description | |----------|-------------| | `arrayEachLike` | Ensure that each item in the list matches the provided example | | `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java PactDslJsonArray.arrayEachLike() .date("clearedDate", "mm/dd/yyyy", date) .stringType("status", "STATUS") .decimalType("amount", 100.0) .closeObject() ``` This will then match a body like: ```json [ { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 } ] ``` You can specify the number of example items to generate in the array. The default is 1. #### Matching JSON values at the root For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request for a basic JSON value") .path("/hello") .willRespondWith() .status(200) .body(PactDslJsonRootValue.integerType()) ``` #### Matching any key in a map The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/313). In this case you can use the `eachKeyLike` method, which takes an example key as a parameter. For example: ```java DslPart body = new PactDslJsonBody() .object("one") .eachKeyLike("001", PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher .closeObject() .object("two") .eachKeyLike("001-A") // key like an id where the value is matched by the following example .stringType("description", "Some Description") .closeObject() .closeObject() .object("three") .eachKeyMappedToAnArrayLike("001") // key like an id mapped to an array where each item is matched by the following example .id("someId", 23456L) .closeObject() .closeArray() .closeObject(); ``` For an example, have a look at [WildcardKeysTest](src/test/java/au/com/dius/pact/consumer/WildcardKeysTest.java). **NOTE:** The `eachKeyLike` method adds a `*` to the matching path, so the matching definition will be applied to all keys of the map if there is not a more specific matcher defined for a particular key. Having more than one `eachKeyLike` condition applied to a map will result in only one being applied when the pact is verified (probably the last). **Further Note: From version 3.5.22 onwards pacts with wildcards applied to map keys will require the Java system property "pact.matching.wildcard" set to value "true" when the pact file is verified.** #### Combining matching rules with AND/OR Matching rules can be combined with AND/OR. There are two methods available on the DSL for this. For example: ```java DslPart body = new PactDslJsonBody() .numberValue("valueA", 100) .and("valueB","AB", PM.includesStr("A"), PM.includesStr("B")) // Must match both matching rules .or("valueC", null, PM.date(), PM.nullValue()) // will match either a valid date or a null value ``` The `and` and `or` methods take a variable number of matchers (varargs). ### Matching on paths You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide a real path as a second value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .matchPath("/transaction/[0-9]+") // or .matchPath("/transaction/[0-9]+", "/transaction/1234567890") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ### Matching on headers You can use regular expressions to match request and response headers. The DSL has a `matchHeader` method for this. You can provide an example header value to use when generating requests and responses, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchHeader("testreqheader", "test.*value") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .matchHeader("Location", ".*/hello/[0-9]+", "/hello/1234") ``` ### Matching on query parameters You can use regular expressions to match request query parameters. The DSL has a `matchQuery` method for this. You can provide an example value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchQuery("a", "\\d+", "100") .matchQuery("b", "[A-Z]", "X") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ## Debugging pact failures When the test runs, Pact will start a mock provider that will listen for requests and match them against the expectations you setup in `createFragment`. If the request does not match, it will return a 500 error response. Each request received and the generated response is logged using [SLF4J](http://www.slf4j.org/). Just enable debug level logging for au.com.dius.pact.consumer.UnfilteredMockProvider. Most failures tend to be mismatched headers or bodies. ## Changing the directory pact files are written to By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.build.directory}</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` ### Using `@PactFolder` annotation You can override the directory the pacts are written in a test by adding the `@PactFolder` annotation to the test class. ## Forcing pact files to be overwritten (3.6.5+) By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. # Publishing your pact files to a pact broker If you use Gradle, you can use the [pact Gradle plugin](../../provider/pact-jvm-provider-gradle#publishing-pact-files-to-a-pact-broker) to publish your pact files. # Pact Specification V3 Version 3 of the pact specification changes the format of pact files in the following ways: * Query parameters are stored in a map form and are un-encoded (see [#66](https://github.com/DiUS/pact-jvm/issues/66) and [#97](https://github.com/DiUS/pact-jvm/issues/97) for information on what this can cause). * Introduces a new message pact format for testing interactions via a message queue. * Multiple provider states can be defined with data parameters. ## Generating V2 spec pact files To have your consumer tests generate V2 format pacts, you can set the specification version to V2. If you're using the `ConsumerPactTest` base class, you can override the `getSpecificationVersion` method. For example: ```java @Override protected PactSpecVersion getSpecificationVersion() { return PactSpecVersion.V2; } ``` If you are using the `PactProviderRule`, you can pass the version into the constructor for the rule. ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", PactSpecVersion.V2, this); ``` ## Consumer test for a message consumer For testing a consumer of messages from a message queue, the `MessagePactProviderRule` rule class works in much the same way as the `PactProviderRule` class for Request-Response interactions, but will generate a V3 format message pact file. For an example, look at [ExampleMessageConsumerTest](src/test/java/au/com/dius/pact/consumer/v3%2FExampleMessageConsumerTest.java) # Having values injected from provider state callbacks (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods all you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/${id}", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ```

pact-jvm-consumer-junit ======================= Provides a DSL and a base test class for use with Junit to build consumer tests. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-junit_2.12` * version-id = `3.5.x` ## Usage ### Using the base ConsumerPactTest To write a pact spec extend ConsumerPactTestMk2. This base class defines the following four methods which must be overridden in your test class. * *providerName:* Returns the name of the API provider that Pact will mock * *consumerName:* Returns the name of the API consumer that we are testing. * *createFragment:* Returns the PactFragment containing the interactions that the test setup using the ConsumerPactBuilder DSL * *runTest:* The actual test run. It receives the URL to the mock server as a parameter. Here is an example: ```java import au.com.dius.pact.consumer.dsl.PactDslWithProvider; import au.com.dius.pact.consumer.exampleclients.ConsumerClient; import au.com.dius.pact.consumer.ConsumerPactTest; import au.com.dius.pact.model.PactFragment; import org.junit.Assert; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static org.junit.Assert.assertEquals; public class ExampleJavaConsumerPactTest extends ConsumerPactTestMk2 { @Override protected RequestResponsePact createFragment(PactDslWithProvider builder) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); return builder .given("test state") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/") .method("GET") .headers(headers) .willRespondWith() .status(200) .headers(headers) .body("{\"responsetest\": true, \"name\": \"harry\"}") .given("test state 2") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest second test interaction") .method("OPTIONS") .headers(headers) .path("/second") .body("") .willRespondWith() .status(200) .headers(headers) .body("") .toPact(); } @Override protected String providerName() { return "test_provider"; } @Override protected String consumerName() { return "test_consumer"; } @Override protected void runTest(MockServer mockServer) throws IOException { Assert.assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 200); Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); expectedResponse.put("name", "harry"); assertEquals(new ConsumerClient(mockServer.getUrl()).getAsMap("/", ""), expectedResponse); assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 200); } } ``` ### Using the Pact JUnit Rule Thanks to [@warmuuh](https://github.com/warmuuh) we have a JUnit rule that simplifies running Pact consumer tests. To use it, create a test class and then add the rule: #### 1. Add the Pact Rule to your test class to represent your provider. ```java @Rule public PactProviderRuleMk2 mockProvider = new PactProviderRuleMk2("test_provider", "localhost", 8080, this); ``` The hostname and port are optional. If left out, it will default to 127.0.0.1 and a random available port. You can get the URL and port from the pact provider rule. #### 2. Annotate a method with Pact that returns a pact fragment for the provider and consumer ```java @Pact(provider="test_provider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` ##### Versions 3.0.2/2.2.13+ You can leave the provider name out. It will then use the provider name of the first mock provider found. I.e., ```java @Pact(consumer="test_consumer") // will default to the provider name from mockProvider public RequestResponsePact createFragment(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` #### 3. Annotate your test method with PactVerification to have it run in the context of the mock server setup with the appropriate pact from step 1 and 2 ```java @Test @PactVerification("test_provider") public void runTest() { Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient(mockProvider.getUrl()).get("/"), expectedResponse); } ``` ##### Versions 3.0.2/2.2.13+ You can leave the provider name out. It will then use the provider name of the first mock provider found. I.e., ```java @Test @PactVerification public void runTest() { // This will run against mockProvider Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient("http://localhost:8080").get("/"), expectedResponse); } ``` For an example, have a look at [ExampleJavaConsumerPactRuleTest](src/test/java/au/com/dius/pact/consumer/examples/ExampleJavaConsumerPactRuleTest.java) ### Requiring a test with multiple providers The Pact Rule can be used to test with multiple providers. Just add a rule to the test class for each provider, and then include all the providers required in the `@PactVerification` annotation. For an example, look at [PactMultiProviderTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactMultiProviderTest.java). Note that if more than one provider fails verification for the same test, you will only receive a failure for one of them. Also, to have multiple tests in the same test class, the providers must be setup with random ports (i.e. don't specify a hostname and port). Also, if the provider name is left out of any of the annotations, the first one found will be used (which may not be the first one defined). ### Requiring the mock server to run with HTTPS [versions 3.2.7/2.4.9+] From versions 3.2.7/2.4.9+ the mock server can be started running with HTTPS using a self-signed certificate instead of HTTP. To enable this set the `https` parameter to `true`. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, PactSpecVersion.V2, this); // ^^^^ ``` For an example test doing this, see [PactProviderHttpsTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderHttpsTest.java). **NOTE:** The provider will start handling HTTPS requests using a self-signed certificate. Most HTTP clients will not accept connections to a self-signed server as the certificate is untrusted. You may need to enable insecure HTTPS with your client for this test to work. For an example of how to enable insecure HTTPS client connections with Apache Http Client, have a look at [InsecureHttpsRequest](src/test/java/org/apache/http/client/fluent/InsecureHttpsRequest.java). ### Requiring the mock server to run with HTTPS with a keystore [versions 3.4.1+] From versions 3.4.1+ the mock server can be started running with HTTPS using a keystore. To enable this set the `https` parameter to `true`, set the keystore path/file, and the keystore's password. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, "/path/to/your/keystore.jks", "your-keystore-password", PactSpecVersion.V2, this); ``` For an example test doing this, see [PactProviderHttpsKeystoreTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderHttpsKeystoreTest.java). ### Setting default expected request and response values [versions 3.5.10+] If you have a lot of tests that may share some values (like headers), you can setup default values that will be applied to all the expected requests and responses for the tests. To do this, you need to create a method that takes single parameter of the appropriate type (`PactDslRequestWithoutPath` or `PactDslResponse`) and annotate it with the default marker annotation (`@DefaultRequestValues` or `@DefaultResponseValues`). For example: ```java @DefaultRequestValues public void defaultRequestValues(PactDslRequestWithoutPath request) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); request.headers(headers); } @DefaultResponseValues public void defaultResponseValues(PactDslResponse response) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testresheader", "testresheadervalue"); response.headers(headers); } ``` For an example test that uses these, have a look at [PactProviderWithMultipleFragmentsTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactProviderWithMultipleFragmentsTest.java) ### Note on HTTP clients and persistent connections Some HTTP clients may keep the connection open, based on the live connections settings or if they use a connection cache. This could cause your tests to fail if the client you are testing lives longer than an individual test, as the mock server will be started and shutdown for each test. This will result in the HTTP client connection cache having invalid connections. For an example of this where the there was a failure for every second test, see [Issue #342](https://github.com/DiUS/pact-jvm/issues/342). ### Using the Pact DSL directly Sometimes it is not convenient to use the ConsumerPactTest as it only allows one test per test class. The DSL can be used directly in this case. Example: ```java import au.com.dius.pact.consumer.ConsumerPactBuilder; import au.com.dius.pact.consumer.PactVerificationResult; import au.com.dius.pact.consumer.exampleclients.ProviderClient; import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.RequestResponsePact; import org.junit.Test; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static au.com.dius.pact.consumer.ConsumerPactRunnerKt.runConsumerTest; import static org.junit.Assert.assertEquals; /** * Sometimes it is not convenient to use the ConsumerPactTest as it only allows one test per test class. * The DSL can be used directly in this case. */ public class DirectDSLConsumerPactTest { @Test public void testPact() { RequestResponsePact pact = ConsumerPactBuilder .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request to say Hello") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .toPact(); MockProviderConfig config = MockProviderConfig.createDefault(); PactVerificationResult result = runConsumerTest(pact, config, mockServer -> { Map expectedResponse = new HashMap(); expectedResponse.put("hello", "harry"); try { assertEquals(new ProviderClient(mockServer.getUrl()).hello("{\"name\": \"harry\"}"), expectedResponse); } catch (IOException e) { throw new RuntimeException(e); } }); if (result instanceof PactVerificationResult.Error) { throw new RuntimeException(((PactVerificationResult.Error)result).getError()); } assertEquals(PactVerificationResult.Ok.INSTANCE, result); } } ``` ### The Pact JUnit DSL The DSL has the following pattern: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .given("a certain state on the provider") .uponReceiving("a request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .uponReceiving("another request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") . . . .toPact() ``` You can define as many interactions as required. Each interaction starts with `uponReceiving` followed by `willRespondWith`. The test state setup with `given` is a mechanism to describe what the state of the provider should be in before the provider is verified. It is only recorded in the consumer tests and used by the provider verification tasks. ### Building JSON bodies with PactDslJsonBody DSL **NOTE:** If you are using Java 8, there is [an updated DSL for consumer tests](../pact-jvm-consumer-java8). The body method of the ConsumerPactBuilder can accept a PactDslJsonBody, which can construct a JSON body as well as define regex and type matchers. For example: ```java PactDslJsonBody body = new PactDslJsonBody() .stringType("name") .booleanType("happy") .hexValue("hexCode") .id() .ipAddress("localAddress") .numberValue("age", 100) .timestamp(); ``` #### DSL Matching methods The following matching methods are provided with the DSL. In most cases, they take an optional value parameter which will be used to generate example values (i.e. when returning a mock response). If no example value is given, a random one will be generated. | method | description | |--------|-------------| | string, stringValue | Match a string value (using string equality) | | number, numberValue | Match a number value (using Number.equals)\* | | booleanValue | Match a boolean value (using equality) | | stringType | Will match all Strings | | numberType | Will match all numbers\* | | integerType | Will match all numbers that are integers (both ints and longs)\* | | decimalType | Will match all real numbers (floating point and decimal)\* | | booleanType | Will match all boolean values (true and false) | | stringMatcher | Will match strings using the provided regular expression | | timestamp | Will match string containing timestamps. If a timestamp format is not given, will match an ISO timestamp format | | date | Will match string containing dates. If a date format is not given, will match an ISO date format | | time | Will match string containing times. If a time format is not given, will match an ISO time format | | ipAddress | Will match string containing IP4 formatted address. | | id | Will match all numbers by type | | hexValue | Will match all hexadecimal encoded strings | | uuid | Will match strings containing UUIDs | | includesStr | Will match strings containing the provided string | | equalsTo | Will match using equals | | matchUrl | Defines a matcher for URLs, given the base URL path and a sequence of path fragments. The path fragments could be strings or regular expression matchers | _\* Note:_ JSON only supports double precision floating point values. Depending on the language implementation, they may parsed as integer, floating point or decimal numbers. #### Ensuring all items in a list match an example (2.2.0+) Lots of the time you might not know the number of items that will be in a list, but you want to ensure that the list has a minimum or maximum size and that each item in the list matches a given example. You can do this with the `arrayLike`, `minArrayLike` and `maxArrayLike` functions. | function | description | |----------|-------------| | `eachLike` | Ensure that each item in the list matches the provided example | | `maxArrayLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `minArrayLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java DslPart body = new PactDslJsonBody() .minArrayLike("users", 1) .id() .stringType("name") .closeObject() .closeArray(); ``` This will ensure that the users list is never empty and that each user has an identifier that is a number and a name that is a string. __Version 3.2.4/2.4.6+__ You can specify the number of example items to generate in the array. The default is 1. ```java DslPart body = new PactDslJsonBody() .minArrayLike("users", 1, 2) .id() .stringType("name") .closeObject() .closeArray(); ``` This will generate the example body with 2 items in the users list. #### Root level arrays that match all items (version 2.2.11+) If the root of the body is an array, you can create PactDslJsonArray classes with the following methods: | function | description | |----------|-------------| | `arrayEachLike` | Ensure that each item in the list matches the provided example | | `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java PactDslJsonArray.arrayEachLike() .date("clearedDate", "mm/dd/yyyy", date) .stringType("status", "STATUS") .decimalType("amount", 100.0) .closeObject() ``` This will then match a body like: ```json [ { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 } ] ``` __Version 3.2.4/2.4.6+__ You can specify the number of example items to generate in the array. The default is 1. #### Matching JSON values at the root (Version 3.2.2/2.4.3+) For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request for a basic JSON value") .path("/hello") .willRespondWith() .status(200) .body(PactDslJsonRootValue.integerType()) ``` #### Matching any key in a map (3.3.1/2.5.0+) The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/313). In this case you can use the `eachKeyLike` method, which takes an example key as a parameter. For example: ```java DslPart body = new PactDslJsonBody() .object("one") .eachKeyLike("001", PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher .closeObject() .object("two") .eachKeyLike("001-A") // key like an id where the value is matched by the following example .stringType("description", "Some Description") .closeObject() .closeObject() .object("three") .eachKeyMappedToAnArrayLike("001") // key like an id mapped to an array where each item is matched by the following example .id("someId", 23456L) .closeObject() .closeArray() .closeObject(); ``` For an example, have a look at [WildcardKeysTest](src/test/java/au/com/dius/pact/consumer/WildcardKeysTest.java). **NOTE:** The `eachKeyLike` method adds a `*` to the matching path, so the matching definition will be applied to all keys of the map if there is not a more specific matcher defined for a particular key. Having more than one `eachKeyLike` condition applied to a map will result in only one being applied when the pact is verified (probably the last). **Further Note: From version 3.5.22 onwards pacts with wildcards applied to map keys will require the Java system property "pact.matching.wildcard" set to value "true" when the pact file is verified.** #### Combining matching rules with AND/OR Matching rules can be combined with AND/OR. There are two methods available on the DSL for this. For example: ```java DslPart body = new PactDslJsonBody() .numberValue("valueA", 100) .and("valueB","AB", PM.includesStr("A"), PM.includesStr("B")) // Must match both matching rules .or("valueC", null, PM.date(), PM.nullValue()) // will match either a valid date or a null value ``` The `and` and `or` methods take a variable number of matchers (varargs). ### Matching on paths (version 2.1.5+) You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide a real path as a second value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .matchPath("/transaction/[0-9]+") // or .matchPath("/transaction/[0-9]+", "/transaction/1234567890") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ### Matching on headers (version 2.2.2+) You can use regular expressions to match request and response headers. The DSL has a `matchHeader` method for this. You can provide an example header value to use when generating requests and responses, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchHeader("testreqheader", "test.*value") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .matchHeader("Location", ".*/hello/[0-9]+", "/hello/1234") ``` ### Matching on query parameters (version 3.3.7+) You can use regular expressions to match request query parameters. The DSL has a `matchQuery` method for this. You can provide an example value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchQuery("a", "\\d+", "100") .matchQuery("b", "[A-Z]", "X") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ## Debugging pact failures When the test runs, Pact will start a mock provider that will listen for requests and match them against the expectations you setup in `createFragment`. If the request does not match, it will return a 500 error response. Each request received and the generated response is logged using [SLF4J](http://www.slf4j.org/). Just enable debug level logging for au.com.dius.pact.consumer.UnfilteredMockProvider. Most failures tend to be mismatched headers or bodies. ## Changing the directory pact files are written to (2.1.9+) By default, pact files are written to `target/pacts`, but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/pacts" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.build.directory}</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` # Publishing your pact files to a pact broker If you use Gradle, you can use the [pact Gradle plugin](https://github.com/DiUS/pact-jvm/tree/master/pact-jvm-provider-gradle#publishing-pact-files-to-a-pact-broker) to publish your pact files. # Pact Specification V3 Version 3 of the pact specification changes the format of pact files in the following ways: * Query parameters are stored in a map form and are un-encoded (see [#66](https://github.com/DiUS/pact-jvm/issues/66) and [#97](https://github.com/DiUS/pact-jvm/issues/97) for information on what this can cause). * Introduces a new message pact format for testing interactions via a message queue. * Multiple provider states can be defined with data parameters. ## Generating V2 spec pact files (3.1.0+, 2.3.0+) To have your consumer tests generate V2 format pacts, you can set the specification version to V2. If you're using the `ConsumerPactTest` base class, you can override the `getSpecificationVersion` method. For example: ```java @Override protected PactSpecVersion getSpecificationVersion() { return PactSpecVersion.V2; } ``` If you are using the `PactProviderRuleMk2`, you can pass the version into the constructor for the rule. ```java @Rule public PactProviderRuleMk2 mockTestProvider = new PactProviderRuleMk2("test_provider", PactSpecVersion.V2, this); ``` ## Consumer test for a message consumer For testing a consumer of messages from a message queue, the `MessagePactProviderRule` rule class works in much the same way as the `PactProviderRule` class for Request-Response interactions, but will generate a V3 format message pact file. For an example, look at [ExampleMessageConsumerTest](https://github.com/DiUS/pact-jvm/blob/master/pact-jvm-consumer-junit%2Fsrc%2Ftest%2Fjava%2Fau%2Fcom%2Fdius%2Fpact%2Fconsumer%2Fv3%2FExampleMessageConsumerTest.java)