最新发布的Jar包


开发团队 项目名称 描述 版本数量 项目大小 发布时间
au.com.dius pact-jvm-provider-junit5_2.11 # Pact Junit 5 Extension ## Overview For writing 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 one of the pact source annotations to your test class (as per a JUnit 4 test), then add a method annotated with `@TestTemplate` and `@ExtendWith(PactVerificationInvocationContextProvider.class)` that takes a `PactVerificationContext` parameter. You will need to call `verifyInteraction()` on the context parameter in your test template method. For example: ```java @Provider("myAwesomeService") @PactFolder("pacts") public class ContractVerificationTest { @TestTemplate @ExtendWith(PactVerificationInvocationContextProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } } ``` For details on the provider and pact source annotations, refer to the [Pact junit runner](../pact-jvm-provider-junit/README.md) docs. ## Test target You can set the test target (the object that defines the target of the test, which should point to your provider) on the `PactVerificationContext`, but you need to do this in a before test method (annotated with `@BeforeEach`). There are three different test targets you can use: `HttpTestTarget`, `HttpsTestTarget` and `AmpqTestTarget`. For example: ```java @BeforeEach void before(PactVerificationContext context) { context.setTarget(HttpTestTarget.fromUrl(new URL(myProviderUrl))); // or something like // context.setTarget(new HttpTestTarget("localhost", myProviderPort, "/")); } ``` ## Provider State Methods Provider State Methods work in the same way as with JUnit 4 tests, refer to the [Pact junit runner](../pact-jvm-provider-junit/README.md) docs. ## Modifying the requests before they are sent **Important Note:** You should only use this feature for things that can not be persisted in the pact file. By modifying the request, you are potentially modifying the contract from the consumer tests! Sometimes you may need to add things to the requests that can't be persisted in a pact file. Examples of these would be authentication tokens, which have a small life span. The Http and Https test targets support injecting the request that will executed into the test template method. You can then add things to the request before calling the `verifyInteraction()` method. For example to add a header: ```java @TestTemplate @ExtendWith(PactVerificationInvocationContextProvider.class) void testTemplate(PactVerificationContext context, HttpRequest request) { // This will add a header to the request request.addHeader("X-Auth-Token", "1234"); context.verifyInteraction(); } ``` ## Objects that can be injected into the test methods You can inject the following objects into your test methods (just like the `PactVerificationContext`). They will be null if injected before the supported phase. | Object | Can be injected from phase | Description | | ------ | --------------- | ----------- | | PactVerificationContext | @BeforeEach | The context to use to execute the interaction test | | Pact | any | The Pact model for the test | | Interaction | any | The Interaction model for the test | | HttpRequest | @TestTemplate | The request that is going to be executed (only for HTTP and HTTPS targets) | | ProviderVerifier | @TestTemplate | The verifier instance that is used to verify the interaction | 3 53.1 KB 2018-06-17T16:20:17
au.com.dius pact-jvm-provider-gradle_2.11 pact-jvm-provider-gradle ======================== Gradle plugin for verifying pacts against a provider. The Gradle plugin creates a task `pactVerify` to your build which will verify all configured pacts against your provider. ## To Use It ### For Gradle versions prior to 2.1 #### 1.1. Add the pact-jvm-provider-gradle jar file to your build script class path: ```groovy buildscript { repositories { mavenCentral() } dependencies { classpath 'au.com.dius:pact-jvm-provider-gradle_2.10:3.2.11' } } ``` #### 1.2. Apply the pact plugin ```groovy apply plugin: 'au.com.dius.pact' ``` ### For Gradle versions 2.1+ ```groovy plugins { id "au.com.dius.pact" version "3.2.11" } ``` ### 2. Define the pacts between your consumers and providers ```groovy pact { serviceProviders { // You can define as many as you need, but each must have a unique name provider1 { // All the provider properties are optional, and have sensible defaults (shown below) protocol = 'http' host = 'localhost' port = 8080 path = '/' // Again, you can define as many consumers for each provider as you need, but each must have a unique name hasPactWith('consumer1') { // currently supports a file path using file() or a URL using url() pactSource = file('path/to/provider1-consumer1-pact.json') } // Or if you have many pact files in a directory hasPactsWith('manyConsumers') { // Will define a consumer for each pact file in the directory. // Consumer name is read from contents of pact file pactFileLocation = file('path/to/pacts') } } } } ``` ### 3. Execute `gradle pactVerify` ## Specifying the provider hostname at runtime If you need to calculate the provider hostname at runtime, you can give a Closure as the provider `host`. ```groovy pact { serviceProviders { provider1 { host = { lookupHostName() } hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` _Since version 3.3.2+/2.4.17+_ you can also give a Closure as the provider `port`. ## Specifying the pact file or URL at runtime [versions 3.2.7/2.4.9+] If you need to calculate the pact file or URL at runtime, you can give a Closure as the provider `pactFile`. ```groovy pact { serviceProviders { provider1 { host = 'localhost' hasPactWith('consumer1') { pactFile = { lookupPactFile() } } } } } ``` ## Starting and shutting down your provider If you need to start-up or shutdown your provider, define Gradle tasks for each action and set `startProviderTask` and `terminateProviderTask` properties of each provider. You could use the jetty tasks here if you provider is built as a WAR file. ```groovy // This will be called before the provider task task('startTheApp') { doLast { // start up your provider here } } // This will be called after the provider task task('killTheApp') { doLast { // kill your provider here } } pact { serviceProviders { provider1 { startProviderTask = startTheApp terminateProviderTask = killTheApp hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` Following typical Gradle behaviour, you can set the provider task properties to the actual tasks, or to the task names as a string (for the case when they haven't been defined yet). ## Preventing the chaining of provider verify task to `pactVerify` [version 3.4.1+] Normally a gradle task named `pactVerify_${provider.name}` is created and added as a task dependency for `pactVerify`. You can disable this dependency on a provider by setting `isDependencyForPactVerify` to `false` (defaults to `true`). ```groovy pact { serviceProviders { provider1 { isDependencyForPactVerify = false hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` To run this task, you would then have to explicitly name it as in ```gradle pactVerify_provider1```, a normal ```gradle pactVerify``` would skip it. This can be useful when you want to define two providers, one with `startProviderTask`/`terminateProviderTask` and as second without, so you can manually start your provider (to debug it from your IDE, for example) but still want a `pactVerify` to run normally from your CI build. ## Enabling insecure SSL [version 2.2.8+] For providers that are running on SSL with self-signed certificates, you need to enable insecure SSL mode by setting `insecure = true` on the provider. ```groovy pact { serviceProviders { provider1 { insecure = true // allow SSL with a self-signed cert hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` ## Specifying a custom trust store [version 2.2.8+] For environments that are running their own certificate chains: ```groovy pact { serviceProviders { provider1 { trustStore = new File('relative/path/to/trustStore.jks') trustStorePassword = 'changeit' hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` `trustStore` is either relative to the current working (build) directory. `trustStorePassword` defaults to `changeit`. NOTE: The hostname will still be verified against the certificate. ## Modifying the HTTP Client Used [version 2.2.4+] The default HTTP client is used for all requests to providers (created with a call to `HttpClients.createDefault()`). This can be changed by specifying a closure assigned to createClient on the provider that returns a CloseableHttpClient. For example: ```groovy pact { serviceProviders { provider1 { createClient = { provider -> // This will enable the client to accept self-signed certificates HttpClients.custom().setSSLHostnameVerifier(new NoopHostnameVerifier()) .setSslcontext(new SSLContextBuilder().loadTrustMaterial(null, { x509Certificates, s -> true }) .build()) .build() } hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` ## Modifying the requests before they are sent **NOTE on breaking change: Version 2.1.8+ uses Apache HttpClient instead of HttpBuilder so the closure will receive a HttpRequest object instead of a request Map.** Sometimes you may need to add things to the requests that can't be persisted in a pact file. Examples of these would be authentication tokens, which have a small life span. The Pact Gradle plugin provides a request filter that can be set to a closure on the provider that will be called before the request is made. This closure will receive the HttpRequest prior to it being executed. ```groovy pact { serviceProviders { provider1 { requestFilter = { req -> // Add an authorization header to each request req.addHeader('Authorization', 'OAUTH eyJhbGciOiJSUzI1NiIsImN0eSI6ImFw...') } hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') } } } } ``` __*Important Note:*__ You should only use this feature for things that can not be persisted in the pact file. By modifying the request, you are potentially modifying the contract from the consumer tests! ## Turning off URL decoding of the paths in the pact file [version 3.3.3+] By default the paths loaded from the pact file will be decoded before the request is sent to the provider. To turn this behaviour off, set the system property `pact.verifier.disableUrlPathDecoding` to `true`. __*Important Note:*__ If you turn off the url path decoding, you need to ensure that the paths in the pact files are correctly encoded. The verifier will not be able to make a request with an invalid encoded path. ## Project Properties The following project properties can be specified with `-Pproperty=value` on the command line: |Property|Description| |--------|-----------| |pact.showStacktrace|This turns on stacktrace printing for each request. It can help with diagnosing network errors| |pact.showFullDiff|This turns on displaying the full diff of the expected versus actual bodies [version 3.3.6+]| |pact.filter.consumers|Comma seperated list of consumer names to verify| |pact.filter.description|Only verify interactions whose description match the provided regular expression| |pact.filter.providerState|Only verify interactions whose provider state match the provided regular expression. An empty string matches interactions that have no state| |pact.verifier.publishResults|Publishing of verification results will be skipped unless this property is set to 'true'| ## Provider States For a description of what provider states are, see the pact documentations: http://docs.pact.io/documentation/provider_states.html ### Using a state change URL For each provider you can specify a state change URL to use to switch the state of the provider. This URL will receive the providerState description and all the parameters from the pact file before each interaction via a POST. As for normal requests, a request filter (`stateChangeRequestFilter`) can also be set to manipulate the request before it is sent. ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') stateChangeUrl = url('http://localhost:8001/tasks/pactStateChange') stateChangeUsesBody = false // defaults to true stateChangeRequestFilter = { req -> // Add an authorization header to each request req.addHeader('Authorization', 'OAUTH eyJhbGciOiJSUzI1NiIsImN0eSI6ImFw...') } } // or hasPactsWith('consumers') { pactFileLocation = file('path/to/pacts') stateChangeUrl = url('http://localhost:8001/tasks/pactStateChange') stateChangeUsesBody = false // defaults to true } } } } ``` If the `stateChangeUsesBody` is not specified, or is set to true, then the provider state description and parameters will be sent as JSON in the body of the request : ```json { "state" : "a provider state description", "params": { "a": "1", "b": "2" } } ``` If it is set to false, they will be passed as query parameters. #### Teardown calls for state changes [version 3.2.5/2.4.7+] You can enable teardown state change calls by setting the property `stateChangeTeardown = true` on the provider. This will add an `action` parameter to the state change call. The setup call before the test will receive `action=setup`, and then a teardown call will be made afterwards to the state change URL with `action=teardown`. ### Using a Closure [version 2.2.2+] You can set a closure to be called before each verification with a defined provider state. The closure will be called with the state description and parameters from the pact file. ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') // Load a fixture file based on the provider state and then setup some database // data. Does not require a state change request so returns false stateChange = { providerState -> // providerState is an instance of ProviderState def fixture = loadFixtuerForProviderState(providerState) setupDatabase(fixture) } } } } } ``` #### Teardown calls for state changes [version 3.2.5/2.4.7+] You can enable teardown state change calls by setting the property `stateChangeTeardown = true` on the provider. This will add an `action` parameter to the state change closure call. The setup call before the test will receive `setup`, as the second parameter, and then a teardown call will be made afterwards with `teardown` as the second parameter. ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = file('path/to/provider1-consumer1-pact.json') // Load a fixture file based on the provider state and then setup some database // data. Does not require a state change request so returns false stateChange = { providerState, action -> if (action == 'setup') { def fixture = loadFixtuerForProviderState(providerState) setupDatabase(fixture) } else { cleanupDatabase() } false } } } } } ``` ## Filtering the interactions that are verified You can filter the interactions that are run using three project properties: `pact.filter.consumers`, `pact.filter.description` and `pact.filter.providerState`. Adding `-Ppact.filter.consumers=consumer1,consumer2` to the command line will only run the pact files for those consumers (consumer1 and consumer2). Adding `-Ppact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `-Ppact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `-Ppact.filter.providerState=` will match any interaction that does not have a provider state. ## Verifying pact files from a pact broker [version 3.1.1+/2.3.1+] You can setup your build to validate against the pacts stored in a pact broker. The pact gradle plugin will query the pact broker for all consumers that have a pact with the provider based on its name. For example: ```groovy pact { serviceProviders { provider1 { // You can get the latest pacts from the broker hasPactsFromPactBroker('http://pact-broker:5000/') // And/or you can get the latest pact with a specific tag hasPactsFromPactBrokerWithTag('http://pact-broker:5000/',"tagname") } } } ``` This will verify all pacts found in the pact broker where the provider name is 'provider1'. If you need to set any values on the consumers from the pact broker, you can add a Closure to configure them. ```groovy pact { serviceProviders { provider1 { hasPactsFromPactBroker('http://pact-broker:5000/') { consumer -> stateChange = { providerState -> /* state change code here */ true } } } } } ``` **NOTE: Currently the pacts are fetched from the broker during the configuration phase of the build. This means that if the broker is not available, you will not be able to run any Gradle tasks.** This should be fixed in a forth coming release. In the mean time, to only load the pacts when running the validate task, you can do something like: ```groovy pact { serviceProviders { provider1 { // Only load the pacts from the broker if the start tasks from the command line include pactVerify if ('pactVerify' in gradle.startParameter.taskNames) { hasPactsFromPactBroker('http://pact-broker:5000/') { consumer -> stateChange = { providerState -> /* state change code here */ true } } } } } } ``` ### Using an authenticated Pact Broker You can add the authentication details for the Pact Broker like so: ```groovy pact { serviceProviders { provider1 { hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Basic', pactBrokerUser, pactBrokerPassword]) } } } ``` `pactBrokerUser` and `pactBrokerPassword` can be defined in the gradle properties. ## Verifying pact files from a S3 bucket [version 3.3.2+/2.4.17+] Pact files stored in an S3 bucket can be verified by using an S3 URL to the pact file. I.e., ```groovy pact { serviceProviders { provider1 { hasPactWith('consumer1') { pactFile = 's3://bucketname/path/to/provider1-consumer1-pact.json' } } } } ``` **NOTE:** you can't use the `url` function with S3 URLs, as the URL and URI classes from the Java SDK don't support URLs with the s3 scheme. # Publishing pact files to a pact broker [version 2.2.7+] The pact gradle plugin provides a `pactPublish` task that can publish all pact files in a directory to a pact broker. To use it, you need to add a publish configuration to the pact configuration that defines the directory where the pact files are and the URL to the pact broker. For example: ```groovy pact { publish { pactDirectory = '/pact/dir' // defaults to $buildDir/pacts pactBrokerUrl = 'http://pactbroker:1234' } } ``` You can set any tags that the pacts should be published with by setting the `tags` property. A common use of this is setting the tag to the current source control branch. This supports using pact with feature branches. ```groovy pact { publish { pactDirectory = '/pact/dir' // defaults to $buildDir/pacts pactBrokerUrl = 'http://pactbroker:1234' tags = [project.pactBrokerTag] } } ``` _NOTE:_ The pact broker requires a version for all published pacts. The `pactPublish` task will use the version of the gradle project by default. Make sure you have set one otherwise the broker will reject the pact files. _Version 3.2.2/2.4.3+_ you can override the version in the publish block. ## Publishing to an authenticated pact broker To publish to a broker protected by basic auth, include the username/password in the `pactBrokerUrl`. For example: ```groovy pact { publish { pactBrokerUrl = 'https://username:password@mypactbroker.com' } } ``` ### [version 3.3.9+] You can add the username and password as properties since version 3.3.9+ ```groovy pact { publish { pactBrokerUrl = 'https://mypactbroker.com' pactBrokerUsername = 'username' pactBrokerPassword = 'password' } } ``` # Verifying a message provider [version 2.2.12+] The Gradle plugin has been updated to allow invoking test methods that can return the message contents from a message producer. To use it, set the way to invoke the verification to `ANNOTATED_METHOD`. This will allow the pact verification task to scan for test methods that return the message contents. Add something like the following to your gradle build file: ```groovy pact { serviceProviders { messageProvider { verificationType = 'ANNOTATED_METHOD' packagesToScan = ['au.com.example.messageprovider.*'] // This is optional, but leaving it out will result in the entire // test classpath being scanned hasPactWith('messageConsumer') { pactFile = url('url/to/messagepact.json') } } } } ``` Now when the `pactVerify` task is run, will look for methods annotated with `@PactVerifyProvider` in the test classpath that have a matching description to what is in the pact file. ```groovy class ConfirmationKafkaMessageBuilderTest { @PactVerifyProvider('an order confirmation message') String verifyMessageForOrder() { Order order = new Order() order.setId(10000004) order.setExchange('ASX') order.setSecurityCode('CBA') order.setPrice(BigDecimal.TEN) order.setUnits(15) order.setGst(new BigDecimal('15.0')) order.setFees(BigDecimal.TEN) def message = new ConfirmationKafkaMessageBuilder() .withOrder(order) .build() JsonOutput.toJson(message) } } ``` It will then validate that the returned contents matches the contents for the message in the pact file. ## Publishing to the Gradle Community Portal To publish the plugin to the community portal: $ ./gradlew :pact-jvm-provider-gradle_2.11:publishPlugins # Verification Reports [versions 3.2.7/2.4.9+] The default behaviour is to display the verification being done to the console, and pass or fail the build via the normal Gradle mechanism. From versions 3.2.7/2.4.9+, additional reports can be generated from the verification. ## Enabling additional reports The verification reports can be controlled by adding a reports section to the pact configuration in the gradle build file. For example: ```groovy pact { reports { defaultReports() // adds the standard console output markdown // report in markdown format json // report in json format } } ``` Any report files will be written to "build/reports/pact". ## Additional Reports The following report types are available in addition to console output (which is enabled by default): `markdown`, `json`. # Publishing verification results to a Pact Broker [version 3.5.4+] For pacts that are loaded from a Pact Broker, the results of running the verification can be published back to the broker against the URL for the pact. You will be able to see the result on the Pact Broker home screen. To turn on the verification publishing, set the project property `pact.verifier.publishResults` to `true` [version 3.5.18+]. 133 41.7 KB 2018-06-17T16:18:23
au.com.dius pact-jvm-matchers_2.11 Pact JVM Matchers ================= Implements matchers for pact requests and responses. 129 211.5 KB 2018-06-17T16:16:40
au.com.dius pact-jvm-consumer_2.11 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("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request to say Hello") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .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("hello", "harry"); assertEquals(expectedResponse, new ConsumerClient(mockServer.getUrl()).post("/hello", "{\"name\": \"harry\"}", 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("Some Consumer") .hasPactWith("Some Provider") .given("a certain state on the provider") .uponReceiving("a request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .uponReceiving("another request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") . . . .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("name") .booleanType("happy") .hexValue("hexCode") .id() .ipAddress("localAddress") .numberValue("age", 100) .timestamp(); ``` #### DSL Matching methods The following matching methods are provided with the DSL. In most cases, they take an optional value parameter which will be used to generate example values (i.e. when returning a mock response). If no example value is given, a random one will be generated. | method | description | |--------|-------------| | string, stringValue | Match a string value (using string equality) | | number, numberValue | Match a number value (using Number.equals)\* | | booleanValue | Match a boolean value (using equality) | | stringType | Will match all Strings | | numberType | Will match all numbers\* | | integerType | Will match all numbers that are integers (both ints and longs)\* | | decimalType | Will match all real numbers (floating point and decimal)\* | | booleanType | Will match all boolean values (true and false) | | stringMatcher | Will match strings using the provided regular expression | | timestamp | Will match string containing timestamps. If a timestamp format is not given, will match an ISO timestamp format | | date | Will match string containing dates. If a date format is not given, will match an ISO date format | | time | Will match string containing times. If a time format is not given, will match an ISO time format | | ipAddress | Will match string containing IP4 formatted address. | | id | Will match all numbers by type | | hexValue | Will match all hexadecimal encoded strings | | uuid | Will match strings containing UUIDs | | 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("users") .id() .stringType("name") .closeObject() .closeArray(); ``` This will ensure that the users list is never empty and that each user has an identifier that is a number and a name that is a string. #### Matching JSON values at the root (Version 3.2.2/2.4.3+) For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request for a basic JSON value") .path("/hello") .willRespondWith() .status(200) .body(PactDslJsonRootValue.integerType()) ``` #### Root level arrays that match all items (version 2.2.11+) If the root of the body is an array, you can create PactDslJsonArray classes with the following methods: | function | description | |----------|-------------| | `arrayEachLike` | Ensure that each item in the list matches the provided example | | `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java PactDslJsonArray.arrayEachLike() .date("clearedDate", "mm/dd/yyyy", date) .stringType("status", "STATUS") .decimalType("amount", 100.0) .closeObject() ``` This will then match a body like: ```json [ { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 } ] ``` #### 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("type","FeatureCollection") .eachLike("features") .stringType("type","Feature") .object("geometry") .stringType("type","Point") .eachArrayLike("coordinates") // coordinates is an array of arrays .decimalType(-7.55717) .decimalType(49.766896) .closeArray() .closeArray() .closeObject() .object("properties") .stringType("prop0","value0") .closeObject() .closeObject() .closeArray() ``` This generated the following JSON: ```json { "features": [ { "geometry": { "coordinates": [[-7.55717, 49.766896]], "type": "Point" }, "type": "Feature", "properties": { "prop0": "value0" } } ], "type": "FeatureCollection" } ``` 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("one") .eachKeyLike("001", PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher .closeObject() .object("two") .eachKeyLike("001-A") // key like an id where the value is matched by the following example .stringType("description", "Some Description") .closeObject() .closeObject() .object("three") .eachKeyMappedToAnArrayLike("001") // key like an id mapped to an array where each item is matched by the following example .id("someId", 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). ### Matching on paths (version 2.1.5+) You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide a real path as a second value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .matchPath("/transaction/[0-9]+") // or .matchPath("/transaction/[0-9]+", "/transaction/1234567890") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ### Matching on headers (version 2.2.2+) You can use regular expressions to match request and response headers. The DSL has a `matchHeader` method for this. You can provide an example header value to use when generating requests and responses, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchHeader("testreqheader", "test.*value") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .matchHeader("Location", ".*/hello/[0-9]+", "/hello/1234") ``` ### 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("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchQuery("a", "\\d+", "100") .matchQuery("b", "[A-Z]", "X") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` 134 259.6 KB 2018-06-17T16:15:40
au.com.dius pact-jvm-consumer-specs2_2.11 pact-jvm-consumer-specs2 ======================== ## Specs2 Bindings for the pact-jvm library ## Dependency In the root folder of your project in build.sbt add the line: ```scala libraryDependencies += "au.com.dius" %% "pact-jvm-consumer-specs2" % "3.2.11" ``` or if you are using Gradle: ```groovy dependencies { testCompile "au.com.dius:pact-jvm-consumer-specs2_2.11:3.2.11" } ``` __*Note:*__ `PactSpec` requires spec2 3.x. Also, for spray users there's an incompatibility between specs2 v3.x and spray. Follow these instructions to resolve that problem: https://groups.google.com/forum/#!msg/spray-user/2T6SBp4OJeI/AJlnJuAKPRsJ ## Usage To author a test, mix `PactSpec` into your spec First we define a service client called `ConsumerService`. In our example this is a simple wrapper for `dispatch`, an HTTP client. The source code can be found in the test folder alongside the `ExamplePactSpec`. Here is a simple example: ``` import au.com.dius.pact.consumer.PactSpec class ExamplePactSpec extends Specification with PactSpec { val consumer = "My Consumer" val provider = "My Provider" override def is = uponReceiving("a request for foo") .matching(path = "/foo") .willRespondWith(body = "{}") .withConsumerTest { providerConfig => Await.result(ConsumerService(providerConfig.url).simpleGet("/foo"), Duration(1000, MILLISECONDS)) must beEqualTo(200, Some("{}")) } } ``` This spec will be run along with the rest of your specs2 unit tests and will output your pact json to ``` /target/pacts/<Consumer>_<Provider>.json ``` 134 34.3 KB 2018-06-17T16:14:36
au.com.dius pact-jvm-consumer-junit_2.11 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<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); return builder .given("test state") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/") .method("GET") .headers(headers) .willRespondWith() .status(200) .headers(headers) .body("{\"responsetest\": true, \"name\": \"harry\"}") .given("test state 2") // NOTE: Using provider states are optional, you can leave it out .uponReceiving("ExampleJavaConsumerPactTest second test interaction") .method("OPTIONS") .headers(headers) .path("/second") .body("") .willRespondWith() .status(200) .headers(headers) .body("") .toPact(); } @Override protected String providerName() { return "test_provider"; } @Override protected String consumerName() { return "test_consumer"; } @Override protected void runTest(MockServer mockServer) throws IOException { Assert.assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 200); Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); expectedResponse.put("name", "harry"); assertEquals(new ConsumerClient(mockServer.getUrl()).getAsMap("/", ""), expectedResponse); assertEquals(new ConsumerClient(mockServer.getUrl()).options("/second"), 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("test_provider", "localhost", 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="test_provider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .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="test_consumer") // will default to the provider name from mockProvider public RequestResponsePact createFragment(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactRuleTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .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("test_provider") public void runTest() { Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient(mockProvider.getUrl()).get("/"), expectedResponse); } ``` ##### Versions 3.0.2/2.2.13+ You can leave the provider name out. It will then use the provider name of the first mock provider found. I.e., ```java @Test @PactVerification public void runTest() { // This will run against mockProvider Map expectedResponse = new HashMap(); expectedResponse.put("responsetest", true); assertEquals(new ConsumerClient("http://localhost:8080").get("/"), expectedResponse); } ``` For an example, have a look at [ExampleJavaConsumerPactRuleTest](src/test/java/au/com/dius/pact/consumer/examples/ExampleJavaConsumerPactRuleTest.java) ### Requiring a test with multiple providers The Pact Rule can be used to test with multiple providers. Just add a rule to the test class for each provider, and then include all the providers required in the `@PactVerification` annotation. For an example, look at [PactMultiProviderTest](src/test/java/au/com/dius/pact/consumer/pactproviderrule/PactMultiProviderTest.java). Note that if more than one provider fails verification for the same test, you will only receive a failure for one of them. Also, to have multiple tests in the same test class, the providers must be setup with random ports (i.e. don't specify a hostname and port). Also, if the provider name is left out of any of the annotations, the first one found will be used (which may not be the first one defined). ### Requiring the mock server to run with HTTPS [versions 3.2.7/2.4.9+] From versions 3.2.7/2.4.9+ the mock server can be started running with HTTPS using a self-signed certificate instead of HTTP. To enable this set the `https` parameter to `true`. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, 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's password. E.g.: ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("test_provider", "localhost", 8443, true, "/path/to/your/keystore.jks", "your-keystore-password", 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<String, String> headers = new HashMap<String, String>(); headers.put("testreqheader", "testreqheadervalue"); request.headers(headers); } @DefaultResponseValues public void defaultResponseValues(PactDslResponse response) { Map<String, String> headers = new HashMap<String, String>(); headers.put("testresheader", "testresheadervalue"); 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("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request to say Hello") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .toPact(); MockProviderConfig config = MockProviderConfig.createDefault(); PactVerificationResult result = runConsumerTest(pact, config, mockServer -> { Map expectedResponse = new HashMap(); expectedResponse.put("hello", "harry"); try { assertEquals(new ProviderClient(mockServer.getUrl()).hello("{\"name\": \"harry\"}"), 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("Some Consumer") .hasPactWith("Some Provider") .given("a certain state on the provider") .uponReceiving("a request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .uponReceiving("another request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") . . . .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("name") .booleanType("happy") .hexValue("hexCode") .id() .ipAddress("localAddress") .numberValue("age", 100) .timestamp(); ``` #### DSL Matching methods The following matching methods are provided with the DSL. In most cases, they take an optional value parameter which will be used to generate example values (i.e. when returning a mock response). If no example value is given, a random one will be generated. | method | description | |--------|-------------| | string, stringValue | Match a string value (using string equality) | | number, numberValue | Match a number value (using Number.equals)\* | | booleanValue | Match a boolean value (using equality) | | stringType | Will match all Strings | | numberType | Will match all numbers\* | | integerType | Will match all numbers that are integers (both ints and longs)\* | | decimalType | Will match all real numbers (floating point and decimal)\* | | booleanType | Will match all boolean values (true and false) | | stringMatcher | Will match strings using the provided regular expression | | timestamp | Will match string containing timestamps. If a timestamp format is not given, will match an ISO timestamp format | | date | Will match string containing dates. If a date format is not given, will match an ISO date format | | time | Will match string containing times. If a time format is not given, will match an ISO time format | | ipAddress | Will match string containing IP4 formatted address. | | id | Will match all numbers by type | | hexValue | Will match all hexadecimal encoded strings | | uuid | Will match strings containing UUIDs | | 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("users", 1) .id() .stringType("name") .closeObject() .closeArray(); ``` This will ensure that the users list is never empty and that each user has an identifier that is a number and a name that is a string. __Version 3.2.4/2.4.6+__ You can specify the number of example items to generate in the array. The default is 1. ```java DslPart body = new PactDslJsonBody() .minArrayLike("users", 1, 2) .id() .stringType("name") .closeObject() .closeArray(); ``` This will generate the example body with 2 items in the users list. #### Root level arrays that match all items (version 2.2.11+) If the root of the body is an array, you can create PactDslJsonArray classes with the following methods: | function | description | |----------|-------------| | `arrayEachLike` | Ensure that each item in the list matches the provided example | | `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java PactDslJsonArray.arrayEachLike() .date("clearedDate", "mm/dd/yyyy", date) .stringType("status", "STATUS") .decimalType("amount", 100.0) .closeObject() ``` This will then match a body like: ```json [ { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 } ] ``` __Version 3.2.4/2.4.6+__ You can specify the number of example items to generate in the array. The default is 1. #### Matching JSON values at the root (Version 3.2.2/2.4.3+) For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request for a basic JSON value") .path("/hello") .willRespondWith() .status(200) .body(PactDslJsonRootValue.integerType()) ``` #### Matching 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("one") .eachKeyLike("001", PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher .closeObject() .object("two") .eachKeyLike("001-A") // key like an id where the value is matched by the following example .stringType("description", "Some Description") .closeObject() .closeObject() .object("three") .eachKeyMappedToAnArrayLike("001") // key like an id mapped to an array where each item is matched by the following example .id("someId", 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). #### 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("valueA", 100) .and("valueB","AB", PM.includesStr("A"), PM.includesStr("B")) // Must match both matching rules .or("valueC", 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("test state") .uponReceiving("a test interaction") .matchPath("/transaction/[0-9]+") // or .matchPath("/transaction/[0-9]+", "/transaction/1234567890") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ### Matching on headers (version 2.2.2+) You can use regular expressions to match request and response headers. The DSL has a `matchHeader` method for this. You can provide an example header value to use when generating requests and responses, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchHeader("testreqheader", "test.*value") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .matchHeader("Location", ".*/hello/[0-9]+", "/hello/1234") ``` ### 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("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchQuery("a", "\\d+", "100") .matchQuery("b", "[A-Z]", "X") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ## Debugging pact failures When the test runs, Pact will start a mock provider that will listen for requests and match them against the expectations you setup in `createFragment`. If the request does not match, it will return a 500 error response. Each request received and the generated response is logged using [SLF4J](http://www.slf4j.org/). Just enable debug level logging for au.com.dius.pact.consumer.UnfilteredMockProvider. Most failures tend to be mismatched headers or bodies. ## Changing the directory pact files are written to (2.1.9+) By default, pact files are written to `target/pacts`, but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/pacts" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.build.directory}</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` # Publishing your pact files to a pact broker If you use Gradle, you can use the [pact Gradle plugin](https://github.com/DiUS/pact-jvm/tree/master/pact-jvm-provider-gradle#publishing-pact-files-to-a-pact-broker) to publish your pact files. # Pact Specification V3 Version 3 of the pact specification changes the format of pact files in the following ways: * Query parameters are stored in a map form and are un-encoded (see [#66](https://github.com/DiUS/pact-jvm/issues/66) and [#97](https://github.com/DiUS/pact-jvm/issues/97) for information on what this can cause). * Introduces a new message pact format for testing interactions via a message queue. * 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'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("test_provider", 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) 134 38.9 KB 2018-06-17T16:13:38
au.com.dius pact-jvm-consumer-junit5_2.11 pact-jvm-consumer-junit5 ======================== JUnit 5 support for Pact consumer tests ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-junit5_2.12` * version-id = `3.5.x` ## Usage ### 1. Add the Pact consumer test extension to the test class. To write Pact consumer tests with JUnit 5, you need to add `@ExtendWith(PactConsumerTestExt)` to your test class. This replaces the `PactRunner` used for JUnit 4 tests. The rest of the test follows a similar pattern as for JUnit 4 tests. ```java @ExtendWith(PactConsumerTestExt.class) class ExampleJavaConsumerPactTest { ``` ### 2. create a method annotated with `@Pact` that returns the interactions for the test For each test (as with JUnit 4), you need to define a method annotated with the `@Pact` annotation that returns the interactions for the test. ```java @Pact(provider="test_provider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` ### 3. Link the mock server with the interactions for the test with `@PactTestFor` Then the final step is to use the `@PactTestFor` annotation to tell the Pact extension how to setup the Pact test. You can either put this annotation on the test class, or on the test method. For examples see [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) and [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy). The `@PactTestFor` annotation allows you to control the mock server in the same way as the JUnit 4 `PactProviderRule`. It allows you to set the hostname to bind to (default is `localhost`) and the port (default is to use a random port). You can also set the Pact specification version to use (default is V3). ```java @ExtendWith(PactConsumerTestExt.class) @PactTestFor(providerName = "ArticlesProvider", port = "1234") public class ExampleJavaConsumerPactTest { ``` **NOTE on the hostname**: The mock server runs in the same JVM as the test, so the only valid values for hostname are: | hostname | result | | -------- | ------ | | `localhost` | binds to the address that localhost points to (normally the loopback adapter) | | `127.0.0.1` or `::1` | binds to the loopback adapter | | host name | binds to the default interface that the host machines DNS name resolves to | | `0.0.0.0` or `::` | binds to the all interfaces on the host machine | #### Matching the interactions by provider name If you set the `providerName` on the `@PactTestFor` annotation, then the first method with a `@Pact` annotation with the same provider name will be used. See [ArticlesTest](src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) for an example. #### Matching the interactions by method name If you set the `pactMethod` on the `@PactTestFor` annotation, then the method with the provided name will be used (it still needs a `@Pact` annotation). See [MultiTest](src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy) for an example. ### Injecting the mock server into the test You can get the mock server injected into the test method by adding a `MockServer` parameter to the test method. ```java @Test void test(MockServer mockServer) { HttpResponse httpResponse = Request.Get(mockServer.getUrl() + "/articles.json").execute().returnResponse(); assertThat(httpResponse.getStatusLine().getStatusCode(), is(equalTo(200))); } ``` This helps with getting the base URL of the mock server, especially when a random port is used. ## Unsupported The current implementation does not support tests with multiple providers. This will be added in a later release. 4 21.8 KB 2018-06-17T16:12:52
au.com.dius pact-jvm-consumer-java8_2.11 # pact-jvm-consumer-java8 Provides a Java8 lambda based DSL for use with Junit to build consumer tests. # A Lambda DSL for Pact This is an extension for the pact DSL provided by [pact-jvm-consumer](../pact-jvm-consumer). The difference between the default pact DSL and this lambda DSL is, as the name suggests, the usage of lambdas. The use of lambdas makes the code much cleaner. ## Why a new DSL implementation? The lambda DSL solves the following two main issues. Both are visible in the following code sample: ```java new PactDslJsonArray() .array() # open an array .stringValue("a1") # choose the method that is valid for arrays .stringValue("a2") # choose the method that is valid for arrays .closeArray() # close the array .array() # open an array .numberValue(1) # choose the method that is valid for arrays .numberValue(2) # choose the method that is valid for arrays .closeArray() # close the array .array() # open an array .object() # now we work with an object .stringValue("foo", "Foo") # choose the method that is valid for objects .closeObject() # close the object and we're back in the array .closeArray() # close the array ``` ### The existing DSL is quite error-prone Methods may only be called in certain states. For example `object()` may only be called when you're currently working on an array whereas `object(name)` is only allowed to be called when working on an object. But both of the methods are available. You'll find out at runtime if you're using the correct method. Finally, the need for opening and closing objects and arrays makes usage cumbersome. The lambda DSL has no ambiguous methods and there's no need to close objects and arrays as all the work on such an object is wrapped in a lamda call. ### The existing DSL is hard to read When formatting your source code with an IDE the code becomes hard to read as there's no indentation possible. Of course, you could do it by hand but we want auto formatting! Auto formatting works great for the new DSL! ```java array.object((o) -> { o.stringValue("foo", "Foo"); # an attribute o.stringValue("bar", "Bar"); # an attribute o.object("tar", (tarObject) -> { # an attribute with a nested object tarObject.stringValue("a", "A"); # attribute of the nested object tarObject.stringValue("b", "B"); # attribute of the nested object }) }); ``` ## Installation ### Maven ``` <dependency> <groupId>au.com.dius</groupId> <artifactId>pact-jvm-consumer-java8</artifactId> <version>${pact.version}</version> </dependency> ``` ## Usage Start with a static import of `LambdaDsl`. This class contains factory methods for the lambda dsl extension. When you come accross the `body()` method of `PactDslWithProvider` builder start using the new extensions. The call to `LambdaDsl` replaces the call to instance `new PactDslJsonArray()` and `new PactDslJsonBody()` of the pact library. ```java io.pactfoundation.consumer.dsl.LambdaDsl.* ``` ### Response body as json array ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonArray; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonArray((a) -> { a.stringValue("a1"); a.stringValue("a2"); }).build()); ``` ### Response body as json object ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonBody; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build()); ``` ### Examples #### Simple Json object When creating simple json structures the difference between the two approaches isn't big. ##### JSON ```json { "bar": "Bar", "foo": "Foo" } ``` ##### Pact DSL ```java new PactDslJsonBody() .stringValue("foo", "Foo") .stringValue("bar", "Bar") ``` ##### Lambda DSL ```java newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build() ``` #### An array of arrays When we come to more complex constructs with arrays and nested objects the beauty of lambdas become visible! ##### JSON ```json [ ["a1", "a2"], [1, 2], [{"foo": "Foo"}] ] ``` ##### Pact DSL ```java new PactDslJsonArray() .array() .stringValue("a1") .stringValue("a2") .closeArray() .array() .numberValue(1) .numberValue(2) .closeArray() .array() .object() .stringValue("foo", "Foo") .closeObject() .closeArray() ``` ##### Lambda DSL ```java newJsonArray((rootArray) -> { rootArray.array((a) -> a.stringValue("a1").stringValue("a2")); rootArray.array((a) -> a.numberValue(1).numberValue(2)); rootArray.array((a) -> a.object((o) -> o.stringValue("foo", "Foo")); }).build() ``` 10 9.2 KB 2018-06-17T16:12:06
au.com.dius pact-jvm-consumer-groovy_2.11 pact-jvm-consumer-groovy ========================= Groovy DSL for Pact JVM ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer-groovy_2.11` * version-id = `3.5.x` ## Usage Add the `pact-jvm-consumer-groovy` library to your test class path. This provides a `PactBuilder` class for you to use to define your pacts. For a full example, have a look at the example JUnit `ExampleGroovyConsumerPactTest`. If you are using gradle for your build, add it to your `build.gradle`: dependencies { testCompile 'au.com.dius:pact-jvm-consumer-groovy_2.11:3.5.0' } Then create an instance of the `PactBuilder` in your test. ```groovy import au.com.dius.pact.consumer.PactVerificationResult import au.com.dius.pact.consumer.groovy.PactBuilder import groovyx.net.http.RESTClient import org.junit.Test class AliceServiceConsumerPactTest { @Test void "A service consumer side of a pact goes a little something like this"() { def alice_service = new PactBuilder() // Create a new PactBuilder alice_service { serviceConsumer "Consumer" // Define the service consumer by name hasPactWith "Alice Service" // Define the service provider that it has a pact with port 1234 // The port number for the service. It is optional, leave it out to // to use a random one given('there is some good mallory') // defines a provider state. It is optional. uponReceiving('a retrieve Mallory request') // upon_receiving starts a new interaction withAttributes(method: 'get', path: '/mallory') // define the request, a GET request to '/mallory' willRespondWith( // define the response we want returned status: 200, headers: ['Content-Type': 'text/html'], body: '"That is some good Mallory."' ) } // Execute the run method to have the mock server run. // It takes a closure to execute your requests and returns a PactVerificationResult. PactVerificationResult result = alice_service.runTest { def client = new RESTClient('http://localhost:1234/') def alice_response = client.get(path: '/mallory') assert alice_response.status == 200 assert alice_response.contentType == 'text/html' def data = alice_response.data.text() assert data == '"That is some good Mallory."' } assert result == PactVerificationResult.Ok.INSTANCE // This means it is all good } } ``` After running this test, the following pact file is produced: { "provider" : { "name" : "Alice Service" }, "consumer" : { "name" : "Consumer" }, "interactions" : [ { "provider_state" : "there is some good mallory", "description" : "a retrieve Mallory request", "request" : { "method" : "get", "path" : "/mallory", "requestMatchers" : { } }, "response" : { "status" : 200, "headers" : { "Content-Type" : "text/html" }, "body" : "That is some good Mallory.", "responseMatchers" : { } } } ] } ### DSL Methods #### serviceConsumer(String consumer) This names the service consumer for the pact. #### hasPactWith(String provider) This names the service provider for the pact. #### port(int port) Sets the port that the mock server will run on. If not supplied, a random port will be used. #### given(String providerState) Defines a state that the provider needs to be in for the request to succeed. For more info, see https://github.com/realestate-com-au/pact/wiki/Provider-states. Can be called multiple times. #### given(String providerState, Map params) Defines a state that the provider needs to be in for the request to succeed. For more info, see https://github.com/realestate-com-au/pact/wiki/Provider-states. Can be called multiple times, and the params map can contain the data required for the state. #### uponReceiving(String requestDescription) Starts the definition of a of a pact interaction. #### withAttributes(Map requestData) Defines the request for the interaction. The request data map can contain the following: | key | Description | Default Value | |----------------------------|-------------------------------------------|-----------------------------| | method | The HTTP method to use | get | | path | The Path for the request | / | | query | Query parameters as a Map<String, List> | | | headers | Map of key-value pairs for the request headers | | | body | The body of the request. If it is not a string, it will be converted to JSON. Also accepts a PactBodyBuilder. | | | prettyPrint | Boolean value to control if the body is pretty printed. See note on Pretty Printed Bodies below | For the path, header attributes and query parameters (version 2.2.2+ for headers, 3.3.7+ for query parameters), you can use regular expressions to match. You can either provide a regex `Pattern` class or use the `regexp` method to construct a `RegexpMatcher` (you can use any of the defined matcher methods, see DSL methods below). If you use a `Pattern`, or the `regexp` method but don't provide a value, a random one will be generated from the regular expression. This value is used when generating requests. For example: ```groovy .withAttributes(path: ~'/transaction/[0-9]+') // This will generate a random path for requests // or .withAttributes(path: regexp('/transaction/[0-9]+', '/transaction/1234567890')) ``` #### withBody(Closure closure) Constructs the body of the request or response by invoking the supplied closure in the context of a PactBodyBuilder. ##### Pretty Printed Bodies [Version 2.2.15+, 3.0.4+] An optional Map can be supplied to control how the body is generated. The option values are available: | Option | Description | |--------|-------------| | mimeType | The mime type of the body. Defaults to `application/json` | | prettyPrint | Boolean value controlling whether to pretty-print the body or not. Defaults to true | If the prettyPrint option is not specified, the bodies will be pretty printed unless the mime type corresponds to one that requires compact bodies. Currently only `application/x-thrift+json` is classed as requiring a compact body. For an example of turning off pretty printing: ```groovy service { uponReceiving('a request') withAttributes(method: 'get', path: '/') withBody(prettyPrint: false) { name 'harry' surname 'larry' } } ``` #### willRespondWith(Map responseData) Defines the response for the interaction. The response data map can contain the following: | key | Description | Default Value | |----------------------------|-------------------------------------------|-----------------------------| | status | The HTTP status code to return | 200 | | headers | Map of key-value pairs for the response headers | | | body | The body of the response. If it is not a string, it will be converted to JSON. Also accepts a PactBodyBuilder. | | | prettyPrint | Boolean value to control if the body is pretty printed. See note on Pretty Printed Bodies above | For the headers (version 2.2.2+), you can use regular expressions to match. You can either provide a regex `Pattern` class or use the `regexp` method to construct a `RegexpMatcher` (you can use any of the defined matcher methods, see DSL methods below). If you use a `Pattern`, or the `regexp` method but don't provide a value, a random one will be generated from the regular expression. This value is used when generating responses. For example: ```groovy .willRespondWith(headers: [LOCATION: ~'/transaction/[0-9]+']) // This will generate a random location value // or .willRespondWith(headers: [LOCATION: regexp('/transaction/[0-9]+', '/transaction/1234567890')]) ``` #### PactVerificationResult runTest(Closure closure) The `runTest` method starts the mock server, and then executes the provided closure. It then returns the pact verification result for the pact run. If you require access to the mock server configuration for the URL, it is passed into the closure, e.g., ```groovy PactVerificationResult result = alice_service.runTest() { mockServer -> def client = new RESTClient(mockServer.url) def alice_response = client.get(path: '/mallory') } ``` ### 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). ### Body DSL For building JSON bodies there is a `PactBodyBuilder` that provides as DSL that includes matching with regular expressions and by types. For a more complete example look at `PactBodyBuilderTest`. For an example: ```groovy service { uponReceiving('a request') withAttributes(method: 'get', path: '/') withBody { name(~/\w+/, 'harry') surname regexp(~/\w+/, 'larry') position regexp(~/staff|contractor/, 'staff') happy(true) } } ``` This will return the following body: ```json { "name": "harry", "surname": "larry", "position": "staff", "happy": true } ``` and add the following matchers: ```json { "$.body.name": {"regex": "\\w+"}, "$.body.surname": {"regex": "\\w+"}, "$.body.position": {"regex": "staff|contractor"} } ``` #### DSL Methods The DSL supports the following matching methods: * regexp(Pattern re, String value = null), regexp(String regexp, String value = null) Defines a regular expression matcher. If the value is not provided, a random one will be generated. * hexValue(String value = null) Defines a matcher that accepts hexidecimal values. If the value is not provided, a random hexidcimal value will be generated. * identifier(def value = null) Defines a matcher that accepts integer values. If the value is not provided, a random value will be generated. * ipAddress(String value = null) Defines a matcher that accepts IP addresses. If the value is not provided, a 127.0.0.1 will be used. * numeric(Number value = null) Defines a matcher that accepts any numerical values. If the value is not provided, a random integer will be used. * integer(def value = null) Defines a matcher that accepts any integer values. If the value is not provided, a random integer will be used. * decimal(def value = null) Defines a matcher that accepts any decimal numbers. If the value is not provided, a random decimal will be used. * timestamp(String pattern = null, def value = null) If pattern is not provided the ISO_DATETIME_FORMAT is used ("yyyy-MM-dd'T'HH:mm:ss") . If the value is not provided, the current date and time is used. * time(String pattern = null, def value = null) If pattern is not provided the ISO_TIME_FORMAT is used ("'T'HH:mm:ss") . If the value is not provided, the current date and time is used. * date(String pattern = null, def value = null) If pattern is not provided the ISO_DATE_FORMAT is used ("yyyy-MM-dd") . If the value is not provided, the current date and time is used. * uuid(String value = null) Defines a matcher that accepts UUIDs. A random one will be generated if no value is provided. * equalTo(def value) Defines an equality matcher that always matches the provided value using `equals`. This is useful for resetting cascading type matchers. * includesStr(def value) Defines a matcher that accepts any value where its string form includes the provided string. * nullValue() Defines a matcher that accepts only null values. * url(String basePath, Object... pathFragments) 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. For example: ```groovy url('http://localhost:8080', 'pacticipants', regexp('[^\\/]+', 'Activity%20Service')) ``` Defines a matcher that accepts only null values. #### What if a field matches a matcher name in the DSL? When using the body DSL, if there is a field that matches a matcher name (e.g. a field named 'date') then you can do the following: ```groovy withBody { date = date() } ``` ### 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 `eachLike`, `minLike` and `maxLike` functions. | function | description | |----------|-------------| | `eachLike()` | Ensure that each item in the list matches the provided example | | `maxLike(integer max)` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `minLike(integer min)` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```groovy withBody { users minLike(1) { id identifier name string('Fred') } } ``` This will ensure that the user 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. ```groovy withBody { users minLike(1, 3) { id identifier name string('Fred') } } ``` This will create an example user list with 3 users. __Version 3.2.13/2.4.14+__ The each like matchers have been updated to work with primitive types. ```groovy withBody { permissions eachLike(3, 'GRANT') } ``` will generate the following JSON ```json { "permissions": ["GRANT", "GRANT", "GRANT"] } ``` and matchers ```json { "$.body.permissions": {"match": "type"} } ``` and now you can even get more fancy ```groovy withBody { permissions eachLike(3, regexp(~/\w+/)) permissions2 minLike(2, 3, integer()) permissions3 maxLike(4, 3, ~/\d+/) } ``` You can also match arrays at the root level, for instance, ```groovy withBody PactBodyBuilder.eachLike(regexp(~/\w+/)) ``` or if you have arrays of arrays ```groovy withBody PactBodyBuilder.eachLike([ regexp('[0-9a-f]{8}', 'e8cda07e'), regexp(~/\w+/, 'sony') ]) ``` __Version 3.5.9+__ A `eachArrayLike` method has been added to handle matching of arrays of arrays. ```groovy { answers minLike(1) { questionId string("books") answer eachArrayLike { questionId string("title") answer string("BBBB") } } ``` This will generate an array of arrays for the `answer` attribute. ### 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 `keyLike` method, which takes an example key as a parameter. For example: ```groovy withBody { example { one { keyLike '001', 'value' // key like an id mapped to a value } two { keyLike 'ABC001', regexp('\\w+') // key like an id mapped to a matcher } three { keyLike 'XYZ001', { // key like an id mapped to a closure id identifier() } } four { keyLike '001XYZ', eachLike { // key like an id mapped to an array where each item is matched by the following id identifier() // example } } } } ``` For an example, have a look at [WildcardPactSpec](src/test/au/com/dius/pact/consumer/groovy/WildcardPactSpec.groovy). **NOTE:** The `keyLike` 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 `keyLike` condition applied to a map will result in only one being applied when the pact is verified (probably the last). ### Matching with an OR (3.5.0+) The V3 spec allows multiple matchers to be combined using either AND or OR for a value. The main use of this would be to either be able to match a value or a null, or to combine different matchers. For example: ```groovy withBody { valueA and('AB', includeStr('A'), includeStr('B')) // valueA must include both A and B valueB or('100', regex(~/\d+/), nullValue()) // valueB must either match a regular expression or be null valueC or('12345678', regex(~/\d{8}/), regex(~/X\d{13}/)) // valueC must match either 8 or X followed by 13 digits } ``` ## Changing the directory pact files are written to (2.1.9+) By default, pact files are written to `target/pacts`, but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/pacts" } ``` # 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 V3 spec pact files (3.1.0+, 2.3.0+) To have your consumer tests generate V3 format pacts, you can pass an option into the `runTest` method. For example: ```groovy PactVerificationResult result = service.runTest(specificationVersion: PactSpecVersion.V3) { config -> def client = new RESTClient(config.url) def response = client.get(path: '/') } ``` ## Consumer test for a message consumer For testing a consumer of messages from a message queue, the `PactMessageBuilder` class provides a DSL for defining your message expectations. It works in much the same way as the `PactBuilder` class for Request-Response interactions, but will generate a V3 format message pact file. The following steps demonstrate how to use it. ### Step 1 - define the message expectations Create a test that uses the `PactMessageBuilder` to define a message expectation, and then call `run`. This will invoke the given closure with a message for each one defined in the pact. ```groovy def eventStream = new PactMessageBuilder().call { serviceConsumer 'messageConsumer' hasPactWith 'messageProducer' given 'order with id 10000004 exists' expectsToReceive 'an order confirmation message' withMetaData(type: 'OrderConfirmed') // Can define any key-value pairs here withContent(contentType: 'application/json') { type 'OrderConfirmed' audit { userCode 'messageService' } origin 'message-service' referenceId '10000004-2' timeSent: '2015-07-22T10:14:28+00:00' value { orderId '10000004' value '10.000000' fee '10.00' gst '15.00' } } } ``` ### Step 2 - call your message handler with the generated messages This example tests a message handler that gets messages from a Kafka topic. In this case the Pact message is wrapped as a Kafka `MessageAndMetadata`. ```groovy eventStream.run { Message message -> messageHandler.handleMessage(new MessageAndMetadata('topic', 1, new kafka.message.Message(message.contentsAsBytes()), 0, null, valueDecoder)) } ``` ### Step 3 - validate that the message was handled correctly ```groovy def order = orderRepository.getOrder('10000004') assert order.status == 'confirmed' assert order.value == 10.0 ``` ### Step 4 - Publish the pact file If the test was successful, a pact file would have been produced with the message from step 1. 134 76.1 KB 2018-06-17T16:11:10
org.codelibs elasticsearch-analysis-ja This plugin provides an analysis library for Japanese. 29 4.5 MB 2018-06-17T15:46:10
org.codelibs elasticsearch-analysis-fess This plugin provides an analysis library for Fess. 21 26.9 KB 2018-06-17T15:35:04
com.nepxion eventbus-aop Nepxion EventBus is a generic event dispatching component based on Google Guava with Nepxion Matrix AOP framework 6 26.8 KB 2018-06-17T15:25:06
com.nepxion eventbus Nepxion EventBus is a generic event dispatching component based on Google Guava with Nepxion Matrix AOP framework 6 7.2 KB 2018-06-17T15:25:02
au.com.dius pact-specification-test_2.12 Pact Specification ================== The [Pact Specification](https://github.com/bethesque/pact_specification) is a robust set of tests on the pact matching code aimed at ensuring pact library implementations across different languages have the same matching behaviour. Without adhering to these specifications there would be room for subtle issues to arise between consumers and providers using different libraries. 16 210.9 KB 2018-06-17T15:16:46
com.mikepenz fastadapter-commons Commons extension for the FastAdapter library. The bullet proof, fast and easy to use adapter library. 23 26.7 KB 2018-06-17T15:16:41
org.langrid jp.go.nict.langrid.servicecontainer Service container including JSON-RPC handler for the Service Grid Server Software and java web services. 11 171.8 KB 2018-06-17T15:15:29
org.langrid jp.go.nict.langrid.client.axis Client library including SOAP client based on Apache Axis for the Service Grid Server Software and java web services. 10 23.3 KB 2018-06-17T15:15:26
org.langrid jp.go.nict.langrid.client.soap SOAP Client library for the Service Grid Server Software and java web services. 11 36.4 KB 2018-06-17T15:15:14
org.langrid jp.go.nict.langrid.service.management_1_2 Management Service Interface Definitionsfor Service Grid Server Software and java web services. 10 115.8 KB 2018-06-17T15:14:52
com.mikepenz fastadapter-extensions Commons extension for the FastAdapter library. The bullet proof, fast and easy to use adapter library. 48 86.9 KB 2018-06-17T15:14:45
org.langrid jp.go.nict.langrid.language Language Code Libraries for RFC3066, ISO3166, ISO639 and IANA Language Tags. 11 101.8 KB 2018-06-17T15:14:24
org.langrid jp.go.nict.langrid.service.language_1_2 Language Service Interface Definitionsfor Service Grid Server Software and java web services. 11 155.6 KB 2018-06-17T15:14:20
au.com.dius pact-jvm-server_2.12 Pact server =========== The pact server is a stand-alone interactions recorder and verifier, aimed at clients that are non-JVM or non-Ruby based. The pact client for that platform will need to be implemented, but it only be responsible for generating the `JSON` interactions, running the tests and communicating with the server. The server implements a `JSON` `REST` Admin API with the following endpoints. / -> For diagnostics, currently returns a list of ports of the running mock servers. /create -> For initialising a test server and submitting the JSON interactions. It returns a port /complete -> For finalising and verifying the interactions with the server. It writes the `JSON` pact file to disk. ## Running the server ### Versions 2.2.6+ Pact server takes the following parameters: ``` Usage: pact-jvm-server [options] [port] port port to run on (defaults to 29999) --help prints this usage text -h <value> | --host <value> host to bind to (defaults to localhost) -l <value> | --mock-port-lower <value> lower bound to allocate mock ports (defaults to 20000) -u <value> | --mock-port-upper <value> upper bound to allocate mock ports (defaults to 40000) -d | --daemon run as a daemon process -v <value> | --pact-version <value> pact version to generate for (2 or 3) -k <value> | --keystore-path <value> Path to keystore -p <value> | --keystore-password <value> Keystore password -s <value> | --ssl-port <value> Ssl port the mock server should run on. lower and upper bounds are ignored --debug run with debug logging ``` ### Using trust store 3.4.0+ Trust store can be used. However, it is limited to a single port for the time being. ### Prior to version 2.2.6 Pact server takes one optional parameter, the port number to listen on. If not provided, it will listen on 29999. It requires an active console to run. ### Using a distribution archive You can download a [distribution from maven central](http://search.maven.org/remotecontent?filepath=au/com/dius/pact-jvm-server_2.11/2.2.4/). There is both a ZIP and TAR archive. Unpack it to a directory of choice and then run the script in the bin directory. ### Building a distribution bundle You can build an application bundle with gradle by running (for 2.11 version): $ ./gradlew :pact-jvm-server_2.11:installdist This will create an app bundle in `build/2.11/install/pact-jvm-server_2.11`. You can then execute it with: $ java -jar pact-jvm-server/build/2.10/install/pact-jvm-server_2.11/lib/pact-jvm-server_2.11-3.2.11.jar or with the generated bundle script file: $ pact-jvm-server/build/2.11/install/pact-jvm-server_2.11/bin/pact-jvm-server_2.11 By default will run on port `29999` but a port number can be optionally supplied. ### Running it with docker You can use a docker image to execute the mock server as a docker container. $ docker run -d -p 8080:8080 -p 20000-20010:20000-20010 uglyog/pact-jvm-server This will run the main server on port 8080, and each created mock server on ports 20000-20010. You can map the ports to any you require. ## Life cycle The following actions are expected to occur * The client calls `/create` to initialise a server with the expected `JSON` interactions and state * The admin server will start a mock server on a random port and return the port number in the response * The client will execute its interaction tests against the mock server with the supplied port * Once finished, the client will call `/complete' on the Admin API, posting the port number * The pact server will verify the interactions and write the `JSON` `pact` file to disk under `/target` * The mock server running on the supplied port will be shutdown. ## Endpoints ### /create The client will need `POST` to `/create` the generated `JSON` interactions, also providing a state as a query parameter and a path. For example: POST http://localhost:29999/create?state=NoUsers&path=/sub/ref/path '{ "provider": { "name": "Animal_Service"}, ... }' This will create a new running mock service provider on a randomly generated port. The port will be returned in the `201` response: { "port" : 34423 } But you can also reference the path from `/sub/ref/path` using the server port. The service will not strip the prefix path, but instead will use it as a differentiator. If your services do not have differences in the prefix of their path, then you will have to use the port method. ### /complete Once the client has finished running its tests against the mock server on the supplied port (in this example port `34423`) the client will need to `POST` to `/complete` the port number of the mock server that was used. For example: POST http://localhost:29999/complete '{ "port" : 34423 }' This will cause the Pact server to verify the interactions, shutdown the mock server running on that port and writing the pact `JSON` file to disk under the `target` directory. ### / The `/` endpoint is for diagnostics and to check that the pact server is running. It will return all the currently running mock servers port numbers. For example: GET http://localhost:29999/ '{ "ports": [23443,43232] }' 16 28.8 MB 2018-06-17T15:14:17
org.langrid jp.go.nict.langrid.client.protobufrpc Client library for ProtocolBuffers RPC. 10 8.5 KB 2018-06-17T15:14:14
org.langrid jp.go.nict.langrid.commons Common and utility library for the Service Grid Server Software and java web services. 11 534.9 KB 2018-06-17T15:14:11
org.langrid jp.go.nict.langrid.client.ws_1_2 Client library for SOAP including stub codes generated by Apache Axis for the Service Grid Server Software and java web services. 10 653.8 KB 2018-06-17T15:13:48
org.langrid jp.go.nict.langrid.commons.protobufrpc Common and utility library about ProtocolBuffers RPC for the Service Grid Server Software and java web services. 10 38.0 KB 2018-06-17T15:13:23
org.langrid jp.go.nict.langrid.composite.common Common classes for Composite services. 1 12.7 KB 2018-06-17T15:13:01
org.langrid jp.go.nict.langrid.client Client library including JSON-RPC client for the Service Grid Server Software and java web services. 11 18.9 KB 2018-06-17T15:12:50
org.langrid jp.go.nict.langrid.service.common_1_2 Common Service Interface definitions for the Service Grid Server Software and java web services. 11 19.4 KB 2018-06-17T15:12:45

‹‹   1   2   3   4   5   6   7   8   9   10   ››