Download JAR files tagged by runs with all dependencies

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

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 Spring/JUnit runner ## Overview Library provides ability to play contract tests against a provider using Spring &amp; JUnit. This library is based on and references the JUnit package, so see [junit provider support](pact-jvm-provider-junit) 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(&quot;myAwesomeService&quot;) // Set up name of tested provider @PactFolder(&quot;pacts&quot;) // 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&apos;re not using (and don&apos;t want to use) a Spring test runner. @InjectMocks private AwesomeController awesomeController = new AwesomeController(); //Mock your service logic class. We&apos;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(&quot;default&quot;, &quot;no-data&quot;) // Method will be run before testing interactions that require &quot;default&quot; or &quot;no-data&quot; state public void toDefaultState() { target.setRunTimes(3); //let&apos;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(&quot;error-case&quot;) 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 -&gt; { 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(&quot;pricing&quot;) @PactBroker(protocol = &quot;https&quot;, host = &quot;${pactBrokerHost}&quot;, port = &quot;443&quot;, authentication = @PactBrokerAuth(username = &quot;${pactBrokerUser}&quot;, password = &quot;${pactBrokerPassword}&quot;)) @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 = &quot;VisibilityModifier&quot;) public final Target target = new HttpTarget(8091); @State(&quot;Product X010000021 exists&quot;) public void setupProductX010000021() throws IOException { reset(productClient); ProductBuilder product = new ProductBuilder() .withProductCode(&quot;X010000021&quot;); when(productClient.fetch((Set&lt;String&gt;) argThat(contains(&quot;X010000021&quot;)), any())).thenReturn(product); } @State(&quot;the product code X00001 can be priced&quot;) public void theProductCodeX00001CanBePriced() throws IOException { reset(productClient); ProductBuilder product = new ProductBuilder() .withProductCode(&quot;X00001&quot;); when(productClient.find((Set&lt;String&gt;) argThat(contains(&quot;X00001&quot;)), 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: &quot;your.broker.local&quot; port: &quot;443&quot; protocol: &quot;https&quot; auth: username: &quot;&lt;your broker username&gt;&quot; password: &quot;&lt;your broker password&gt;&quot; ``` Then you can use the defaults on the `@PactBroker` annotation. ```java @RunWith(SpringRestPactRunner.class) @Provider(&quot;My Service&quot;) @PactBroker( authentication = @PactBrokerAuth(username = &quot;${pactbroker.auth.username}&quot;, password = &quot;${pactbroker.auth.password}&quot;) ) @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(&quot;My Service&quot;) @PactBroker @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) public class PactVerificationTest { @TestTarget public final Target target = new SpringBootHttpTarget(); } ```

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 Spring/JUnit runner ## Overview Library provides ability to play contract tests against a provider using Spring &amp; 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(&quot;myAwesomeService&quot;) // Set up name of tested provider @PactFolder(&quot;pacts&quot;) // 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&apos;re not using (and don&apos;t want to use) a Spring test runner. @InjectMocks private AwesomeController awesomeController = new AwesomeController(); //Mock your service logic class. We&apos;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(&quot;default&quot;, &quot;no-data&quot;) // Method will be run before testing interactions that require &quot;default&quot; or &quot;no-data&quot; state public void toDefaultState() { target.setRunTimes(3); //let&apos;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(&quot;error-case&quot;) 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 -&gt; { throw new NotCoolException(i.getArgumentAt(0, UUID.class).toString()); }); } } ``` ## Using Spring runners You can use `SpringRestPactRunner` or `SpringMessagePactRunner` instead of the default Pact runner to use the Spring test annotations. This will allow you to inject or mock spring beans. `SpringRestPactRunner` is for restful webapps and `SpringMessagePactRunner` is for async message tests. For example: ```java @RunWith(SpringRestPactRunner.class) @Provider(&quot;pricing&quot;) @PactBroker(protocol = &quot;https&quot;, host = &quot;${pactBrokerHost}&quot;, port = &quot;443&quot;, authentication = @PactBrokerAuth(username = &quot;${pactBrokerUser}&quot;, password = &quot;${pactBrokerPassword}&quot;)) @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 = &quot;VisibilityModifier&quot;) public final Target target = new HttpTarget(8091); @State(&quot;Product X010000021 exists&quot;) public void setupProductX010000021() throws IOException { reset(productClient); ProductBuilder product = new ProductBuilder() .withProductCode(&quot;X010000021&quot;); when(productClient.fetch((Set&lt;String&gt;) argThat(contains(&quot;X010000021&quot;)), any())).thenReturn(product); } @State(&quot;the product code X00001 can be priced&quot;) public void theProductCodeX00001CanBePriced() throws IOException { reset(productClient); ProductBuilder product = new ProductBuilder() .withProductCode(&quot;X00001&quot;); when(productClient.find((Set&lt;String&gt;) argThat(contains(&quot;X00001&quot;)), any())).thenReturn(product); } } ``` ### Using Spring Context Properties 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: &quot;your.broker.local&quot; port: &quot;443&quot; protocol: &quot;https&quot; auth: username: &quot;&lt;your broker username&gt;&quot; password: &quot;&lt;your broker password&gt;&quot; ``` Then you can use the defaults on the `@PactBroker` annotation. ```java @RunWith(SpringRestPactRunner.class) @Provider(&quot;My Service&quot;) @PactBroker( authentication = @PactBrokerAuth(username = &quot;${pactbroker.auth.username}&quot;, password = &quot;${pactbroker.auth.password}&quot;) ) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) public class PactVerificationTest { ``` ### Using a random port with a Springboot test If you use a random port in a springboot test (by setting `SpringBootTest.WebEnvironment.RANDOM_PORT`), you need to set it to the `TestTarget`. How this works is different for JUnit4 and JUnit5. #### JUnit4 You can use the `SpringBootHttpTarget` which will get the application port from the spring application context. For example: ```java @RunWith(SpringRestPactRunner.class) @Provider(&quot;My Service&quot;) @PactBroker @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) public class PactVerificationTest { @TestTarget public final Target target = new SpringBootHttpTarget(); } ``` #### JUnit5 You actually don&apos;t need to dependend on `pact-jvm-provider-spring` for this. It&apos;s sufficient to depend on `pact-jvm-provider-junit5`. You can set the port to the `HttpTestTarget` object in the before method. ```java @Provider(&quot;My Service&quot;) @PactBroker @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) public class PactVerificationTest { @LocalServerPort private int port; @BeforeEach void before(PactVerificationContext context) { context.setTarget(new HttpTestTarget(&quot;localhost&quot;, port)); } } ```

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

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

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

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&lt;String, String&gt; headers = new HashMap&lt;String, String&gt;(); headers.put(&quot;testreqheader&quot;, &quot;testreqheadervalue&quot;); return builder .given(&quot;test state&quot;) // NOTE: Using provider states are optional, you can leave it out .uponReceiving(&quot;ExampleJavaConsumerPactTest test interaction&quot;) .path(&quot;/&quot;) .method(&quot;GET&quot;) .headers(headers) .willRespondWith() .status(200) .headers(headers) .body(&quot;{\&quot;responsetest\&quot;: true, \&quot;name\&quot;: \&quot;harry\&quot;}&quot;) .given(&quot;test state 2&quot;) // NOTE: Using provider states are optional, you can leave it out .uponReceiving(&quot;ExampleJavaConsumerPactTest second test interaction&quot;) .method(&quot;OPTIONS&quot;) .headers(headers) .path(&quot;/second&quot;) .body(&quot;&quot;) .willRespondWith() .status(200) .headers(headers) .body(&quot;&quot;) .toFragment(); } @Override protected String providerName() { return &quot;test_provider&quot;; } @Override protected String consumerName() { return &quot;test_consumer&quot;; } @Override protected void runTest(String url) throws IOException { Assert.assertEquals(new ConsumerClient(url).options(&quot;/second&quot;), 200); Map expectedResponse = new HashMap(); expectedResponse.put(&quot;responsetest&quot;, true); expectedResponse.put(&quot;name&quot;, &quot;harry&quot;); assertEquals(new ConsumerClient(url).getAsMap(&quot;/&quot;, &quot;&quot;), expectedResponse); assertEquals(new ConsumerClient(url).options(&quot;/second&quot;), 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(&quot;test_provider&quot;, &quot;localhost&quot;, 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=&quot;test_provider&quot;, consumer=&quot;test_consumer&quot;) public PactFragment createFragment(PactDslWithProvider builder) { return builder .given(&quot;test state&quot;) .uponReceiving(&quot;ExampleJavaConsumerPactRuleTest test interaction&quot;) .path(&quot;/&quot;) .method(&quot;GET&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;responsetest\&quot;: true}&quot;) .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=&quot;test_consumer&quot;) // will default to the provider name from mockProvider public PactFragment createFragment(PactDslWithProvider builder) { return builder .given(&quot;test state&quot;) .uponReceiving(&quot;ExampleJavaConsumerPactRuleTest test interaction&quot;) .path(&quot;/&quot;) .method(&quot;GET&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;responsetest\&quot;: true}&quot;) .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(&quot;test_provider&quot;) public void runTest() { Map expectedResponse = new HashMap(); expectedResponse.put(&quot;responsetest&quot;, true); assertEquals(new ConsumerClient(&quot;http://localhost:8080&quot;).get(&quot;/&quot;), 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(&quot;responsetest&quot;, true); assertEquals(new ConsumerClient(&quot;http://localhost:8080&quot;).get(&quot;/&quot;), 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&apos;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(&quot;test_provider&quot;, &quot;localhost&quot;, 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(&quot;Some Consumer&quot;) .hasPactWith(&quot;Some Provider&quot;) .uponReceiving(&quot;a request to say Hello&quot;) .path(&quot;/hello&quot;) .method(&quot;POST&quot;) .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;) .toFragment(); MockProviderConfig config = MockProviderConfig.createDefault(); VerificationResult result = pactFragment.runConsumer(config, new TestRun() { @Override public void run(MockProviderConfig config) { Map expectedResponse = new HashMap(); expectedResponse.put(&quot;hello&quot;, &quot;harry&quot;); try { assertEquals(new ProviderClient(config.url()).hello(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;), 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(&quot;Some Consumer&quot;) .hasPactWith(&quot;Some Provider&quot;) .given(&quot;a certain state on the provider&quot;) .uponReceiving(&quot;a request for something&quot;) .path(&quot;/hello&quot;) .method(&quot;POST&quot;) .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;) .uponReceiving(&quot;another request for something&quot;) .path(&quot;/hello&quot;) .method(&quot;POST&quot;) .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;) . . . .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(&quot;name&quot;) .booleanType(&quot;happy&quot;) .hexValue(&quot;hexCode&quot;) .id() .ipAddress(&quot;localAddress&quot;) .numberValue(&quot;age&quot;, 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(&quot;users&quot;, 1) .id() .stringType(&quot;name&quot;) .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(&quot;users&quot;, 1, 2) .id() .stringType(&quot;name&quot;) .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(&quot;clearedDate&quot;, &quot;mm/dd/yyyy&quot;, date) .stringType(&quot;status&quot;, &quot;STATUS&quot;) .decimalType(&quot;amount&quot;, 100.0) .closeObject() ``` This will then match a body like: ```json [ { &quot;clearedDate&quot; : &quot;07/22/2015&quot;, &quot;status&quot; : &quot;C&quot;, &quot;amount&quot; : 15.0 }, { &quot;clearedDate&quot; : &quot;07/22/2015&quot;, &quot;status&quot; : &quot;C&quot;, &quot;amount&quot; : 15.0 }, { &quot;clearedDate&quot; : &quot;07/22/2015&quot;, &quot;status&quot; : &quot;C&quot;, &quot;amount&quot; : 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(&quot;Some Consumer&quot;) .hasPactWith(&quot;Some Provider&quot;) .uponReceiving(&quot;a request for a basic JSON value&quot;) .path(&quot;/hello&quot;) .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(&quot;one&quot;) .eachKeyLike(&quot;001&quot;, PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher .closeObject() .object(&quot;two&quot;) .eachKeyLike(&quot;001-A&quot;) // key like an id where the value is matched by the following example .stringType(&quot;description&quot;, &quot;Some Description&quot;) .closeObject() .closeObject() .object(&quot;three&quot;) .eachKeyMappedToAnArrayLike(&quot;001&quot;) // key like an id mapped to an array where each item is matched by the following example .id(&quot;someId&quot;, 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(&quot;test state&quot;) .uponReceiving(&quot;a test interaction&quot;) .matchPath(&quot;/transaction/[0-9]+&quot;) // or .matchPath(&quot;/transaction/[0-9]+&quot;, &quot;/transaction/1234567890&quot;) .method(&quot;POST&quot;) .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;) ``` ### 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(&quot;test state&quot;) .uponReceiving(&quot;a test interaction&quot;) .path(&quot;/hello&quot;) .method(&quot;POST&quot;) .matchHeader(&quot;testreqheader&quot;, &quot;test.*value&quot;) .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;) .matchHeader(&quot;Location&quot;, &quot;.*/hello/[0-9]+&quot;, &quot;/hello/1234&quot;) ``` ### 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(&quot;test state&quot;) .uponReceiving(&quot;a test interaction&quot;) .path(&quot;/hello&quot;) .method(&quot;POST&quot;) .matchQuery(&quot;a&quot;, &quot;\\d+&quot;, &quot;100&quot;) .matchQuery(&quot;b&quot;, &quot;[A-Z]&quot;, &quot;X&quot;) .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;) .willRespondWith() .status(200) .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;) ``` ## 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[&apos;pact.rootDir&apos;] = &quot;$buildDir/pacts&quot; } ``` For maven, use the systemPropertyVariables configuration: ```xml &lt;project&gt; [...] &lt;build&gt; &lt;plugins&gt; &lt;plugin&gt; &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt; &lt;artifactId&gt;maven-surefire-plugin&lt;/artifactId&gt; &lt;version&gt;2.18&lt;/version&gt; &lt;configuration&gt; &lt;systemPropertyVariables&gt; &lt;pact.rootDir&gt;some/other/directory&lt;/pact.rootDir&gt; &lt;buildDirectory&gt;${project.build.directory}&lt;/buildDirectory&gt; [...] &lt;/systemPropertyVariables&gt; &lt;/configuration&gt; &lt;/plugin&gt; &lt;/plugins&gt; &lt;/build&gt; [...] &lt;/project&gt; ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq(&quot;-Dpact.rootDir=some/other/directory&quot;) ``` # 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&apos;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(&quot;test_provider&quot;, 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)