Download pact-jvm-consumer-junit_2.10 JAR file with all dependencies
pact-jvm-consumer-junit_2.10 from group au.com.dius (version 2.4.10)
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 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 PactFrament 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.model.PactFragment;
import java.util.HashMap;
import java.util.Map;
import static org.junit.Assert.assertEquals;
public class ExampleJavaConsumerPactTest extends ConsumerPactTest {
@Override
protected PactFragment createFragment(ConsumerPactBuilder.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("a request for something")
.path("/")
.method("GET")
.headers(headers)
.body("{\"test\":true}")
.willRespondWith()
.status(200)
.headers(headers)
.body("{\"responsetest\":true}").toFragment();
}
@Override
protected String providerName() {
return "Some Provider";
}
@Override
protected String consumerName() {
return "Some Consumer";
}
@Override
protected void runTest(String url) {
assertEquals(new ProviderClient(url).getSomething(), "{\"responsetest\":true}");
}
}
```
### 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 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")
```
## 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)
Artifact pact-jvm-consumer-junit_2.10
Group au.com.dius
Version 2.4.10
Last update 17. June 2016
Tags: need insecurehttpsrequest using maven tend supports untrusted time thanks something stringvalue pactdslwithprovider 2015 number consumerclient header project each array spec runtimeexception before debug handling pactproviderhttpstest leave providername times write left 8443 ensure classes look define integer needs introduces stringmatcher represent testrun ports starts what ioexception base library closearray testing construct configuration public methods expression body client root arraylike apache pactfragment 2fcom same consumer willrespondwith localhost unfilteredmockprovider basic description optional timestamps getspecificationversion assertequals hostname haspactwith dpact double much items override maximum rootdir against doing containing minarraylike example does matchers arrayminlike basedir response throw following name fragment testreqheadervalue precision 2fau 8080 hexvalue responsetest annotate hello message 2fdius never which take java github pacts arrays they simplifies ipaddress insecure longs given junit_2 verified empty only import groupid pact_verified central mockprovider pacterror formatted regex responses include builddir 2fsrc http verification mockproviderconfig them then recorded will yyyy bodies incoming bigger examplejavaconsumerpacttest most build followed tests listen "null" note files verificationresult void true master hexcode item method headers 2fpact apply integers cause second location sometimes testpact where type providerclient level more when request value required test_consumer returning lots appropriate extends here systempropertyvariables expressions integertype matching surefire issues gradle createdefault this util test_provider from localaddress scala artifactid smaller real paths allows pactframent path pactdsljsonarray exmaple receive constructor building extend consumerpacttest your into list generating mismatched ints know pass booleantype convenient closeobject implementation matchpath also step dius changes found 2ftest received plugin matches providers consumername receives boolean defined static mocktestprovider builder __version systemproperties warmuuh available system defines hexadecimal uuid specify examples ways fails pactproviderrule minimum states logged date running messages dslpart timestamp numbers happy written depending publish debugging https works artifact pattern string assert annotations runs slf4j publishing queue harry both provide requiring must amount values maxarraylike parameters connections 2fv3 cleareddate 2fexamplemessageconsumertest size that failure generated than case identifier result model generate catch strings well arraymaxlike json pactdsljsonbody four multiple interactions 2fjava functions regular fluent provides provider junit expecting builddirectory pacttest changing usage actual provided server certain tofragment test accept mechanism annotation certificate 1234567890 tree pactspecversion file describe config false expectations 2fconsumer information fork groovy form equals random interaction like create many start uuids language some port might plugins query self ensuring pactmultiprovidertest version dates want pactconfig just consumerpactbuilder failures arrayeachlike post mock cases signed pactdsljsonrootvalue return stored should overwritten point runtest directory broker decimaltype users transaction overridden eachlike enable used function dependency requests tools testreqheader examplejavaconsumerpactruletest returns directly work status messagepactproviderrule class logging property format booleans 1234 parsed pact default instanceof floating match getsomething examplemessageconsumertest other javaoptions have expectedresponse uponreceiving state encoded numbervalue another protected parameter equality setup rule with booleanvalue error pactverification runconsumer matchheader tasks decimal blob createfragment versions numbertype address context instead target specification hashmap started group user stringtype first clients
Organization not specified
URL https://github.com/DiUS/pact-jvm
License Apache 2
Dependencies amount 8
Dependencies scala-library, junit, pact-jvm-consumer_2.10, json, scala-compiler, guava, commons-lang3, slf4j-api,
There are maybe transitive dependencies!
Group au.com.dius
Version 2.4.10
Last update 17. June 2016
Tags: need insecurehttpsrequest using maven tend supports untrusted time thanks something stringvalue pactdslwithprovider 2015 number consumerclient header project each array spec runtimeexception before debug handling pactproviderhttpstest leave providername times write left 8443 ensure classes look define integer needs introduces stringmatcher represent testrun ports starts what ioexception base library closearray testing construct configuration public methods expression body client root arraylike apache pactfragment 2fcom same consumer willrespondwith localhost unfilteredmockprovider basic description optional timestamps getspecificationversion assertequals hostname haspactwith dpact double much items override maximum rootdir against doing containing minarraylike example does matchers arrayminlike basedir response throw following name fragment testreqheadervalue precision 2fau 8080 hexvalue responsetest annotate hello message 2fdius never which take java github pacts arrays they simplifies ipaddress insecure longs given junit_2 verified empty only import groupid pact_verified central mockprovider pacterror formatted regex responses include builddir 2fsrc http verification mockproviderconfig them then recorded will yyyy bodies incoming bigger examplejavaconsumerpacttest most build followed tests listen "null" note files verificationresult void true master hexcode item method headers 2fpact apply integers cause second location sometimes testpact where type providerclient level more when request value required test_consumer returning lots appropriate extends here systempropertyvariables expressions integertype matching surefire issues gradle createdefault this util test_provider from localaddress scala artifactid smaller real paths allows pactframent path pactdsljsonarray exmaple receive constructor building extend consumerpacttest your into list generating mismatched ints know pass booleantype convenient closeobject implementation matchpath also step dius changes found 2ftest received plugin matches providers consumername receives boolean defined static mocktestprovider builder __version systemproperties warmuuh available system defines hexadecimal uuid specify examples ways fails pactproviderrule minimum states logged date running messages dslpart timestamp numbers happy written depending publish debugging https works artifact pattern string assert annotations runs slf4j publishing queue harry both provide requiring must amount values maxarraylike parameters connections 2fv3 cleareddate 2fexamplemessageconsumertest size that failure generated than case identifier result model generate catch strings well arraymaxlike json pactdsljsonbody four multiple interactions 2fjava functions regular fluent provides provider junit expecting builddirectory pacttest changing usage actual provided server certain tofragment test accept mechanism annotation certificate 1234567890 tree pactspecversion file describe config false expectations 2fconsumer information fork groovy form equals random interaction like create many start uuids language some port might plugins query self ensuring pactmultiprovidertest version dates want pactconfig just consumerpactbuilder failures arrayeachlike post mock cases signed pactdsljsonrootvalue return stored should overwritten point runtest directory broker decimaltype users transaction overridden eachlike enable used function dependency requests tools testreqheader examplejavaconsumerpactruletest returns directly work status messagepactproviderrule class logging property format booleans 1234 parsed pact default instanceof floating match getsomething examplemessageconsumertest other javaoptions have expectedresponse uponreceiving state encoded numbervalue another protected parameter equality setup rule with booleanvalue error pactverification runconsumer matchheader tasks decimal blob createfragment versions numbertype address context instead target specification hashmap started group user stringtype first clients
Organization not specified
URL https://github.com/DiUS/pact-jvm
License Apache 2
Dependencies amount 8
Dependencies scala-library, junit, pact-jvm-consumer_2.10, json, scala-compiler, guava, commons-lang3, slf4j-api,
There are maybe transitive dependencies!
Page 1 from 1 (items total 1)