Download jvm-npm-rhino JAR file with all dependencies
pact-jvm-provider-maven_2.10 from group au.com.dius (version 2.4.11)
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>
```
pact-jvm-provider-junit_2.10 from group au.com.dius (version 2.4.11)
# Pact junit runner
## Overview
Library provides ability to play contract tests against a provider service in JUnit fashionable way.
Supports:
- Out-of-the-box convenient ways to load pacts
- Easy way to change assertion strategy
- **org.junit.BeforeClass**, **org.junit.AfterClass** and **org.junit.ClassRule** JUnit annotations, that will be run
once - before/after whole contract test suite.
- **org.junit.Before**, **org.junit.After** and **org.junit.Rule** JUnit annotations, that will be run before/after
each test of an interaction.
- **au.com.dius.pact.provider.junit.State** custom annotation - before each interaction that requires a state change,
all methods annotated by `@State` with appropriate the state listed will be invoked.
## Example of HTTP test
```java
@RunWith(PactRunner.class) // Say JUnit to run tests with custom Runner
@Provider("myAwesomeService") // Set up name of tested provider
@PactFolder("pacts") // Point where to find pacts (See also section Pacts source in documentation)
public class ContractTest {
// NOTE: this is just an example of embedded service that listens to requests, you should start here real service
@ClassRule //Rule will be applied once: before/after whole contract test suite
public static final ClientDriverRule embeddedService = new ClientDriverRule(8332);
@BeforeClass //Method will be run once: before whole contract test suite
public static void setUpService() {
//Run DB, create schema
//Run service
//...
}
@Before //Method will be run before each test of interaction
public void before() {
// Rest data
// Mock dependent service responses
// ...
embeddedService.addExpectation(
onRequestTo("/data"), giveEmptyResponse()
);
}
@State("default", "no-data") // Method will be run before testing interactions that require "default" or "no-data" state
public void toDefaultState() {
// Prepare service before interaction that require "default" state
// ...
System.out.println("Now service in default state");
}
@TestTarget // Annotation denotes Target that will be used for tests
public final Target target = new HttpTarget(8332); // Out-of-the-box implementation of Target (for more information take a look at Test Target section)
}
```
## Example of AMQP Message test
```java
@RunWith(PactRunner.class) // Say JUnit to run tests with custom Runner
@Provider("myAwesomeService") // Set up name of tested provider
@PactBroker(host="pactbroker", port = "80")
public class ConfirmationKafkaContractTest {
@TestTarget // Annotation denotes Target that will be used for tests
public final Target target = new AmqpTarget(); // Out-of-the-box implementation of Target (for more information take a look at Test Target section)
@BeforeClass //Method will be run once: before whole contract test suite
public static void setUpService() {
//Run DB, create schema
//Run service
//...
}
@Before //Method will be run before each test of interaction
public void before() {
// Message data preparation
// ...
}
@PactVerifyProvider('an order confirmation message')
String verifyMessageForOrder() {
Order order = new Order()
order.setId(10000004)
order.setPrice(BigDecimal.TEN)
order.setUnits(15)
def message = new ConfirmationKafkaMessageBuilder()
.withOrder(order)
.build()
JsonOutput.toJson(message)
}
}
```
## Pact source
The Pact runner will automatically collect pacts based on annotations on the test class. For this purpose there are 3
out-of-the-box options (files from a directory, files from a set of URLs or a pact broker) or you can easily add your
own Pact source.
**Note:** You can only define one source of pacts per test class.
### Download pacts from a pact-broker
To use pacts from a Pact Broker, annotate the test class with `@PactBroker(host="host.of.pact.broker.com", port = "80")`.
From _version 3.2.2/2.4.3+_ you can also specify the protocol, which defaults to "http".
The pact broker will be queried for all pacts with the same name as the provider annotation.
For example, test all pacts for the "Activity Service" in the pact broker:
```java
@RunWith(PactRunner.class)
@Provider("Activity Service")
@PactBroker(host = "localhost", port = "80")
public class PactJUnitTest {
@TestTarget
public final Target target = new HttpTarget(5050);
}
```
#### _Version 3.2.3/2.4.4+_ - Using Java System properties
The pact broker loader was updated to allow system properties to be used for the hostname, port or protocol. The port
was changed to a string to allow expressions to be set.
To use a system property or environment variable, you can place the property name in `${}` expression de-markers:
```java
@PactBroker(host="${pactbroker.hostname}", port = "80")
```
You can provide a default value by separating the property name with a colon (`:`):
```java
@PactBroker(host="${pactbroker.hostname:localhost}", port = "80")
```
#### _Version ???/???+_ - More Java System properties
The default values of the `@PactBroker` annotation now enable variable interpolation.
The following keys may be managed through the environment
* `pactbroker.host`
* `pactbroker.port`
* `pactbroker.protocol`
* `pactbroker.tags` (comma separated)
* `pactbroker.auth.scheme`
* `pactbroker.auth.username`
* `pactbroker.auth.password`
#### _Version 3.2.4/2.4.6+_ - Using tags with the pact broker
The pact broker allows different versions to be tagged. To load all the pacts:
```java
@PactBroker(host="pactbroker", port = "80", tags = {"latest", "dev", "prod"})
```
The default value for tags is `latest` which is not actually a tag but instead corresponds to the latest version ignoring the tags. If there are multiple consumers matching the name specified in the provider annotation then the latest pact for each of the consumers is loaded.
For any other value the latest pact tagged with the specified tag is loaded.
Specifying multiple tags is an OR operation. For example if you specify `tags = {"dev", "prod"}` then both the latest pact file tagged with `dev` and the latest pact file taggged with `prod` is loaded.
#### _Version 3.3.4/2.4.19+_ - Using basic auth with the with the pact broker
You can use basic authentication with the `@PactBroker` annotation by setting the `authentication` value to a `@PactBrokerAuth`
annotation. For example:
```java
@PactBroker(host = "${pactbroker.url:localhost}", port = "1234", tags = {"latest", "prod", "dev"},
authentication = @PactBrokerAuth(username = "test", password = "test"))
```
The `username` and `password` values also take Java system property expressions.
### Pact Url
To use pacts from urls annotate the test class with
```java
@PactUrl(urls = {"http://build.server/zoo_app-animal_service.json"} )
```
### Pact folder
To use pacts from a resource folder of the project annotate test class with
```java
@PactFolder("subfolder/in/resource/directory")
```
### Custom pacts source
It's possible to use a custom Pact source. For this, implement interface `au.com.dius.pact.provider.junit.loader.PactLoader`
and annotate the test class with `@PactSource(MyOwnPactLoader.class)`. **Note:** class `MyOwnPactLoader` must have a default empty constructor or a constructor with one argument of class `Class` which at runtime will be the test class so you can get custom annotations of test class.
## Test target
The field in test class of type `au.com.dius.pact.provider.junit.target.Target` annotated with `au.com.dius.pact.provider.junit.target.TestTarget`
will be used for actual Interaction execution and asserting of contract.
**Note:** there must be exactly 1 such field, otherwise an `InitializationException` will be thrown.
### HttpTarget
`au.com.dius.pact.provider.junit.target.HttpTarget` - out-of-the-box implementation of `au.com.dius.pact.provider.junit.target.Target`
that will play pacts as http request and assert response from service by matching rules from pact.
_Version 3.2.2/2.4.3+_ you can also specify the protocol, defaults to "http".
### AmqpTarget
`au.com.dius.pact.provider.junit.target.AmqpTarget` - out-of-the-box implementation of `au.com.dius.pact.provider.junit.target.Target`
that will play pacts as an AMQP message and assert response from service by matching rules from pact.
#### Modifying the requests before they are sent [Version 3.2.3/2.4.5+]
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 HttpTarget supports request filters by annotating methods
on the test class with `@TargetRequestFilter`. These methods must be public void methods that take a single HttpRequest
parameter.
For example:
```java
@TargetRequestFilter
public void exampleRequestFilter(HttpRequest request) {
request.addHeader("Authorization", "OAUTH hdsagasjhgdjashgdah...");
}
```
__*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 [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.
### Custom Test Target
It's possible to use custom `Target`, for that interface `Target` should be implemented and this class can be used instead of `HttpTarget`.
# Verification Reports [versions 3.2.7/2.4.9+]
The default test behaviour is to display the verification being done to the console, and pass or fail the test via the normal
JUnit mechanism. From versions 3.2.7/2.4.9+, additional reports can be generated from the tests.
## Enabling additional reports via annotations on the test classes
A `@VerificationReports` annotation can be added to any pact test class which will control the verification output. The
annotation takes a list report types and an optional report directory (defaults to "target/pact/reports").
The currently supported report types are `console`, `markdown` and `json`.
For example:
```java
@VerificationReports({"console", "markdown"})
public class MyPactTest {
```
will enable the markdown report in addition to the normal console output. And,
```java
@VerificationReports(value = {"markdown"}, reportDir = "/myreports")
public class MyPactTest {
```
will disable the normal console output and write the markdown reports to "/myreports".
## Enabling additional reports via Java system properties or environment variables
The additional reports can also be enabled with Java System properties or environment variables. The following two
properties have been introduced: `pact.verification.reports` and `pact.verification.reportDir`.
`pact.verification.reports` is the comma separated list of report types to enable (e.g. `console,json,markdown`).
`pact.verification.reportDir` is the directory to write reports to (defaults to "target/pact/reports").
## Additional Reports
The following report types are available in addition to console output (`console`, which is enabled by default):
`markdown`, `json`.
You can also provide a fully qualified classname as report so custom reports are also supported.
This class must implement `au.com.dius.pact.provider.reporters.VerifierReporter` interface in order to be correct custom implementation of a report.
objectfabric-jvm from group org.objectfabric (version 0.9.1)
pact-jvm-provider-gradle_2.10 from group au.com.dius (version 2.4.11)
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.
## 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_2.10:2.2.1'
}
}
```
#### 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 "2.2.1"
}
```
### 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()
pactFile = 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')
}
}
}
}
```
## Starting and shutting down your provider
If you need to start-up or shutdown your provider, you can define a start and terminate task for 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') << {
// start up your provider here
}
// This will be called after the provider task
task('killTheApp') << {
// 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).
## 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` 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 [version 2.2.8+]
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 [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:
```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
**NOTE on breaking change: Version 2.1.8+ uses Apache HttpClient instead of HttpBuilder so the closure will receive a
HttpRequest object instead of a request Map.**
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')
}
}
}
}
```
## 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.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|
## Provider States
For a description of what provider states are, see the wiki in the Ruby project:
https://github.com/realestate-com-au/pact/wiki/Provider-states
### 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 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')
stateChange = 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')
stateChange = 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 will be sent as
JSON in the body of the request. If it is set to false, it will passed as a query parameter.
### Using a Closure [version 2.2.2+]
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 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 ->
def fixture = loadFixtuerForProviderState(providerState)
setupDatabase(fixture)
}
}
}
}
}
```
## 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 [version 3.1.1+/2.3.1+]
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 {
hasPactsFromPactBroker('http://pact-broker:5000/')
}
}
}
```
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 }
}
}
}
}
}
```
# Publishing pact files to a pact broker [version 2.2.7+]
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'
}
}
```
_NOTE:_ The pact broker requires a version for all published pacts. The `pactPublish` task will use the version of the
gradle project. Make sure you have set one otherwise the broker will reject the pact files.
# Verifying a message provider [version 2.2.12+]
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 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'))
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.
## Publishing to the Gradle Community Portal
To publish the plugin to the community portal:
$ ./gradlew :pact-jvm-provider-gradle_2.11:publishPlugins
0 downloads
pact-jvm-model_2.10 from group au.com.dius (version 2.4.11)
Pact model
==========
The model project is responsible for providing:
* a model to represent pacts
* serialization and deserialization
* comparison between two parts of the pact model
* conversion between the pact model and whatever third party libraries used by the pact-consumer and pact-provider requires
You should never need to include this project directly
pact-jvm-matchers_2.10 from group au.com.dius (version 2.4.11)
Pact JVM Matchers
=================
Implements matchers for pact requests and responses.
pact-jvm-logging_2.11 from group au.com.dius (version 2.4.11)
pact-jvm-loggin
---------------
Inlined logging from https://github.com/typesafehub/scalalogging to support both Scala 2.10 and 2.11
pact-jvm-logging_2.10 from group au.com.dius (version 2.4.11)
pact-jvm-loggin
---------------
Inlined logging from https://github.com/typesafehub/scalalogging to support both Scala 2.10 and 2.11
pact-jvm-consumer_2.10 from group au.com.dius (version 2.4.11)
Pact consumer
=============
Pact Consumer is used by projects that are consumers of an API.
Most projects will want to use pact-consumer via one of the test framework specific projects. If your favourite
framework is not implemented, this module should give you all the hooks you need.
Provides a DSL for use with Java to build consumer pacts.
## Dependency
The library is available on maven central using:
* group-id = `au.com.dius`
* artifact-id = `pact-jvm-consumer_2.11`
## DSL Usage
Example in a JUnit test:
```java
import au.com.dius.pact.model.MockProviderConfig;
import au.com.dius.pact.model.PactFragment;
import org.junit.Test;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import static org.junit.Assert.assertEquals;
public class PactTest {
@Test
public void testPact() {
PactFragment pactFragment = 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\"}")
.toFragment();
MockProviderConfig config = MockProviderConfig.createDefault();
VerificationResult result = pactFragment.runConsumer(config, new TestRun() {
@Override
public void run(MockProviderConfig config) {
Map expectedResponse = new HashMap();
expectedResponse.put("hello", "harry");
try {
assertEquals(new ProviderClient(config.url()).hello("{\"name\": \"harry\"}"),
expectedResponse);
} catch (IOException e) {}
}
});
if (result instanceof PactError) {
throw new RuntimeException(((PactError)result).error());
}
assertEquals(ConsumerPactTest.PACT_VERIFIED, result);
}
}
```
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\"}")
.
.
.
.toFragment()
```
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
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 |
_\* 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")
.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.
#### 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())
```
#### 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
} ]
```
#### Matching arrays of arrays (version 3.2.12/2.4.14+)
For the case where you have arrays of arrays (GeoJSON is an example), the following methods have been provided:
| function | description |
|----------|-------------|
| `eachArrayLike` | Ensure that each item in the array is an array that matches the provided example |
| `eachArrayWithMaxLike` | Ensure that each item in the array is an array that matches the provided example and the array is no bigger than the provided max |
| `eachArrayWithMinLike` | Ensure that each item in the array is an array that matches the provided example and the array is no smaller than the provided min |
For example (with GeoJSON structure):
```java
new PactDslJsonBody()
.stringType("type","FeatureCollection")
.eachLike("features")
.stringType("type","Feature")
.object("geometry")
.stringType("type","Point")
.eachArrayLike("coordinates") // coordinates is an array of arrays
.decimalType(-7.55717)
.decimalType(49.766896)
.closeArray()
.closeArray()
.closeObject()
.object("properties")
.stringType("prop0","value0")
.closeObject()
.closeObject()
.closeArray()
```
This generated the following JSON:
```json
{
"features": [
{
"geometry": {
"coordinates": [[-7.55717, 49.766896]],
"type": "Point"
},
"type": "Feature",
"properties": { "prop0": "value0" }
}
],
"type": "FeatureCollection"
}
```
and will be able to match all coordinates regardless of the number of coordinates.
#### 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/131). 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).
### 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\"}")
```
pact-jvm-consumer-specs2_2.10 from group au.com.dius (version 2.4.11)
pact-jvm-consumer-specs2
========================
## Specs2 Bindings for the pact-jvm library
## Dependency
In the root folder of your project in build.sbt add the line:
```scala
libraryDependencies += "au.com.dius" %% "pact-jvm-consumer-specs2" % "3.2.2"
```
or if you are using Gradle:
```groovy
dependencies {
testCompile "au.com.dius:pact-jvm-consumer-specs2_2.11:3.2.2"
}
```
__*Note:*__ `PactSpec` requires spec2 3.x. Also, for spray users there's an incompatibility between specs2 v3.x and spray.
Follow these instructions to resolve that problem: https://groups.google.com/forum/#!msg/spray-user/2T6SBp4OJeI/AJlnJuAKPRsJ
## Usage
To author a test, mix `PactSpec` into your spec
First we define a service client called `ConsumerService`. In our example this is a simple wrapper for `dispatch`, an HTTP client. The source code can be found in the test folder alongside the `ExamplePactSpec`.
Here is a simple example:
```
import au.com.dius.pact.consumer.PactSpec
class ExamplePactSpec extends Specification with PactSpec {
val consumer = "My Consumer"
val provider = "My Provider"
override def is = uponReceiving("a request for foo")
.matching(path = "/foo")
.willRespondWith(body = "{}")
.withConsumerTest { providerConfig =>
Await.result(ConsumerService(providerConfig.url).simpleGet("/foo"), Duration(1000, MILLISECONDS)) must beEqualTo(200, Some("{}"))
}
}
```
This spec will be run along with the rest of your specs2 unit tests and will output your pact json to
```
/target/pacts/<Consumer>_<Provider>.json
```
0 downloads
pact-jvm-consumer-junit_2.10 from group au.com.dius (version 2.4.11)
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.11`
* version-id = `3.0.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 ConsumerPactTest {
@Override
protected PactFragment 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("")
.toFragment();
}
@Override
protected String providerName() {
return "test_provider";
}
@Override
protected String consumerName() {
return "test_consumer";
}
@Override
protected void runTest(String url) throws IOException {
Assert.assertEquals(new ConsumerClient(url).options("/second"), 200);
Map expectedResponse = new HashMap();
expectedResponse.put("responsetest", true);
expectedResponse.put("name", "harry");
assertEquals(new ConsumerClient(url).getAsMap("/", ""), expectedResponse);
assertEquals(new ConsumerClient(url).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 localhost and a random available port.
#### 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 PactFragment createFragment(PactDslWithProvider builder) {
return builder
.given("test state")
.uponReceiving("ExampleJavaConsumerPactRuleTest test interaction")
.path("/")
.method("GET")
.willRespondWith()
.status(200)
.body("{\"responsetest\": true}")
.toFragment();
}
```
##### 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 PactFragment createFragment(PactDslWithProvider builder) {
return builder
.given("test state")
.uponReceiving("ExampleJavaConsumerPactRuleTest test interaction")
.path("/")
.method("GET")
.willRespondWith()
.status(200)
.body("{\"responsetest\": true}")
.toFragment();
}
```
#### 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("http://localhost:8080").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,
PactConfig.apply(PactSpecVersion.V2), this); // ^^^^
```
For an exmaple 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).
### 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.ConsumerPactTest;
import au.com.dius.pact.consumer.PactError;
import au.com.dius.pact.consumer.TestRun;
import au.com.dius.pact.consumer.VerificationResult;
import au.com.dius.pact.consumer.examples.client.ProviderClient;
import au.com.dius.pact.model.MockProviderConfig;
import au.com.dius.pact.model.PactFragment;
import org.junit.Test;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import static org.junit.Assert.assertEquals;
public class PactTest {
@Test
public void testPact() {
PactFragment pactFragment = 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\"}")
.toFragment();
MockProviderConfig config = MockProviderConfig.createDefault();
VerificationResult result = pactFragment.runConsumer(config, new TestRun() {
@Override
public void run(MockProviderConfig config) {
Map expectedResponse = new HashMap();
expectedResponse.put("hello", "harry");
try {
assertEquals(new ProviderClient(config.url()).hello("{\"name\": \"harry\"}"),
expectedResponse);
} catch (IOException e) {
throw new RuntimeException(e);
}
}
});
if (result instanceof PactError) {
throw new RuntimeException(((PactError)result).error());
}
assertEquals(ConsumerPactTest.PACT_VERIFIED, 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\"}")
.
.
.
.toFragment()
```
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
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 |
_\* 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).
### 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.
## Generating V3 spec pact files (3.1.0+, 2.3.0+)
To have your consumer tests generate V3 format pacts, you can set the specification version to V3. If you're using the
`ConsumerPactTest` base class, you can override the `getSpecificationVersion` method. For example:
```java
@Override
protected PactSpecVersion getSpecificationVersion() {
return PactSpecVersion.V3;
}
```
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.V3, 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)
jvm-sdk_2.10 from group io.sphere.sdk.jvm (version 1.0.0-M6)
jvm-sdk
pact-jvm-server_2.11 from group au.com.dius (version 3.2.7)
Pact server
===========
The pact server is a stand-alone interactions recorder and verifier, aimed at clients that are non-JVM or non-Ruby based.
The pact client for that platform will need to be implemented, but it only be responsible for generating the `JSON`
interactions, running the tests and communicating with the server.
The server implements a `JSON` `REST` Admin API with the following endpoints.
/ -> For diagnostics, currently returns a list of ports of the running mock servers.
/create -> For initialising a test server and submitting the JSON interactions. It returns a port
/complete -> For finalising and verifying the interactions with the server. It writes the `JSON` pact file to disk.
## Running the server
### Versions 2.2.6+
Pact server takes the following parameters:
```
Usage: pact-jvm-server [options] [port]
port
port to run on (defaults to 29999)
--help
prints this usage text
-h <value> | --host <value>
host to bind to (defaults to localhost)
-l <value> | --mock-port-lower <value>
lower bound to allocate mock ports (defaults to 20000)
-u <value> | --mock-port-upper <value>
upper bound to allocate mock ports (defaults to 40000)
-d | --daemon
run as a daemon process
--debug
run with debug logging
```
### Prior to version 2.2.6
Pact server takes one optional parameter, the port number to listen on. If not provided, it will listen on 29999.
It requires an active console to run.
### Using a distribution archive
You can download a [distribution from maven central](http://search.maven.org/remotecontent?filepath=au/com/dius/pact-jvm-server_2.11/2.2.4/).
There is both a ZIP and TAR archive. Unpack it to a directory of choice and then run the script in the bin directory.
### Building a distribution bundle
You can build an application bundle with gradle by running (for 2.11 version):
$ ./gradlew :pact-jvm-server_2.11:installdist
This will create an app bundle in `build/2.11/install/pact-jvm-server_2.11`. You can then execute it with:
$ java -jar pact-jvm-server/build/2.10/install/pact-jvm-server_2.11/lib/pact-jvm-server_2.11-2.2.4.jar
or with the generated bundle script file:
$ pact-jvm-server/build/2.11/install/pact-jvm-server_2.11/bin/pact-jvm-server_2.11
By default will run on port `29999` but a port number can be optionally supplied.
### Running it with docker
You can use a docker image to execute the mock server as a docker container.
$ docker run -d -p 8080:8080 -p 20000-20010:20000-20010 uglyog/pact-jvm-server
This will run the main server on port 8080, and each created mock server on ports 20000-20010. You can map the ports to
any you require.
## Life cycle
The following actions are expected to occur
* The client calls `/create` to initialise a server with the expected `JSON` interactions and state
* The admin server will start a mock server on a random port and return the port number in the response
* The client will execute its interaction tests against the mock server with the supplied port
* Once finished, the client will call `/complete' on the Admin API, posting the port number
* The pact server will verify the interactions and write the `JSON` `pact` file to disk under `/target`
* The mock server running on the supplied port will be shutdown.
## Endpoints
### /create
The client will need `POST` to `/create` the generated `JSON` interactions, also providing a state as a query parameter.
For example:
POST http://localhost:29999/create?state=NoUsers '{ "provider": { "name": "Animal_Service"}, ... }'
This will create a new running mock service provider on a randomly generated port. The port will be returned in the
`201` response:
{ "port" : 34423 }
### /complete
Once the client has finished running its tests against the mock server on the supplied port (in this example port
`34423`) the client will need to `POST` to `/complete` the port number of the mock server that was used.
For example:
POST http://localhost:29999/complete '{ "port" : 34423 }'
This will cause the Pact server to verify the interactions, shutdown the mock server running on that port and writing
the pact `JSON` file to disk under the `target` directory.
### /
The `/` endpoint is for diagnostics and to check that the pact server is running. It will return all the currently
running mock servers port numbers.
For example:
GET http://localhost:29999/
'{ "ports": [23443,43232] }'
pact-jvm-provider_2.11 from group au.com.dius (version 3.2.7)
Pact provider
=============
sub project of https://github.com/DiUS/pact-jvm
The pact provider is responsible for verifying that an API provider adheres to a number of pacts authored by its clients
This library provides the basic tools required to automate the process, and should be usable on its own in many instances.
Framework and build tool specific bindings will be provided in separate libraries that build on top of this core functionality.
### Running Pacts
Main takes 2 arguments:
The first is the root folder of your pact files
(all .json files in root and subfolders are assumed to be pacts)
The second is the location of your pact config json file.
### Pact config
The pact config is a simple mapping of provider names to endpoint url's
paths will be appended to endpoint url's when interactions are attempted
for an example see: https://github.com/DiUS/pact-jvm/blob/master/pact-jvm-provider/src/test/resources/pact-config.json
### Provider State
Before each interaction is executed, the provider under test will have the opportunity to enter a state.
Generally the state maps to a set of fixture data for mocking out services that the provider is a consumer of (they will have their own pacts)
The pact framework will instruct the test server to enter that state by sending:
POST "${config.stateChangeUrl.url}/setup" { "state" : "${interaction.stateName}" }
### An example of running provider verification with junit
This example uses java, junit and hamcrest matchers to run the provider verification.
As the provider service is a DropWizard application, it uses the DropwizardAppRule to startup the service before running any test.
Warning: It only grabs the first interaction from the pact file with the consumer, where there could be many. (This could possibly be solved with a parameterized test)
```java
public class PactJVMProviderJUnitTest {
@ClassRule
public static TestRule startServiceRule = new DropwizardAppRule<DropwizardAppConfig>(DropwizardApp.class, "config.yml");
private static ProviderInfo serviceProvider;
private static Pact testConsumerPact;
@BeforeClass
public static void setupProvider() {
serviceProvider = new ProviderInfo("Dropwizard App");
serviceProvider.setProtocol("http");
serviceProvider.setHost("localhost");
serviceProvider.setPort(8080);
serviceProvider.setPath("/");
ConsumerInfo consumer = new ConsumerInfo();
consumer.setName("test_consumer");
consumer.setPactFile(new File("target/pacts/ping_client-ping_service.json"));
// serviceProvider.getConsumers().add(consumer);
testConsumerPact = (Pact) new PactReader().loadPact(consumer.getPactFile());
}
@Test
@SuppressWarnings("unchecked")
public void runConsumerPacts() {
//grab the first interaction from the pact with consumer
List<Interaction> interactions = scala.collection.JavaConversions.seqAsJavaList(testConsumerPact.interactions());
Interaction interaction1 = interactions.get(0);
//setup any provider state
//setup the client and interaction to fire against the provider
ProviderClient client = new ProviderClient();
client.setProvider(serviceProvider);
client.setRequest(interaction1.request());
Map<String, Object> clientResponse = (Map<String, Object>) client.makeRequest();
Map<String, Object> result = (Map<String, Object>) ResponseComparison.compareResponse(interaction1.response(),
clientResponse, (int) clientResponse.get("statusCode"), (Map) clientResponse.get("headers"), (String) clientResponse.get("data"));
//assert all good
assertThat(result.get("method"), is(true)); // method type matches
Map headers = (Map) result.get("headers"); //headers match
headers.forEach( (k, v) ->
assertThat(format("Header: [%s] does not match", k), v, org.hamcrest.Matchers.equalTo(true))
);
assertThat((Collection<Object>)((Map)result.get("body")).values(), org.hamcrest.Matchers.hasSize(0)); // empty list of body mismatches
}
}
```
### An example of running provider verification with spock
This example uses groovy and spock to run the provider verification.
Again the provider service is a DropWizard application, and is using the DropwizardAppRule to startup the service.
This example runs all interactions using spocks Unroll feature
```groovy
class PactJVMProviderSpockSpec extends Specification {
@ClassRule @Shared
TestRule startServiceRule = new DropwizardAppRule<DropwizardAppConfig>(DropwizardApp.class, "config.yml");
@Shared
ProviderInfo serviceProvider
@Shared
Pact testConsumerPact
def setupSpec() {
serviceProvider = new ProviderInfo("Dropwizard App")
serviceProvider.protocol = "http"
serviceProvider.host = "localhost"
serviceProvider.port = 8080;
serviceProvider.path = "/"
def consumer = serviceProvider.hasPactWith("ping_consumer", {
pactFile = new File('target/pacts/ping_client-ping_service.json')
})
testConsumerPact = (Pact) new PactReader().loadPact(consumer.getPactFile());
}
def cleanup() {
//cleanup provider state
//ie. db.truncateAllTables()
}
def cleanupSpec() {
//cleanup provider
}
@Unroll
def "Provider Pact - With Consumer"() {
given:
//setup provider state
// ie. db.setupRecords()
// serviceProvider.requestFilter = { req ->
// req.addHeader('Authorization', token)
// }
when:
ProviderClient client = new ProviderClient(provider: serviceProvider, request: interaction.request())
Map clientResponse = (Map) client.makeRequest()
Map result = (Map) ResponseComparison.compareResponse(interaction.response(),
clientResponse, clientResponse.statusCode, clientResponse.headers, clientResponse.data)
then:
// method matches
result.method == true
// headers all match, spock needs the size checked before
// asserting each result
if (result.headers.size() > 0) {
result.headers.each() { k, v ->
assert v == true
}
}
// empty list of body mismatches
result.body.size() == 0
where:
interaction << scala.collection.JavaConversions.seqAsJavaList(testConsumerPact.interactions())
}
}
```
pact-jvm-provider-specs2_2.11 from group au.com.dius (version 3.2.7)
pact-jvm-provider-specs2
========================
Provides an extension to Specs2 Specification to validate a pact file against a running provider. See
[ExampleProviderSpec.scala](pact-jvm-provider-specs2/src/test/scala/au/com/dius/pact/provider/specs2/ExampleProviderSpec.scala)
for an example.
*Note:* The Pact ProviderSpec requires spec2 3.x
0 downloads
Page 19 from 20 (items total 294)
© 2015 - 2025 Weber Informatics LLC | Privacy Policy