Download JAR files tagged by example with all dependencies

pact-jvm-consumer-junit5 ======================== JUnit 5 support for Pact consumer tests ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-junit5_2.12` * version-id = `3.5.x` ## Usage ### 1. Add the Pact consumer test extension to the test class. To write Pact consumer tests with JUnit 5, you need to add `@ExtendWith(PactConsumerTestExt)` to your test class. This replaces the `PactRunner` used for JUnit 4 tests. The rest of the test follows a similar pattern as for JUnit 4 tests. ```java @ExtendWith(PactConsumerTestExt.class) class ExampleJavaConsumerPactTest { ``` ### 2. create a method annotated with `@Pact` that returns the interactions for the test For each test (as with JUnit 4), you need to define a method annotated with the `@Pact` annotation that returns the interactions for the test. ```java @Pact(provider="test_provider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` ### 3. Link the mock server with the interactions for the test with `@PactTestFor` Then the final step is to use the `@PactTestFor` annotation to tell the Pact extension how to setup the Pact test. You can either put this annotation on the test class, or on the test method. For examples see [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) and [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy). The `@PactTestFor` annotation allows you to control the mock server in the same way as the JUnit 4 `PactProviderRule`. It allows you to set the hostname to bind to (default is `localhost`) and the port (default is to use a random port). You can also set the Pact specification version to use (default is V3). ```java @ExtendWith(PactConsumerTestExt.class) @PactTestFor(providerName = "ArticlesProvider", port = "1234") public class ExampleJavaConsumerPactTest { ``` **NOTE on the hostname**: The mock server runs in the same JVM as the test, so the only valid values for hostname are: | hostname | result | | -------- | ------ | | `localhost` | binds to the address that localhost points to (normally the loopback adapter) | | `127.0.0.1` or `::1` | binds to the loopback adapter | | host name | binds to the default interface that the host machines DNS name resolves to | | `0.0.0.0` or `::` | binds to the all interfaces on the host machine | #### Matching the interactions by provider name If you set the `providerName` on the `@PactTestFor` annotation, then the first method with a `@Pact` annotation with the same provider name will be used. See [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) for an example. #### Matching the interactions by method name If you set the `pactMethod` on the `@PactTestFor` annotation, then the method with the provided name will be used (it still needs a `@Pact` annotation). See [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy) for an example. ### Injecting the mock server into the test You can get the mock server injected into the test method by adding a `MockServer` parameter to the test method. ```java @Test void test(MockServer mockServer) { HttpResponse httpResponse = Request.Get(mockServer.getUrl() + "/articles.json").execute().returnResponse(); assertThat(httpResponse.getStatusLine().getStatusCode(), is(equalTo(200))); } ``` This helps with getting the base URL of the mock server, especially when a random port is used. ## Unsupported The current implementation does not support tests with multiple providers. This will be added in a later release.

# pact-jvm-consumer-java8 Provides a Java8 lambda based DSL for use with Junit to build consumer tests. # A Lambda DSL for Pact This is an extension for the pact DSL provided by [pact-jvm-consumer](../pact-jvm-consumer). The difference between the default pact DSL and this lambda DSL is, as the name suggests, the usage of lambdas. The use of lambdas makes the code much cleaner. ## Why a new DSL implementation? The lambda DSL solves the following two main issues. Both are visible in the following code sample: ```java new PactDslJsonArray() .array() # open an array .stringValue("a1") # choose the method that is valid for arrays .stringValue("a2") # choose the method that is valid for arrays .closeArray() # close the array .array() # open an array .numberValue(1) # choose the method that is valid for arrays .numberValue(2) # choose the method that is valid for arrays .closeArray() # close the array .array() # open an array .object() # now we work with an object .stringValue("foo", "Foo") # choose the method that is valid for objects .closeObject() # close the object and we're back in the array .closeArray() # close the array ``` ### The existing DSL is quite error-prone Methods may only be called in certain states. For example `object()` may only be called when you're currently working on an array whereas `object(name)` is only allowed to be called when working on an object. But both of the methods are available. You'll find out at runtime if you're using the correct method. Finally, the need for opening and closing objects and arrays makes usage cumbersome. The lambda DSL has no ambiguous methods and there's no need to close objects and arrays as all the work on such an object is wrapped in a lamda call. ### The existing DSL is hard to read When formatting your source code with an IDE the code becomes hard to read as there's no indentation possible. Of course, you could do it by hand but we want auto formatting! Auto formatting works great for the new DSL! ```java array.object((o) -> { o.stringValue("foo", "Foo"); # an attribute o.stringValue("bar", "Bar"); # an attribute o.object("tar", (tarObject) -> { # an attribute with a nested object tarObject.stringValue("a", "A"); # attribute of the nested object tarObject.stringValue("b", "B"); # attribute of the nested object }) }); ``` ## Installation ### Maven ``` <dependency> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-consumer-java8_2.12</artifactId> <version>${pact.version}</version> </dependency> ``` ## Usage Start with a static import of `LambdaDsl`. This class contains factory methods for the lambda dsl extension. When you come accross the `body()` method of `PactDslWithProvider` builder start using the new extensions. The call to `LambdaDsl` replaces the call to instance `new PactDslJsonArray()` and `new PactDslJsonBody()` of the pact library. ```java io.pactfoundation.consumer.dsl.LambdaDsl.* ``` ### Response body as json array ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonArray; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonArray((a) -> { a.stringValue("a1"); a.stringValue("a2"); }).build()); ``` ### Response body as json object ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonBody; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build()); ``` ### Examples #### Simple Json object When creating simple json structures the difference between the two approaches isn't big. ##### JSON ```json { "bar": "Bar", "foo": "Foo" } ``` ##### Pact DSL ```java new PactDslJsonBody() .stringValue("foo", "Foo") .stringValue("bar", "Bar") ``` ##### Lambda DSL ```java newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build() ``` #### An array of arrays When we come to more complex constructs with arrays and nested objects the beauty of lambdas become visible! ##### JSON ```json [ ["a1", "a2"], [1, 2], [{"foo": "Foo"}] ] ``` ##### Pact DSL ```java new PactDslJsonArray() .array() .stringValue("a1") .stringValue("a2") .closeArray() .array() .numberValue(1) .numberValue(2) .closeArray() .array() .object() .stringValue("foo", "Foo") .closeObject() .closeArray() ``` ##### Lambda DSL ```java newJsonArray((rootArray) -> { rootArray.array((a) -> a.stringValue("a1").stringValue("a2")); rootArray.array((a) -> a.numberValue(1).numberValue(2)); rootArray.array((a) -> a.object((o) -> o.stringValue("foo", "Foo")); }).build() ```

This module contains a more general approach to construct AlignmentAlgorithms by relying on the theoretical concept of Algebraic Dynamic Programming (ADP) as developed by Giegerich et al. ADP defines four ingredients for an alignment algorithm: 1.) A signature that defines the permitted alignment operations. Operations are just function templates with an associated arity, meaning the number of arguments it takes from the left sequence and from the right sequence. In the TCSAlignmentToolbox we have a fixed signature with the following operations: REPLACEMENT(1, 1), DELETION(1, 0), INSERTION(0, 1), SKIPDELETION(1, 0) and SKIPINSERTION(0, 1) 2.) A regular tree grammar that produces alignments, that is: sequences of operations, in a restricted fashion. 3.) An algebra that can translate such trees to a cost. In the TCSAlignmentToolbox this is a Comparator. 4.) A choice function, in case of the TCSAlignmentToolbox: the strict minimum or the soft minimum. An alignment algorithm in the TCSAlignmentToolbox sense of the word then is the combination of choice function and grammar. While we provide hardcoded versions of these combinations in the main package, the adp package allows you to create your own grammars. You can combine them with a choice function by instantiating one of the Algorithm classes provided in this package with a grammar of your choice. For example: AlignmentAlgorithm algo = new SoftADPScoreAlgorithm(my_grammar, comparator); creates an alignment algorithm that implicitly produces all possible alignments your grammar can construct with the given input, translates them to a cost using the algebra/comparator you provided and applies the soft minimum to return the score. This all gets efficient by dynamic programming. Note that there is runtime overhead when using this method in comparison with the hardcoded algorithms. But for complicated grammars this is a much easier way to go. For more information on the theory, please refer to my master's thesis: "Adaptive Affine Sequence Alignment using Algebraic Dynamic Programming"

pact-jvm-consumer-groovy-v3 =========================== Groovy DSL for Pact JVM implementing V3 specification changes. ##Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-groovy-v3_2.11` * version-id = `2.2.x` or `3.0.x` ##Usage Add the `pact-jvm-consumer-groovy-v3` library to your test class path. This provides a `PactMessageBuilder` class for you to use to define your pacts. If you are using gradle for your build, add it to your `build.gradle`: dependencies { testCompile 'au.com.dius:pact-jvm-consumer-groovy-v3_2.11:2.2.12' } ## Consumer test for a message consumer The `PactMessageBuilder` class provides a DSL for defining your message expectations. It works in much the same way as the `PactBuilder` class for Request-Response interactions. ### Step 1 - define the message expectations Create a test that uses the `PactMessageBuilder` to define a message expectation, and then call `run`. This will invoke the given closure with a message for each one defined in the pact. ```groovy def eventStream = new PactMessageBuilder().call { serviceConsumer 'messageConsumer' hasPactWith 'messageProducer' given 'order with id 10000004 exists' expectsToReceive 'an order confirmation message' withMetaData(type: 'OrderConfirmed') // Can define any key-value pairs here withContent(contentType: 'application/json') { type 'OrderConfirmed' audit { userCode 'messageService' } origin 'message-service' referenceId '10000004-2' timeSent: '2015-07-22T10:14:28+00:00' value { orderId '10000004' value '10.000000' fee '10.00' gst '15.00' } } } ``` ### Step 2 - call your message handler with the generated messages This example tests a message handler that gets messages from a Kafka topic. In this case the Pact message is wrapped as a Kafka `MessageAndMetadata`. ```groovy eventStream.run { Message message -> messageHandler.handleMessage(new MessageAndMetadata('topic', 1, new kafka.message.Message(message.contentsAsBytes()), 0, null, valueDecoder)) } ``` ### Step 3 - validate that the message was handled correctly ```groovy def order = orderRepository.getOrder('10000004') assert order.status == 'confirmed' assert order.value == 10.0 ``` ### Step 4 - Publish the pact file If the test was successful, a pact file would have been produced with the message from step 1.

pact-jvm-consumer-groovy-v3 =========================== Groovy DSL for Pact JVM implementing V3 specification changes. ##Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-groovy-v3_2.11` * version-id = `2.2.x` or `3.0.x` ##Usage Add the `pact-jvm-consumer-groovy-v3` library to your test class path. This provides a `PactMessageBuilder` class for you to use to define your pacts. If you are using gradle for your build, add it to your `build.gradle`: dependencies { testCompile 'au.com.dius:pact-jvm-consumer-groovy-v3_2.11:2.2.12' } ## Consumer test for a message consumer The `PactMessageBuilder` class provides a DSL for defining your message expectations. It works in much the same way as the `PactBuilder` class for Request-Response interactions. ### Step 1 - define the message expectations Create a test that uses the `PactMessageBuilder` to define a message expectation, and then call `run`. This will invoke the given closure with a message for each one defined in the pact. ```groovy def eventStream = new PactMessageBuilder().call { serviceConsumer 'messageConsumer' hasPactWith 'messageProducer' given 'order with id 10000004 exists' expectsToReceive 'an order confirmation message' withMetaData(type: 'OrderConfirmed') // Can define any key-value pairs here withContent(contentType: 'application/json') { type 'OrderConfirmed' audit { userCode 'messageService' } origin 'message-service' referenceId '10000004-2' timeSent: '2015-07-22T10:14:28+00:00' value { orderId '10000004' value '10.000000' fee '10.00' gst '15.00' } } } ``` ### Step 2 - call your message handler with the generated messages This example tests a message handler that gets messages from a Kafka topic. In this case the Pact message is wrapped as a Kafka `MessageAndMetadata`. ```groovy eventStream.run { Message message -> messageHandler.handleMessage(new MessageAndMetadata('topic', 1, new kafka.message.Message(message.contentsAsBytes()), 0, null, valueDecoder)) } ``` ### Step 3 - validate that the message was handled correctly ```groovy def order = orderRepository.getOrder('10000004') assert order.status == 'confirmed' assert order.value == 10.0 ``` ### Step 4 - Publish the pact file If the test was successful, a pact file would have been produced with the message from step 1.

minitest provides a complete suite of testing facilities supporting TDD, BDD, mocking, and benchmarking. "I had a class with Jim Weirich on testing last week and we were allowed to choose our testing frameworks. Kirk Haines and I were paired up and we cracked open the code for a few test frameworks... I MUST say that minitest is *very* readable / understandable compared to the 'other two' options we looked at. Nicely done and thank you for helping us keep our mental sanity." -- Wayne E. Seguin minitest/unit is a small and incredibly fast unit testing framework. It provides a rich set of assertions to make your tests clean and readable. minitest/spec is a functionally complete spec engine. It hooks onto minitest/unit and seamlessly bridges test assertions over to spec expectations. minitest/benchmark is an awesome way to assert the performance of your algorithms in a repeatable manner. Now you can assert that your newb co-worker doesn't replace your linear algorithm with an exponential one! minitest/mock by Steven Baker, is a beautifully tiny mock (and stub) object framework. minitest/pride shows pride in testing and adds coloring to your test output. I guess it is an example of how to write IO pipes too. :P minitest/unit is meant to have a clean implementation for language implementors that need a minimal set of methods to bootstrap a working test suite. For example, there is no magic involved for test-case discovery. "Again, I can't praise enough the idea of a testing/specing framework that I can actually read in full in one sitting!" -- Piotr Szotkowski Comparing to rspec: rspec is a testing DSL. minitest is ruby. -- Adam Hawkins, "Bow Before MiniTest" minitest doesn't reinvent anything that ruby already provides, like: classes, modules, inheritance, methods. This means you only have to learn ruby to use minitest and all of your regular OO practices like extract-method refactorings still apply.

# pact-jvm-consumer-java8 Provides a Java8 lambda based DSL for use with Junit to build consumer tests. ## Dependency The library is available on maven central using: * group-id = `au.com.dius.pact.consumer` * artifact-id = `java8` * version-id = `4.1.x` # A Lambda DSL for Pact This is an extension for the pact DSL provided by [consumer](../consumer). The difference between the default pact DSL and this lambda DSL is, as the name suggests, the usage of lambdas. The use of lambdas makes the code much cleaner. ## Why a new DSL implementation? The lambda DSL solves the following two main issues. Both are visible in the following code sample: ```java new PactDslJsonArray() .array() # open an array .stringValue("a1") # choose the method that is valid for arrays .stringValue("a2") # choose the method that is valid for arrays .closeArray() # close the array .array() # open an array .numberValue(1) # choose the method that is valid for arrays .numberValue(2) # choose the method that is valid for arrays .closeArray() # close the array .array() # open an array .object() # now we work with an object .stringValue("foo", "Foo") # choose the method that is valid for objects .closeObject() # close the object and we're back in the array .closeArray() # close the array ``` ### The existing DSL is quite error-prone Methods may only be called in certain states. For example `object()` may only be called when you're currently working on an array whereas `object(name)` is only allowed to be called when working on an object. But both of the methods are available. You'll find out at runtime if you're using the correct method. Finally, the need for opening and closing objects and arrays makes usage cumbersome. The lambda DSL has no ambiguous methods and there's no need to close objects and arrays as all the work on such an object is wrapped in a lamda call. ### The existing DSL is hard to read When formatting your source code with an IDE the code becomes hard to read as there's no indentation possible. Of course, you could do it by hand but we want auto formatting! Auto formatting works great for the new DSL! ```java array.object((o) -> { o.stringValue("foo", "Foo"); # an attribute o.stringValue("bar", "Bar"); # an attribute o.object("tar", (tarObject) -> { # an attribute with a nested object tarObject.stringValue("a", "A"); # attribute of the nested object tarObject.stringValue("b", "B"); # attribute of the nested object }) }); ``` ## Installation ### Maven ``` <dependency> <groupId>au.com.dius.pact.consumer</groupId> <artifactId>java8</artifactId> <version>${pact.version}</version> </dependency> ``` ## Usage Start with a static import of `LambdaDsl`. This class contains factory methods for the lambda dsl extension. When you come accross the `body()` method of `PactDslWithProvider` builder start using the new extensions. The call to `LambdaDsl` replaces the call to instance `new PactDslJsonArray()` and `new PactDslJsonBody()` of the pact library. ```java io.pactfoundation.consumer.dsl.LambdaDsl.* ``` ### Response body as json array ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonArray; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonArray((a) -> { a.stringValue("a1"); a.stringValue("a2"); }).build()); ``` ### Response body as json object ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonBody; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build()); ``` ### Examples #### Simple Json object When creating simple json structures the difference between the two approaches isn't big. ##### JSON ```json { "bar": "Bar", "foo": "Foo" } ``` ##### Pact DSL ```java new PactDslJsonBody() .stringValue("foo", "Foo") .stringValue("bar", "Bar") ``` ##### Lambda DSL ```java newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build(); ``` #### An array of arrays When we come to more complex constructs with arrays and nested objects the beauty of lambdas become visible! ##### JSON ```json [ ["a1", "a2"], [1, 2], [{"foo": "Foo"}] ] ``` ##### Pact DSL ```java new PactDslJsonArray() .array() .stringValue("a1") .stringValue("a2") .closeArray() .array() .numberValue(1) .numberValue(2) .closeArray() .array() .object() .stringValue("foo", "Foo") .closeObject() .closeArray(); ``` ##### Lambda DSL ```java newJsonArray((rootArray) -> { rootArray.array((a) -> a.stringValue("a1").stringValue("a2")); rootArray.array((a) -> a.numberValue(1).numberValue(2)); rootArray.array((a) -> a.object((o) -> o.stringValue("foo", "Foo"))); }).build(); ``` ##### Kotlin Lambda DSL ```kotlin newJsonArray { newArray { stringValue("a1") stringValue("a2") } newArray { numberValue(1) numberValue(2) } newArray { newObject { stringValue("foo", "Foo") } } } ``` # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

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 -v <value> | --pact-version <value> pact version to generate for (2 or 3) -k <value> | --keystore-path <value> Path to keystore -p <value> | --keystore-password <value> Keystore password -s <value> | --ssl-port <value> Ssl port the mock server should run on. lower and upper bounds are ignored --debug run with debug logging ``` ### Using trust store 3.4.0+ Trust store can be used. However, it is limited to a single port for the time being. ### 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-3.2.11.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 and a path. For example: POST http://localhost:29999/create?state=NoUsers&path=/sub/ref/path '{ "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 } But you can also reference the path from `/sub/ref/path` using the server port. The service will not strip the prefix path, but instead will use it as a differentiator. If your services do not have differences in the prefix of their path, then you will have to use the port method. ### /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 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. ### 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 Groovy, JUnit 4 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) ```groovy class ReadmeExamplePactJVMProviderJUnitTest { @ClassRule public static TestRule startServiceRule = new DropwizardAppRule<DropwizardConfiguration>( TestDropwizardApplication.class, ResourceHelpers.resourceFilePath("dropwizard/test-config.yaml")) private static ProviderInfo serviceProvider private static Pact<RequestResponseInteraction> testConsumerPact private static ConsumerInfo consumer @BeforeClass static void setupProvider() { serviceProvider = new ProviderInfo("Dropwizard App") serviceProvider.setProtocol("http") serviceProvider.setHost("localhost") serviceProvider.setPort(8080) serviceProvider.setPath("/") consumer = new ConsumerInfo() consumer.setName("test_consumer") consumer.setPactSource(new UrlSource( ReadmeExamplePactJVMProviderJUnitTest.getResource("/pacts/zoo_app-animal_service.json").toString())) testConsumerPact = PactReader.loadPact(consumer.getPactSource()) as Pact<RequestResponseInteraction> } @Test void runConsumerPacts() { // grab the first interaction from the pact with consumer Interaction interaction = testConsumerPact.interactions.get(0) // setup the verifier ProviderVerifier verifier = setupVerifier(interaction, serviceProvider, consumer) // setup any provider state // setup the client and interaction to fire against the provider ProviderClient client = new ProviderClient(serviceProvider, new HttpClientFactory()) Map<String, Object> failures = new HashMap<>() verifier.verifyResponseFromProvider(serviceProvider, interaction, interaction.getDescription(), failures, client) if (!failures.isEmpty()) { verifier.displayFailures(failures) } // Assert all good assertThat(failures, is(empty())) } private ProviderVerifier setupVerifier(Interaction interaction, ProviderInfo provider, ConsumerInfo consumer) { ProviderVerifier verifier = new ProviderVerifier() verifier.initialiseReporters(provider) verifier.reportVerificationForConsumer(consumer, provider) if (!interaction.getProviderStates().isEmpty()) { for (ProviderState providerState: interaction.getProviderStates()) { verifier.reportStateForInteraction(providerState.getName(), provider, consumer, true) } } verifier.reportInteractionDescription(interaction) return verifier } } ``` ### 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 ReadmeExamplePactJVMProviderSpockSpec extends Specification { @ClassRule @Shared TestRule startServiceRule = new DropwizardAppRule<DropwizardConfiguration>(TestDropwizardApplication, ResourceHelpers.resourceFilePath('dropwizard/test-config.yaml')) @Shared ProviderInfo serviceProvider ProviderVerifier verifier def setupSpec() { serviceProvider = new ProviderInfo('Dropwizard App') serviceProvider.protocol = 'http' serviceProvider.host = 'localhost' serviceProvider.port = 8080 serviceProvider.path = '/' serviceProvider.hasPactWith('zoo_app') { pactSource = new FileSource(new File(ResourceHelpers.resourceFilePath('pacts/zoo_app-animal_service.json'))) } } def setup() { verifier = new ProviderVerifier() } def cleanup() { // cleanup provider state // ie. db.truncateAllTables() } def cleanupSpec() { // cleanup provider } @Unroll def "Provider Pact - With Consumer #consumer"() { expect: verifyConsumerPact(consumer).empty where: consumer << serviceProvider.consumers } private Map verifyConsumerPact(ConsumerInfo consumer) { Map failures = [:] verifier.initialiseReporters(serviceProvider) verifier.runVerificationForConsumer(failures, serviceProvider, consumer) if (!failures.empty) { verifier.displayFailures(failures) } failures } } ```

# Pact Spring/JUnit runner ## Overview Library provides ability to play contract tests against a provider using Spring & JUnit. This library is based on and references the JUnit package, so see the [Pact JUnit 4](../pact-jvm-provider-junit) or [Pact JUnit 5](../pact-jvm-provider-junit5) providers for more details regarding configuration using JUnit. Supports: - Standard ways to load pacts from folders and broker - Easy way to change assertion strategy - Spring Test MockMVC Controllers and ControllerAdvice using MockMvc standalone setup. - MockMvc debugger output - Multiple @State runs to test a particular Provider State multiple times - **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. **NOTE:** For publishing provider verification results to a pact broker, make sure the Java system property `pact.provider.version` is set with the version of your provider. ## Example of MockMvc test ```java @RunWith(RestPactRunner.class) // Custom pact runner, child of PactRunner which runs only REST tests @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 { //Create an instance of your controller. We cannot autowire this as we're not using (and don't want to use) a Spring test runner. @InjectMocks private AwesomeController awesomeController = new AwesomeController(); //Mock your service logic class. We'll use this to create scenarios for respective provider states. @Mock private AwesomeBusinessLogic awesomeBusinessLogic; //Create an instance of your controller advice (if you have one). This will be passed to the MockMvcTarget constructor to be wired up with MockMvc. @InjectMocks private AwesomeControllerAdvice awesomeControllerAdvice = new AwesomeControllerAdvice(); //Create a new instance of the MockMvcTarget and annotate it as the TestTarget for PactRunner @TestTarget public final MockMvcTarget target = new MockMvcTarget(); @Before //Method will be run before each test of interaction public void before() { //initialize your mocks using your mocking framework MockitoAnnotations.initMocks(this); //configure the MockMvcTarget with your controller and controller advice target.setControllers(awesomeController); target.setControllerAdvice(awesomeControllerAdvice); } @State("default", "no-data") // Method will be run before testing interactions that require "default" or "no-data" state public void toDefaultState() { target.setRunTimes(3); //let's loop through this state a few times for a 3 data variants when(awesomeBusinessLogic.getById(any(UUID.class))) .thenReturn(myTestHelper.generateRandomReturnData(UUID.randomUUID(), ExampleEnum.ONE)) .thenReturn(myTestHelper.generateRandomReturnData(UUID.randomUUID(), ExampleEnum.TWO)) .thenReturn(myTestHelper.generateRandomReturnData(UUID.randomUUID(), ExampleEnum.THREE)); } @State("error-case") public void SingleUploadExistsState_Success() { target.setRunTimes(1); //tell the runner to only loop one time for this state //you might want to throw exceptions to be picked off by your controller advice when(awesomeBusinessLogic.getById(any(UUID.class))) .then(i -> { throw new NotCoolException(i.getArgumentAt(0, UUID.class).toString()); }); } } ``` ## Using a Spring runner (version 3.5.7+) You can use `SpringRestPactRunner` instead of the default Pact runner to use the Spring test annotations. This will allow you to inject or mock spring beans. For example: ```java @RunWith(SpringRestPactRunner.class) @Provider("pricing") @PactBroker(protocol = "https", host = "${pactBrokerHost}", port = "443", authentication = @PactBrokerAuth(username = "${pactBrokerUser}", password = "${pactBrokerPassword}")) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT) public class PricingServiceProviderPactTest { @MockBean private ProductClient productClient; // This will replace the bean with a mock in the application context @TestTarget @SuppressWarnings(value = "VisibilityModifier") public final Target target = new HttpTarget(8091); @State("Product X010000021 exists") public void setupProductX010000021() throws IOException { reset(productClient); ProductBuilder product = new ProductBuilder() .withProductCode("X010000021"); when(productClient.fetch((Set<String>) argThat(contains("X010000021")), any())).thenReturn(product); } @State("the product code X00001 can be priced") public void theProductCodeX00001CanBePriced() throws IOException { reset(productClient); ProductBuilder product = new ProductBuilder() .withProductCode("X00001"); when(productClient.find((Set<String>) argThat(contains("X00001")), any())).thenReturn(product); } } ``` ### Using Spring Context Properties (version 3.5.14+) From version 3.5.14 onwards, the SpringRestPactRunner will look up any annotation expressions (like `${pactBrokerHost}`) above) from the Spring context. For Springboot, this will allow you to define the properties in the application test properties. For instance, if you create the following `application.yml` in the test resources: ```yaml pactbroker: host: "your.broker.local" port: "443" protocol: "https" auth: username: "<your broker username>" password: "<your broker password>" ``` Then you can use the defaults on the `@PactBroker` annotation. ```java @RunWith(SpringRestPactRunner.class) @Provider("My Service") @PactBroker( authentication = @PactBrokerAuth(username = "${pactbroker.auth.username}", password = "${pactbroker.auth.password}") ) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) public class PactVerificationTest { ``` ### Using a random port with a Springboot test (version 3.5.14+) If you use a random port in a springboot test (by setting `SpringBootTest.WebEnvironment.RANDOM_PORT`), you can use the `SpringBootHttpTarget` which will get the application port from the spring application context. For example: ```java @RunWith(SpringRestPactRunner.class) @Provider("My Service") @PactBroker @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) public class PactVerificationTest { @TestTarget public final Target target = new SpringBootHttpTarget(); } ```