[...] org.apache.maven.plugins maven-surefire-plugin 2.18 some/other/directory ${project.build.directory} [...] [...] ``` 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." > mvncenter: au.com.dius:pact-jvm-consumer-junit_2.10:2.2.11
p

pact-jvm-consumer-junit_2.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 = `2.2.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 headers = new HashMap(); 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(); } ``` #### 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); } ``` For an example, have a look at [ExampleJavaConsumerPactRuleTest](src/test/java/au/com/dius/pact/consumer/examples/ExampleJavaConsumerPactRuleTest.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.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 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(); ``` #### 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. #### 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") .realType("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 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 [...] org.apache.maven.plugins maven-surefire-plugin 2.18 some/other/directory ${project.build.directory} [...] [...] ``` 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.
https://github.com/DiUS/pact-jvm
Apache 2
Travis Dixon Ronald Holshausen Ken Scambler
using maven tend received plugin matches time thanks consumername receives something static pactdslwithprovider 2015 builder number warmuuh available systemproperties consumerclient header project system defines each examples array spec runtimeexception minimum pactproviderrule before states debug logged date running dslpart timestamp leave providername happy written write left publish debugging ensure look https classes define needs represent testrun artifact starts pattern what ioexception string library base assert testing closearray construct runs slf4j public configuration publishing methods expression body harry provide root arraylike pactfragment apache consumer willrespondwith localhost must amount unfilteredmockprovider maxarraylike description optional assertequals cleareddate haspactwith hostname dpact size that items generated maximum override rootdir against than containing minarraylike example case identifier does result model generate arrayminlike matchers catch basedir well arraymaxlike response throw following json pactdsljsonbody name four testreqheadervalue fragment interactions functions regular provides provider 8080 junit hexvalue responsetest annotate builddirectory hello never which pacttest changing provided actual usage java server certain pacts github arrays tofragment simplifies test accept mechanism ipaddress 1234567890 tree given junit_2 verified describe empty expectations only config import groupid central pact_verified mockprovider pacterror fork groovy regex random interaction like create responses many builddir start http verification them mockproviderconfig then will recorded yyyy bodies some port might realtype incoming examplejavaconsumerpacttest bigger plugins most build ensuring followed version tests listen note want consumerpactbuilder just failures files arrayeachlike post mock return verificationresult true void should overwritten master runtest hexcode directory item method broker headers users second sometimes overridden transaction location eachlike testpact enable type used function dependency requests providerclient tools level testreqheader request when value examplejavaconsumerpactruletest returns required directly test_consumer appropriate lots extends status class here logging property systempropertyvariables expressions 1234 default pact matching surefire instanceof gradle createdefault match getsomething this util other javaoptions expectedresponse have test_provider state uponreceiving from localaddress numbervalue scala smaller artifactid another real parameter protected paths allows pactframent rule setup path pactdsljsonarray building with error extend consumerpacttest pactverification your runconsumer matchheader list generating tasks mismatched know booleantype createfragment convenient closeobject context target hashmap group matchpath stringtype user step dius
Files download
File Operation
pact-jvm-consumer-junit_2.10-2.2.11.jar download
pact-jvm-consumer-junit_2.10-2.2.11.pom download
pact-jvm-consumer-junit_2.10-2.2.11-sources.jar download
Apache Maven 
<dependency>
  <groupId>au.com.dius</groupId>
  <artifactId>pact-jvm-consumer-junit_2.10</artifactId>
  <version>2.2.11</version>
</dependency>
Gradle Groovy 
implementation 'au.com.dius:pact-jvm-consumer-junit_2.10:2.2.11'
Gradle Kotlin 
implementation("au.com.dius:pact-jvm-consumer-junit_2.10:2.2.11")
Scala SBT 
libraryDependencies += "au.com.dius" % "pact-jvm-consumer-junit_2.10" % "2.2.11"
Groovy Grape 
@Grapes(
  @Grab(group='au.com.dius', module='pact-jvm-consumer-junit_2.10', version='2.2.11')
)
Apache Ivy 
<dependency org="au.com.dius" name="pact-jvm-consumer-junit_2.10" rev="2.2.11" />
Leiningen 
[au.com.dius/pact-jvm-consumer-junit_2.10 "2.2.11"]
Apache Buildr 
'au.com.dius:pact-jvm-consumer-junit_2.10:jar:2.2.11'
Dependencies

compile

|-- junit:junit:4.12

|-- org.scala-lang:scala-library:2.10.5

|-- org.json:json:20140107

|-- au.com.dius:pact-jvm-consumer_2.10:2.2.11

|-- org.json4s:json4s-native_2.10:3.2.11

|-- org.apache.commons:commons-lang3:3.3.2

|-- org.slf4j:slf4j-api:1.7.7

|-- org.json4s:json4s-jackson_2.10:3.2.11

test

|-- com.google.code.gson:gson:2.3.1

|-- org.specs2:specs2_2.10:2.3.13

|-- org.hamcrest:hamcrest-all:1.3

|-- org.apache.commons:commons-collections4:4.0

|-- org.apache.httpcomponents:fluent-hc:4.4

|-- ch.qos.logback:logback-core:1.1.2

|-- org.mockito:mockito-core:1.9.5

|-- ch.qos.logback:logback-classic:1.1.2