Download JAR files tagged by module with all dependencies

Module that defines the HttpChannel API. HttpChannels abstract complex download and upload steps into a simple and easy to use NIO Channel. NIO Channels can be wrapped into an InputStream or OutputStream and used in any way you may find possible to. Aside from that, Channels can be used natively in most next-gen libraries, meaning that you don't even need to wrap anything, just start writing or reading data to or from the channel wth a ByteBuffer. Anyone using the library should try to rely on code from this module only and, only if necessary, on configuration classes that are implementation specific. Relying on any other resource or class is considered an error and should NOT be done. One of the most interesting usages of channels for uploads and download is that you can easily copy data straight from one channel to the other, with less than 10 lines of code! Also, channels allows the implementation of a "tee" mechanism, in which data redden from a single channel can be copied to several other channels on the fly!

GlassFish build depends on properly functioning several custom lifecycle mappings and artifact handlers. Because these are necessary to resolve dependencies and to run "gf:run" goal and etc., it is critical that these extensions be made available to Maven early on during Maven execution. This definition was originally in maven-glassfish-plugin, which was integrated into Maven POM through <plugin>/<extensions>true marking, but after a series of debugging to resolve artifact resolution failure problems, it turns out that that doesn't cause Maven to load components early enough. I tried to circumbent the prolem by also registering the maven-glassfish-plugin as an extension module (via <build>/<extensions/<extension>), but that apparently confuses Maven to no end --- I get build errors like this: [INFO] Internal error in the plugin manager executing goal 'org.apache.maven.plugins:maven-jar-plugin:2.1:jar': Unable to find the mojo 'org.apache.maven.plugins:maven-jar-plugin:2.1:jar' in the plugin 'org.apache.maven.plugins:maven-jar-plugin' This is obviously one of the problematic areas of Maven, so to avoid doing hack over hack, I'm simply moving the component definitions to its own module.

GlassFish build depends on properly functioning several custom lifecycle mappings and artifact handlers. Because these are necessary to resolve dependencies and to run "gf:run" goal and etc., it is critical that these extensions be made available to Maven early on during Maven execution. This definition was originally in maven-glassfish-plugin, which was integrated into Maven POM through <plugin>/<extensions>true marking, but after a series of debugging to resolve artifact resolution failure problems, it turns out that that doesn't cause Maven to load components early enough. I tried to circumbent the prolem by also registering the maven-glassfish-plugin as an extension module (via <build>/<extensions/<extension>), but that apparently confuses Maven to no end --- I get build errors like this: [INFO] Internal error in the plugin manager executing goal 'org.apache.maven.plugins:maven-jar-plugin:2.1:jar': Unable to find the mojo 'org.apache.maven.plugins:maven-jar-plugin:2.1:jar' in the plugin 'org.apache.maven.plugins:maven-jar-plugin' This is obviously one of the problematic areas of Maven, so to avoid doing hack over hack, I'm simply moving the component definitions to its own module.

# Pact Spring/JUnit5 Support This module extends the base [Pact JUnit5 module](../pact-jvm-provider-junit5). See that for more details. For writing Spring Pact verification tests with JUnit 5, there is an JUnit 5 Invocation Context Provider that you can use with the `@TestTemplate` annotation. This will generate a test for each interaction found for the pact files for the provider. To use it, add the `@Provider` and `@ExtendWith(SpringExtension.class)` and one of the pact source annotations to your test class (as per a JUnit 5 test), then add a method annotated with `@TestTemplate` and `@ExtendWith(PactVerificationSpringProvider.class)` that takes a `PactVerificationContext` parameter. You will need to call `verifyInteraction()` on the context parameter in your test template method. For example: ```java @ExtendWith(SpringExtension.class) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT) @Provider(&quot;Animal Profile Service&quot;) @PactBroker public class ContractVerificationTest { @TestTemplate @ExtendWith(PactVerificationSpringProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } } ``` You will now be able to setup all the required properties using the Spring context, e.g. creating an application YAML file in the test resources: ```yaml pactbroker: host: your.broker.host auth: username: broker-user password: broker.password ``` You can also run pact tests against `MockMvc` without need to spin up the whole application context which takes time and often requires more additional setup (e.g. database). In order to run lightweight tests just use `@WebMvcTest` from Spring and `MockMvcTestTarget` as a test target before each test. For example: ```java @WebMvcTest @Provider(&quot;myAwesomeService&quot;) @PactBroker class ContractVerificationTest { @Autowired private MockMvc mockMvc; @TestTemplate @ExtendWith(PactVerificationInvocationContextProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } @BeforeEach void before(PactVerificationContext context) { context.setTarget(new MockMvcTestTarget(mockMvc)); } } ``` You can also use `MockMvcTestTarget` for tests without spring context by providing the controllers manually. For example: ```java @Provider(&quot;myAwesomeService&quot;) @PactFolder(&quot;pacts&quot;) class MockMvcTestTargetStandaloneMockMvcTestJava { @TestTemplate @ExtendWith(PactVerificationInvocationContextProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } @BeforeEach void before(PactVerificationContext context) { MockMvcTestTarget testTarget = new MockMvcTestTarget(); testTarget.setControllers(new DataResource()); context.setTarget(testTarget); } @RestController static class DataResource { @GetMapping(&quot;/data&quot;) @ResponseStatus(HttpStatus.NO_CONTENT) void getData(@RequestParam(&quot;ticketId&quot;) String ticketId) { } } } ``` **Important:** Since `@WebMvcTest` starts only Spring MVC components you can&apos;t use `PactVerificationSpringProvider` and need to fallback to `PactVerificationInvocationContextProvider`

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

This is the main aggregator for all gwt submodules. All gwt-specific code resides here. Submodules should avoid inheriting from each other unless necessary. This goes for maven structure and gwt.xml structure. The super module is where our jre emulation layer and super-source live; all modules should inherit super, and a minimum of other modules. Some modules, like injection, are fulfilling an api in the core module, and should be accessed only through core service interfaces. Other modules, like reflection, are capable of being standalone inherits, but can benefit from core utilities like injection, so, two (or more) .gwt.xml modules may be provided. As XApi nears 1.0, all submodules will be routinely stitched together into an uber-jar, in order to have a single jar with a single gwt module that can provide all of the services at once. Internal projects will never use the uber jar, to help maintain modularity, but external projects that want to use more than one service will certainly prefer inheriting one artifact, instead of twelve. When distributed in uber-jar format, it will likely be necessary for either the uber jar, or just xapi-gwt-api.jar to appear before gwt-dev on your compile-time classpath. If using gwt-maven-plugin, the gwtFirstOnClasspath option may become problematic. If so, we will provide a forked gwt-plugin to make sure our compiler enhancements are included in the build process. There is also work going on to make a super-source-everything plugin, which will use maven to find source files, and generate synthetic .gwt.xml for you, as part of an effort to create a wholly unified programming environment. In addition to java-to-javascript, we intend to compile java-to-java and possibly other languages, like go; imagine implementing gwt deferred binding to eliminate cross-platform differences between server environments, or operating systems, or versions of a platform, or anywhere else a core api needs to bind to multiple implementations, depending on the runtime environment.

Pact consumer ============= Pact Consumer is used by projects that are consumers of an API. Most projects will want to use pact-consumer via one of the test framework specific projects. If your favourite framework is not implemented, this module should give you all the hooks you need. Provides a DSL for use with Java to build consumer pacts. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer_2.11` ## DSL Usage Example in a JUnit test: ```java import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.PactFragment; import org.junit.Test; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static org.junit.Assert.assertEquals; public class PactTest { @Test public void testPact() { PactFragment pactFragment = ConsumerPactBuilder .consumer(&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) {} } }); if (result instanceof PactError) { throw new RuntimeException(((PactError)result).error()); } assertEquals(ConsumerPactTest.PACT_VERIFIED, result); } } ``` 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;) .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. #### 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()) ``` #### 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 } ] ``` #### Matching arrays of arrays (version 3.2.12/2.4.14+) For the case where you have arrays of arrays (GeoJSON is an example), the following methods have been provided: | function | description | |----------|-------------| | `eachArrayLike` | Ensure that each item in the array is an array that matches the provided example | | `eachArrayWithMaxLike` | Ensure that each item in the array is an array that matches the provided example and the array is no bigger than the provided max | | `eachArrayWithMinLike` | Ensure that each item in the array is an array that matches the provided example and the array is no smaller than the provided min | For example (with GeoJSON structure): ```java new PactDslJsonBody() .stringType(&quot;type&quot;,&quot;FeatureCollection&quot;) .eachLike(&quot;features&quot;) .stringType(&quot;type&quot;,&quot;Feature&quot;) .object(&quot;geometry&quot;) .stringType(&quot;type&quot;,&quot;Point&quot;) .eachArrayLike(&quot;coordinates&quot;) // coordinates is an array of arrays .decimalType(-7.55717) .decimalType(49.766896) .closeArray() .closeArray() .closeObject() .object(&quot;properties&quot;) .stringType(&quot;prop0&quot;,&quot;value0&quot;) .closeObject() .closeObject() .closeArray() ``` This generated the following JSON: ```json { &quot;features&quot;: [ { &quot;geometry&quot;: { &quot;coordinates&quot;: [[-7.55717, 49.766896]], &quot;type&quot;: &quot;Point&quot; }, &quot;type&quot;: &quot;Feature&quot;, &quot;properties&quot;: { &quot;prop0&quot;: &quot;value0&quot; } } ], &quot;type&quot;: &quot;FeatureCollection&quot; } ``` and will be able to match all coordinates regardless of the number of coordinates. #### Matching any key in a map (3.3.1/2.5.0+) The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/131). In this case you can use the `eachKeyLike` method, which takes an example key as a parameter. For example: ```java DslPart body = new PactDslJsonBody() .object(&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;) ```

Pact consumer ============= Pact Consumer is used by projects that are consumers of an API. Most projects will want to use pact-consumer via one of the test framework specific projects. If your favourite framework is not implemented, this module should give you all the hooks you need. Provides a DSL for use with Java to build consumer pacts. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer_2.11` ## DSL Usage Example in a JUnit test: ```java import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.RequestResponsePact; import org.apache.http.entity.ContentType; import org.jetbrains.annotations.NotNull; 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; public class PactTest { @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, new PactTestRun() { @Override public void run(@NotNull MockServer mockServer) throws IOException { Map expectedResponse = new HashMap(); expectedResponse.put(&quot;hello&quot;, &quot;harry&quot;); assertEquals(expectedResponse, new ConsumerClient(mockServer.getUrl()).post(&quot;/hello&quot;, &quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;, ContentType.APPLICATION_JSON)); } }); if (result instanceof PactVerificationResult.Error) { throw new RuntimeException(((PactVerificationResult.Error)result).getError()); } assertEquals(PactVerificationResult.Ok.INSTANCE, result); } } ``` 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 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;) .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. #### 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()) ``` #### 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 } ] ``` #### Matching arrays of arrays (version 3.2.12/2.4.14+) For the case where you have arrays of arrays (GeoJSON is an example), the following methods have been provided: | function | description | |----------|-------------| | `eachArrayLike` | Ensure that each item in the array is an array that matches the provided example | | `eachArrayWithMaxLike` | Ensure that each item in the array is an array that matches the provided example and the array is no bigger than the provided max | | `eachArrayWithMinLike` | Ensure that each item in the array is an array that matches the provided example and the array is no smaller than the provided min | For example (with GeoJSON structure): ```java new PactDslJsonBody() .stringType(&quot;type&quot;,&quot;FeatureCollection&quot;) .eachLike(&quot;features&quot;) .stringType(&quot;type&quot;,&quot;Feature&quot;) .object(&quot;geometry&quot;) .stringType(&quot;type&quot;,&quot;Point&quot;) .eachArrayLike(&quot;coordinates&quot;) // coordinates is an array of arrays .decimalType(-7.55717) .decimalType(49.766896) .closeArray() .closeArray() .closeObject() .object(&quot;properties&quot;) .stringType(&quot;prop0&quot;,&quot;value0&quot;) .closeObject() .closeObject() .closeArray() ``` This generated the following JSON: ```json { &quot;features&quot;: [ { &quot;geometry&quot;: { &quot;coordinates&quot;: [[-7.55717, 49.766896]], &quot;type&quot;: &quot;Point&quot; }, &quot;type&quot;: &quot;Feature&quot;, &quot;properties&quot;: { &quot;prop0&quot;: &quot;value0&quot; } } ], &quot;type&quot;: &quot;FeatureCollection&quot; } ``` and will be able to match all coordinates regardless of the number of coordinates. #### Matching any key in a map (3.3.1/2.5.0+) The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/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](../pact-jvm-consumer-junit/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.** ### 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;) ``` # 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`. # 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 allow 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 consumer ============= Pact Consumer is used by projects that are consumers of an API. Most projects will want to use pact-consumer via one of the test framework specific projects. If your favourite framework is not implemented, this module should give you all the hooks you need. Provides a DSL for use with Java to build consumer pacts. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer` ## DSL Usage Example in a JUnit test: ```java import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.RequestResponsePact; import org.apache.http.entity.ContentType; import org.jetbrains.annotations.NotNull; 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; public class PactTest { @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, new PactTestRun() { @Override public void run(@NotNull MockServer mockServer) throws IOException { Map expectedResponse = new HashMap(); expectedResponse.put(&quot;hello&quot;, &quot;harry&quot;); assertEquals(expectedResponse, new ConsumerClient(mockServer.getUrl()).post(&quot;/hello&quot;, &quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;, ContentType.APPLICATION_JSON)); } }); if (result instanceof PactVerificationResult.Error) { throw new RuntimeException(((PactVerificationResult.Error)result).getError()); } assertEquals(PactVerificationResult.Ok.INSTANCE, result); } } ``` 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 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;) .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. #### 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()) ``` #### 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 } ] ``` #### Matching arrays of arrays For the case where you have arrays of arrays (GeoJSON is an example), the following methods have been provided: | function | description | |----------|-------------| | `eachArrayLike` | Ensure that each item in the array is an array that matches the provided example | | `eachArrayWithMaxLike` | Ensure that each item in the array is an array that matches the provided example and the array is no bigger than the provided max | | `eachArrayWithMinLike` | Ensure that each item in the array is an array that matches the provided example and the array is no smaller than the provided min | For example (with GeoJSON structure): ```java new PactDslJsonBody() .stringType(&quot;type&quot;,&quot;FeatureCollection&quot;) .eachLike(&quot;features&quot;) .stringType(&quot;type&quot;,&quot;Feature&quot;) .object(&quot;geometry&quot;) .stringType(&quot;type&quot;,&quot;Point&quot;) .eachArrayLike(&quot;coordinates&quot;) // coordinates is an array of arrays .decimalType(-7.55717) .decimalType(49.766896) .closeArray() .closeArray() .closeObject() .object(&quot;properties&quot;) .stringType(&quot;prop0&quot;,&quot;value0&quot;) .closeObject() .closeObject() .closeArray() ``` This generated the following JSON: ```json { &quot;features&quot;: [ { &quot;geometry&quot;: { &quot;coordinates&quot;: [[-7.55717, 49.766896]], &quot;type&quot;: &quot;Point&quot; }, &quot;type&quot;: &quot;Feature&quot;, &quot;properties&quot;: { &quot;prop0&quot;: &quot;value0&quot; } } ], &quot;type&quot;: &quot;FeatureCollection&quot; } ``` and will be able to match all coordinates regardless of the number of coordinates. #### 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](../pact-jvm-consumer-junit/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.** ### 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;) ``` # 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`. # 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 allow 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 consumer ============= Pact Consumer is used by projects that are consumers of an API. Most projects will want to use pact-consumer via one of the test framework specific projects. If your favourite framework is not implemented, this module should give you all the hooks you need. Provides a DSL for use with Java to build consumer pacts. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer_2.11` ## DSL Usage Example in a JUnit test: ```java import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.RequestResponsePact; import org.apache.http.entity.ContentType; import org.jetbrains.annotations.NotNull; 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; public class PactTest { @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, new PactTestRun() { @Override public void run(@NotNull MockServer mockServer) throws IOException { Map expectedResponse = new HashMap(); expectedResponse.put(&quot;hello&quot;, &quot;harry&quot;); assertEquals(expectedResponse, new ConsumerClient(mockServer.getUrl()).post(&quot;/hello&quot;, &quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;, ContentType.APPLICATION_JSON)); } }); if (result instanceof PactVerificationResult.Error) { throw new RuntimeException(((PactVerificationResult.Error)result).getError()); } assertEquals(PactVerificationResult.Ok.INSTANCE, result); } } ``` 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 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;) .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. #### 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()) ``` #### 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 } ] ``` #### Matching arrays of arrays (version 3.2.12/2.4.14+) For the case where you have arrays of arrays (GeoJSON is an example), the following methods have been provided: | function | description | |----------|-------------| | `eachArrayLike` | Ensure that each item in the array is an array that matches the provided example | | `eachArrayWithMaxLike` | Ensure that each item in the array is an array that matches the provided example and the array is no bigger than the provided max | | `eachArrayWithMinLike` | Ensure that each item in the array is an array that matches the provided example and the array is no smaller than the provided min | For example (with GeoJSON structure): ```java new PactDslJsonBody() .stringType(&quot;type&quot;,&quot;FeatureCollection&quot;) .eachLike(&quot;features&quot;) .stringType(&quot;type&quot;,&quot;Feature&quot;) .object(&quot;geometry&quot;) .stringType(&quot;type&quot;,&quot;Point&quot;) .eachArrayLike(&quot;coordinates&quot;) // coordinates is an array of arrays .decimalType(-7.55717) .decimalType(49.766896) .closeArray() .closeArray() .closeObject() .object(&quot;properties&quot;) .stringType(&quot;prop0&quot;,&quot;value0&quot;) .closeObject() .closeObject() .closeArray() ``` This generated the following JSON: ```json { &quot;features&quot;: [ { &quot;geometry&quot;: { &quot;coordinates&quot;: [[-7.55717, 49.766896]], &quot;type&quot;: &quot;Point&quot; }, &quot;type&quot;: &quot;Feature&quot;, &quot;properties&quot;: { &quot;prop0&quot;: &quot;value0&quot; } } ], &quot;type&quot;: &quot;FeatureCollection&quot; } ``` and will be able to match all coordinates regardless of the number of coordinates. #### Matching any key in a map (3.3.1/2.5.0+) The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/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](../pact-jvm-consumer-junit/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.** ### 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;) ```