Java библиотеки

lein

au.com.dius.pact.provider : lein

# Leiningen plugin to verify a provider Leiningen plugin for verifying pacts against a provider. The plugin provides a `pact-verify` task which will verify all configured pacts against your provider. ## To Use It ### 1. Add the plugin to your project plugins, preferably in it's own profile. ```clojure :profiles { :pact { :plugins [[au.com.dius.pact.provider/lein "4.1.20" :exclusions [commons-logging]]] :dependencies [[ch.qos.logback/logback-core "1.2.3"] [ch.qos.logback/logback-classic "1.2.3"]] }} ``` ### 2. Define the pacts between your consumers and providers You define all the providers and consumers within the `:pact` configuration element of your project. ```clojure :pact { :service-providers { ; 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 "/" :has-pact-with { ; Again, you can define as many consumers for each provider as you need, but each must have a unique name :consumer1 { ; pact file can be either a path or an URL :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` ### 3. Execute `lein with-profile pact pact-verify` You will have to have your provider running for this to pass. ## Enabling insecure SSL 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. ```clojure :pact { :service-providers { :provider1 { :protocol "https" :host "localhost" :port 8443 :insecure true :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` ## Specifying a custom trust store For environments that are running their own certificate chains: ```clojure :pact { :service-providers { :provider1 { :protocol "https" :host "localhost" :port 8443 :trust-store "relative/path/to/trustStore.jks" :trust-store-password "changeme" :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` `:trust-store` is relative to the current working (build) directory. `:trust-store-password` defaults to `changeit`. NOTE: The hostname will still be verified against the certificate. ## Modifying the requests before they are sent 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 Leiningen plugin provides a request filter that can be set to an anonymous function on the provider that will be called before the request is made. This function will receive the HttpRequest object as a parameter. ```clojure :pact { :service-providers { :provider1 { ; function that adds an Authorization header to each request :request-filter #(.addHeader % "Authorization" "oauth-token eyJhbGciOiJSUzI1NiIsIm...") :has-pact-with { :consumer1 { :pact-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! ## Modifying the HTTP Client Used 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 function assigned to `:create-client` on the provider that returns a `CloseableHttpClient`. The function will receive the provider info as a parameter. ## Turning off URL decoding of the paths in the pact file 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. ## Plugin Properties The following plugin options can be specified 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| |: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'| Example, to run verification only for a particular consumer: ``` $ lein with-profile pact pact-verify :pact.filter.consumers=:consumer2 ``` ## Provider States 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 from the pact file before each interaction via a POST. The `:state-change-uses-body` controls if the state is passed in the request body or as a query parameter. These values can be set at the provider level, or for a specific consumer. Consumer values take precedent if both are given. ```clojure :pact { :service-providers { :provider1 { :state-change-url "http://localhost:8080/tasks/pactStateChange" :state-change-uses-body false ; defaults to true :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` If the `:state-change-uses-body` is not specified, or is set to true, then the provider state description will be sent as JSON in the body of the request. If it is set to false, it will passed as a query parameter. As for normal requests (see Modifying the requests before they are sent), a state change request can be modified before it is sent. Set `:state-change-request-filter` to an anonymous function on the provider that will be called before the request is made. #### Returning values that can be injected You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. There are methods on the consumer DSLs that can provider an expression that contains variables (like '/api/user/au.com.dius.pact.provider:lein:jar:4.4.0-beta.2' for the path). The provider state callback can then return a map for values, and the `id` attribute from the map will be expanded in the expression. For URL callbacks, the values need to be returned as JSON in the response body. ## Filtering the interactions that are verified You can filter the interactions that are run using three properties: `:pact.filter.consumers`, `:pact.filter.description` and `:pact.filter.providerState`. Adding `:pact.filter.consumers=:consumer1,:consumer2` to the command line will only run the pact files for those consumers (consumer1 and consumer2). Adding `:pact.filter.description=a request for payment.*` will only run those interactions whose descriptions start with 'a request for payment'. `:pact.filter.providerState=.*payment` will match any interaction that has a provider state that ends with payment, and `:pact.filter.providerState=` will match any interaction that does not have a provider state. ## Starting and shutting down your provider For the pact verification to run, the provider needs to be running. Leiningen provides a `do` task that can chain tasks together. So, by creating a `start-app` and `terminate-app` alias, you could so something like: $ lein with-profile pact do start-app, pact-verify, terminate-app However, if the pact verification fails the build will abort without running the `terminate-app` task. To have the start and terminate tasks always run regardless of the state of the verification, you can assign them to `:start-provider-task` and `:terminate-provider-task` on the provider. ```clojure :aliases {"start-app" ^{:doc "Starts the app"} ["tasks to start app ..."] ; insert tasks to start the app here "terminate-app" ^{:doc "Kills the app"} ["tasks to terminate app ..."] ; insert tasks to stop the app here } :pact { :service-providers { :provider1 { :start-provider-task "start-app" :terminate-provider-task "terminate-app" :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` Then you can just run: $ lein with-profile pact pact-verify and the `start-app` and `terminate-app` tasks will run before and after the provider verification. ## Specifying the provider hostname at runtime If you need to calculate the provider hostname at runtime (for instance it is run as a new docker container or AWS instance), you can give an anonymous function as the provider host that returns the host name. The function will receive the provider information as a parameter. ```clojure :pact { :service-providers { :provider1 { :host #(calculate-host-name %) :has-pact-with { :consumer1 { :pact-file "path/to/provider1-consumer1-pact.json" } } } } } ``` # Verifying V4 Pact files that require plugins (version 4.3.0+) Pact files that require plugins can be verified with version 4.3.0+. For details on how plugins work, see the [Pact plugin project](https://github.com/pact-foundation/pact-plugins). Each required plugin is defined in the `plugins` section in the Pact metadata in the Pact file. The plugins will be loaded from the plugin directory. By default, this is `~/.pact/plugins` or the value of the `PACT_PLUGIN_DIR` environment variable. Each plugin required by the Pact file must be installed there. You will need to follow the installation instructions for each plugin, but the default is to unpack the plugin into a sub-directory `<plugin-name>-<plugin-version>` (i.e., for the Protobuf plugin 0.0.0 it will be `protobuf-0.0.0`). The plugin manifest file must be present for the plugin to be able to be loaded. # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

typeson

org.webjars.npm : typeson

WebJar for typeson

Последняя версия: 6.1.0

Дата: 27 апр. 2022 г.

junit5spring

au.com.dius.pact.provider : junit5spring

# Pact Spring/JUnit5 Support This module extends the base [Pact JUnit5 module](/provider/junit5/README.md). See that for more details. ## Dependency The combined library (JUnit5 + Spring) is available on maven central using: group-id = au.com.dius.pact.provider artifact-id = junit5spring version-id = 4.2.x ## Usage For writing Spring Pact verification tests with JUnit 5, there is an JUnit 5 Invocation Context Provider that you can use with the `@TestTemplate` annotation. This will generate a test for each interaction found for the pact files for the provider. To use it, add the `@Provider` and `@ExtendWith(SpringExtension.class)` and one of the pact source annotations to your test class (as per a JUnit 5 test), then add a method annotated with `@TestTemplate` and `@ExtendWith(PactVerificationSpringProvider.class)` that takes a `PactVerificationContext` parameter. You will need to call `verifyInteraction()` on the context parameter in your test template method. For example: ```java @ExtendWith(SpringExtension.class) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT) @Provider("Animal Profile Service") @PactBroker public class ContractVerificationTest { @TestTemplate @ExtendWith(PactVerificationSpringProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } } ``` You will now be able to setup all the required properties using the Spring context, e.g. creating an application YAML file in the test resources: ```yaml pactbroker: host: your.broker.host auth: username: broker-user password: broker.password ``` You can also run pact tests against `MockMvc` without need to spin up the whole application context which takes time and often requires more additional setup (e.g. database). In order to run lightweight tests just use `@WebMvcTest` from Spring and `MockMvcTestTarget` as a test target before each test. For example: ```java @WebMvcTest @Provider("myAwesomeService") @PactBroker class ContractVerificationTest { @Autowired private MockMvc mockMvc; @TestTemplate @ExtendWith(PactVerificationSpringProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } @BeforeEach void before(PactVerificationContext context) { context.setTarget(new MockMvcTestTarget(mockMvc)); } } ``` You can also use `MockMvcTestTarget` for tests without spring context by providing the controllers manually. For example: ```java @Provider("myAwesomeService") @PactFolder("pacts") class MockMvcTestTargetStandaloneMockMvcTestJava { @TestTemplate @ExtendWith(PactVerificationSpringProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } @BeforeEach void before(PactVerificationContext context) { MockMvcTestTarget testTarget = new MockMvcTestTarget(); testTarget.setControllers(new DataResource()); context.setTarget(testTarget); } @RestController static class DataResource { @GetMapping("/data") @ResponseStatus(HttpStatus.NO_CONTENT) void getData(@RequestParam("ticketId") String ticketId) { } } } ``` **Important:** Since `@WebMvcTest` starts only Spring MVC components you can't use `PactVerificationSpringProvider` and need to fallback to `PactVerificationInvocationContextProvider` ## Webflux tests You can test Webflux routing functions using the `WebFluxTarget` target class. The easiest way to do it is to get Spring to autowire your handler and router into the test and then pass the routing function to the target. For example: ```java @Autowired YourRouter router; @Autowired YourHandler handler; @BeforeEach void setup(PactVerificationContext context) { context.setTarget(new WebFluxTarget(router.route(handler))); } @TestTemplate @ExtendWith(PactVerificationSpringProvider.class) void pactVerificationTestTemplate(PactVerificationContext context) { context.verifyInteraction(); } ``` ## Modifying requests As documented in [Pact JUnit5 module](/provider/junit5/README.md#modifying-the-requests-before-they-are-sent), you can inject a request object to modify the requests made. However, depending on the Pact test target you are using, you need to use a different class. | Test Target | Class to use | |-------------|--------------| | HttpTarget, HttpsTarget, SpringBootHttpTarget | org.apache.http.HttpRequest | | MockMvcTestTarget | MockHttpServletRequestBuilder | | WebFluxTarget | WebTestClient.RequestHeadersSpec | # Verifying V4 Pact files that require plugins (version 4.3.0+) Pact files that require plugins can be verified with version 4.3.0+. For details on how plugins work, see the [Pact plugin project](https://github.com/pact-foundation/pact-plugins). Each required plugin is defined in the `plugins` section in the Pact metadata in the Pact file. The plugins will be loaded from the plugin directory. By default, this is `~/.pact/plugins` or the value of the `PACT_PLUGIN_DIR` environment variable. Each plugin required by the Pact file must be installed there. You will need to follow the installation instructions for each plugin, but the default is to unpack the plugin into a sub-directory `<plugin-name>-<plugin-version>` (i.e., for the Protobuf plugin 0.0.0 it will be `protobuf-0.0.0`). The plugin manifest file must be present for the plugin to be able to be loaded. # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

junit5

au.com.dius.pact.provider : junit5

# Pact Junit 5 Extension ## Dependency The library is available on maven central using: * group-id = `au.com.dius.pact.provider` * artifact-id = `junit5` * version-id = `4.1.x` ## 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](../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 `MessageTestTarget`. For example: ```java @BeforeEach void before(PactVerificationContext context) { context.setTarget(HttpTestTarget.fromUrl(new URL(myProviderUrl))); // or something like // context.setTarget(new HttpTestTarget("localhost", myProviderPort, "/")); } ``` ### HttpTestTarget `HttpTestTarget` accepts the following options: | Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | host | String | localhost | The hostname to use to access the provider | | port | Int | 8080 | The port the provider is running on | | path | String | "/" | The base path the provider is mounted on | | httpClientFactory | () -> IHttpClientFactory | Default Factory | Callback used to override the HTTP client factory | ### HttpsTestTarget `HttpsTestTarget` accepts the following options: | Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | host | String | localhost | The hostname to use to access the provider | | port | Int | 8443 | The port the provider is running on | | path | String | "/" | The base path the provider is mounted on | | insecure | Boolean | false | Disables the standard TLS verification used with HTTPS connections | | httpClientFactory | () -> IHttpClientFactory | Default Factory | Callback used to override the HTTP client factory | ### MessageTestTarget `MessageTestTarget` accepts the following options: | Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | packagesToScan | List<String> | empty List | The Java packages to scan to find classes with annotated methods. If your methods are on your test class, you don't need to supply a value for this. | | classLoader | ClassLoader? | null | Class loader to use to load the classes with annotated methods | ## !! Important note for Maven users !! If you use Maven to run your tests, you will have to make sure that the Maven Surefire plugin is at least version 2.22.1 and configured to use an isolated classpath. For example, configure it by adding the following to your POM: ```xml <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.22.1</version> <configuration> <useSystemClassLoader>false</useSystemClassLoader> </configuration> </plugin> ``` ### IMPORTANT NOTE!!!: JVM system properties needs to be set on the test JVM if your build is running with Gradle or Maven. Gradle and Maven do not pass in the system properties in to the test JVM from the command line. The system properties specified on the command line only control the build JVM (the one that runs Gradle or Maven), but the tests will run in a new JVM. See [Maven Surefire Using System Properties](https://maven.apache.org/surefire/maven-surefire-plugin/examples/system-properties.html) and [Gradle Test docs](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.testing.Test.html#org.gradle.api.tasks.testing.Test:systemProperties). ### For Message Tests and Spring and Maven If you are using Spring (or Springboot), and want to have values injected into your test, you need to ensure that the same class loader is used to execute your annotated test method as Spring is using to inject the values. In particular, options like the Maven Surefire plugin's `forkCount == 0` can impact this. Either don't supply any packages to scan (this will use the default class loader and the annotated methods **have** to be on your test class), or you can provide the classloader to use as the second parameter to `MessageTestTarget`. ## Provider State Methods Provider State Methods work in the same way as with JUnit 4 tests, refer to the [Pact junit runner](../junit/README.md) docs. ### Using multiple classes for the state change methods If you have a large number of state change methods, you can split things up by moving them to other classes. You will need to specify the additional classes on the test context in a `Before` method. Do this with the `withStateHandler` or `setStateHandlers` methods. See [StateAnnotationsOnAdditionalClassTest](https://github.com/DiUS/pact-jvm/blob/master/provider/junit5/src/test/java/au/com/dius/pact/provider/junit5/StateAnnotationsOnAdditionalClassTest.java) for an example. ## 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! **NOTE: JUnit 5 tests do not use `@TargetRequestFilter`** 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 (of type `org.apache.http.HttpRequest` for versions 4.2.x and before, `org.apache.hc.core5.http.HttpRequest` for versions 4.3.0+). 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 | ## Allowing the test to pass when no pacts are found to verify (version 4.0.7+) By default, the test will fail with an exception if no pacts were found to verify. This can be overridden by adding the `@IgnoreNoPactsToVerify` annotation to the test class. For this to work, you test class will need to be able to receive null values for any of the injected parameters. ## Overriding the handling of a body data type **NOTE: version 4.1.3+** By default, bodies will be handled based on their content types. For binary contents, the bodies will be base64 encoded when written to the Pact file and then decoded again when the file is loaded. You can change this with an override property: `pact.content_type.override.<TYPE>.<SUBTYPE>=text|json|binary`. For instance, setting `pact.content_type.override.application.pdf=text` will treat PDF bodies as a text type and not encode/decode them. ### Controlling the generation of diffs **NOTE: version 4.2.7+** When there are mismatches with large bodies the calculation of the diff can take a long time . You can turn off the generation of the diffs with the JVM system property: `pact.verifier.generateDiff=true|false|<dataSize>`, where `dataSize`, if specified, must be a valid data size (for instance `100kb` or `1mb`). This will turn off the diff calculation for payloads that exceed this size. For instance, setting `pact.verifier.generateDiff=false` will turn off the generation of diffs for all bodies, while `pact.verifier.generateDiff=512kb` will only turn off the diffs if the actual or expected body is larger than 512kb. # Publishing verification results to a Pact Broker 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. You need to set the version of the provider that is verified using the `pact.provider.version` system property. To enable publishing of results, set the Java system property or environment variable `pact.verifier.publishResults` to `true`. ### IMPORTANT NOTE!!!: this property needs to be set on the test JVM if your build is running with Gradle or Maven. Gradle and Maven do not pass in the system properties in to the test JVM from the command line. The system properties specified on the command line only control the build JVM (the one that runs Gradle or Maven), but the tests will run in a new JVM. See [Maven Surefire Using System Properties](https://maven.apache.org/surefire/maven-surefire-plugin/examples/system-properties.html) and [Gradle Test docs](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.testing.Test.html#org.gradle.api.tasks.testing.Test:systemProperties). ## Tagging the provider before verification results are published [4.0.1+] You can have a tag pushed against the provider version before the verification results are published. To do this you need set the `pact.provider.tag` JVM system property to the tag value. From 4.1.8+, you can specify multiple tags with a comma separated string for the `pact.provider.tag` system property. ## Setting the provider branch before verification results are published [4.3.0-beta.7+] Pact Broker version 2.86.0 or later You can have a branch pushed against the provider version before the verification results are published. To do this you need set the `pact.provider.branch` JVM system property to the branch value. ## Setting the build URL for verification results [4.3.2+] You can specify a URL to link to your CI build output. To do this you need to set the `pact.verifier.buildUrl` JVM system property to the URL value. # Pending Pact Support (version 4.1.0 and later) If your Pact broker supports pending pacts, you can enable support for that by enabling that on your Pact broker annotation or with JVM system properties. You also need to provide the tags that will be published with your provider's verification results. The broker will then label any pacts found that don't have a successful verification result as pending. That way, if they fail verification, the verifier will ignore those failures and not fail the build. For example, with annotation: ```java @Provider("Activity Service") @PactBroker(host = "test.pactflow.io", tags = {"test"}, scheme = "https", enablePendingPacts = "true", providerTags = "master" ) public class PactJUnitTest { ``` You can also use the `pactbroker.enablePending` and `pactbroker.providerTags` JVM system properties. Then any pending pacts will not cause a build failure. # Work In Progress (WIP) Pact Support (version 4.1.5 and later) WIP pacts work in the same way as with JUnit 4 tests, refer to the [Pact junit runner](../junit/README.md) docs. # Verifying V4 Pact files that require plugins (version 4.3.0+) Pact files that require plugins can be verified with version 4.3.0+. For details on how plugins work, see the [Pact plugin project](https://github.com/pact-foundation/pact-plugins). Each required plugin is defined in the `plugins` section in the Pact metadata in the Pact file. The plugins will be loaded from the plugin directory. By default, this is `~/.pact/plugins` or the value of the `PACT_PLUGIN_DIR` environment variable. Each plugin required by the Pact file must be installed there. You will need to follow the installation instructions for each plugin, but the default is to unpack the plugin into a sub-directory `<plugin-name>-<plugin-version>` (i.e., for the Protobuf plugin 0.0.0 it will be `protobuf-0.0.0`). The plugin manifest file must be present for the plugin to be able to be loaded. # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

junit

au.com.dius.pact.provider : junit

# Pact junit runner ## Dependency The library is available on maven central using: * group-id = `au.com.dius.pact.provider` * artifact-id = `junit` * version-id = `4.1.x` ## Overview Library provides ability to play contract tests against a provider service in JUnit fashionable way. Supports: - Out-of-the-box convenient ways to load pacts - Easy way to change assertion strategy - **org.junit.BeforeClass**, **org.junit.AfterClass** and **org.junit.ClassRule** JUnit annotations, that will be run once - before/after whole contract test suite. - **org.junit.Before**, **org.junit.After** and **org.junit.Rule** JUnit annotations, that will be run before/after each test of an interaction. - **au.com.dius.pact.provider.junit.State** custom annotation - before each interaction that requires a state change, all methods annotated by `@State` with appropriate the state listed will be invoked. These methods must either take no parameters or a single Map parameter. ## Example of HTTP test ```java @RunWith(PactRunner.class) // Say JUnit to run tests with custom Runner @Provider("myAwesomeService") // Set up name of tested provider @PactFolder("pacts") // Point where to find pacts (See also section Pacts source in documentation) public class ContractTest { // NOTE: this is just an example of embedded service that listens to requests, you should start here real service @ClassRule //Rule will be applied once: before/after whole contract test suite public static final ClientDriverRule embeddedService = new ClientDriverRule(8332); @BeforeClass //Method will be run once: before whole contract test suite public static void setUpService() { //Run DB, create schema //Run service //... } @Before //Method will be run before each test of interaction public void before() { // Rest data // Mock dependent service responses // ... embeddedService.addExpectation( onRequestTo("/data"), giveEmptyResponse() ); } @State({"default", "no-data"}) // Method will be run before testing interactions that require "default" or "no-data" state public void toDefaultState() { // Prepare service before interaction that require "default" state // ... System.out.println("Now service in default state"); } @State("with-data") // Method will be run before testing interactions that require "with-data" state public void toStateWithData(Map data) { // Prepare service before interaction that require "with-data" state. The provider state data will be passed // in the data parameter // ... System.out.println("Now service in state using data " + data); } @TestTarget // Annotation denotes Target that will be used for tests public final Target target = new HttpTarget(8332); // Out-of-the-box implementation of Target (for more information take a look at Test Target section) } ``` ## Example of Message test ```java @RunWith(PactRunner.class) // Say JUnit to run tests with custom Runner @Provider("myAwesomeService") // Set up name of tested provider @PactBroker(host="pactbroker", port = "80") public class ConfirmationKafkaContractTest { @TestTarget // Annotation denotes Target that will be used for tests public final Target target = new MessageTarget(); // Out-of-the-box implementation of Target (for more information take a look at Test Target section) @BeforeClass //Method will be run once: before whole contract test suite public static void setUpService() { //Run DB, create schema //Run service //... } @Before //Method will be run before each test of interaction public void before() { // Message data preparation // ... } @PactVerifyProvider('an order confirmation message') String verifyMessageForOrder() { Order order = new Order() order.setId(10000004) order.setPrice(BigDecimal.TEN) order.setUnits(15) def message = new ConfirmationKafkaMessageBuilder() .withOrder(order) .build() JsonOutput.toJson(message) } } ``` ### Example of Message test that verifies metadata To have the message metadata - such as the topic - also verified you need to return a `MessageAndMetadata` from the invoked method that contains the payload and metadata to be validation. For example, to verify the metadata of an integration using the Spring [Message](https://docs.spring.io/spring-integration/reference/html/message.html) interface, you can do something like the following: ```java ... @PactVerifyProvider("a product event update") public MessageAndMetadata verifyMessageForOrder() { ProductEvent product = new ProductEvent("id1", "product name", "product type", "v1", EventType.CREATED); Message<String> message = new ProductMessageBuilder().withProduct(product).build(); return generateMessageAndMetadata(message); } private MessageAndMetadata generateMessageAndMetadata(Message<String> message) { HashMap<String, Object> metadata = new HashMap<String, Object>(); message.getHeaders().forEach((k, v) -> metadata.put(k, v)); return new MessageAndMetadata(message.getPayload().getBytes(), metadata); } ``` _NOTE: this requires you to add medadata expections in your consumer test_ ## Provider state callback methods For the provider states in the pact being verified, you can define methods to be invoked to setup the correct state for each interaction. Just annotate a method with the `au.com.dius.pact.provider.junit.State` annotation and the method will be invoked before the interaction is verified. For example: ```java @State("SomeProviderState") // Must match the state description in the pact file public void someProviderState() { // Do what you need to set the correct state } ``` If there are parameters in the pact file, just add a Map parameter to the method to be able to access those parameters. ```java @State("SomeProviderState") public void someProviderState(Map<String, Object> providerStateParameters) { // Do what you need to set the correct state } ``` ### Provider state teardown methods If you need to tear down your provider state, you can annotate a method with the `@State` annotation with the action set to `StateChangeAction.TEARDOWN` and it will be invoked after the interaction is verified. ```java @State("SomeProviderState", action = StateChangeAction.TEARDOWN) public void someProviderStateCleanup() { // Do what you need to to teardown the state } ``` #### Returning values that can be injected You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. There are methods on the consumer DSLs that can provider an expression that contains variables (like '/api/user/au.com.dius.pact.provider:junit:jar:4.4.0-beta.2' for the path). The provider state callback can then return a map for values, and the `id` attribute from the map will be expanded in the expression. For this to work, just make your provider state method return a Map of the values. ### Using multiple classes for the state change methods If you have a large number of state change methods, you can split things up by moving them to other classes. There are two ways you can do this: #### Use interfaces You can put the state change methods on interfaces and then have your test class implement those interfaces. See [StateAnnotationsOnInterfaceTest](https://github.com/DiUS/pact-jvm/blob/master/provider/junit/src/test/java/au/com/dius/pact/provider/junit/StateAnnotationsOnInterfaceTest.java) for an example. #### Specify the additional classes on the test target You can provide the additional classes to the test target with the `withStateHandler` or `setStateHandlers` methods. See [BooksPactProviderTest](https://github.com/DiUS/pact-jvm/blob/master/provider/spring/src/test/java/au/com/dius/pact/provider/spring/BooksPactProviderTest.java) for an example. ## Pact source The Pact runner will automatically collect pacts based on annotations on the test class. For this purpose there are 3 out-of-the-box options (files from a directory, files from a set of URLs or a pact broker) or you can easily add your own Pact source. If you need to load a single pact file from the file system, use the `PactUrl` with the URL set to the file path. **Note:** You can only define one source of pacts per test class. ### Download pacts from a pact-broker To use pacts from a Pact Broker, annotate the test class with `@PactBroker(host="host.of.pact.broker.com", port = "80")`. You can also specify the protocol, which defaults to "http". The pact broker will be queried for all pacts with the same name as the provider annotation. For example, test all pacts for the "Activity Service" in the pact broker: ```java @RunWith(PactRunner.class) @Provider("Activity Service") @PactBroker(host = "localhost", port = "80") public class PactJUnitTest { @TestTarget public final Target target = new HttpTarget(5050); } ``` #### Using Java System properties The pact broker loader was updated to allow system properties to be used for the hostname, port or protocol. The port was changed to a string to allow expressions to be set. To use a system property or environment variable, you can place the property name in `${}` expression de-markers: ```java @PactBroker(host="${pactbroker.hostname}", port = "80") ``` You can provide a default value by separating the property name with a colon (`:`): ```java @PactBroker(host="${pactbroker.hostname:localhost}", port = "80") ``` #### More Java System properties The default values of the `@PactBroker` annotation now enable variable interpolation. The following keys may be managed through the environment * `pactbroker.host` * `pactbroker.port` * `pactbroker.scheme` * `pactbroker.tags` (comma separated) * `pactbroker.auth.username` (for basic auth) * `pactbroker.auth.password` (for basic auth) * `pactbroker.auth.token` (for bearer auth) * `pactbroker.consumers` (comma separated list to filter pacts by consumer; if not provided, will fetch all pacts for the provider) #### Using tags with the pact broker The pact broker allows different versions to be tagged. To load all the pacts: ```java @PactBroker(host="pactbroker", port = "80", tags = {"latest", "dev", "prod"}) ``` The default value for tags is `latest` which is not actually a tag but instead corresponds to the latest version ignoring the tags. If there are multiple consumers matching the name specified in the provider annotation then the latest pact for each of the consumers is loaded. For any other value the latest pact tagged with the specified tag is loaded. Specifying multiple tags is an OR operation. For example if you specify `tags = {"dev", "prod"}` then both the latest pact file tagged with `dev` and the latest pact file taggged with `prod` is loaded. In 4.1.4+, tags was deprecated in favor of consumerVersionSelectors. Consumer version selectors give you the ability to include pacts for the latest version of a tag, or all versions of a tag. ```java @PactBroker( host="pactbroker", port="80", consumerVersionSelectors={ @ConsumerVersionSelector(tag = "dev"), // Verify the latest version tagged with dev @ConsumerVersionSelector(tag = "prod", latest = "false") // Verify all versions tagged with prod } ) ``` #### Using authentication with the pact broker You can use basic authentication with the `@PactBroker` annotation by setting the `authentication` value to a `@PactBrokerAuth` annotation. For example: ```java @PactBroker(host = "${pactbroker.url:localhost}", port = "1234", tags = {"latest", "prod", "dev"}, authentication = @PactBrokerAuth(username = "test", password = "test")) ``` Bearer tokens are also supported. For example: ```java @PactBroker(host = "${pactbroker.url:localhost}", port = "1234", tags = {"latest", "prod", "dev"}, authentication = @PactBrokerAuth(token = "test")) ``` The `token`, `username` and `password` values also take Java system property expressions. Preemptive Authentication can be enabled by setting the `pact.pactbroker.httpclient.usePreemptiveAuthentication` Java system property to `true`. ### Allowing just the changed pact specified in a webhook to be verified [4.0.6+] When a consumer publishes a new version of a pact file, the Pact broker can fire off a webhook with the URL of the changed pact file. To allow only the changed pact file to be verified, you can override the URL by adding the annotation `@AllowOverridePactUrl` to your test class and then setting using the `pact.filter.consumers` and `pact.filter.pacturl` values as either Java system properties or environment variables. If you have annotated your test class with `@Consumer` you don't need to provide `pact.filter.consumers`. ### Pact Url To use pacts from urls annotate the test class with ```java @PactUrl(urls = {"http://build.server/zoo_app-animal_service.json"}) ``` If you need to load a single pact file from the file system, you can use the `PactUrl` with the URL set to the file path. For authenticated URLs, specify the authentication on the annotation ```java @PactUrl(urls = {"http://build.server/zoo_app-animal_service.json"}, authentication = @Authentication(token = "1234ABCD")) ``` You can use either bearer token scheme (by setting the `token`), or basic auth by setting the `username` and `password`. JVM system properties or environment variables can also be used by placing the property/variable name in `${}` expressions. ```java @PactUrl(urls = {"http://build.server/zoo_app-animal_service.json"}, authentication = @Authentication(token = "${TOKEN}")) ``` ### Pact folder To use pacts from a resource folder of the project annotate test class with ```java @PactFolder("subfolder/in/resource/directory") ``` ### Custom pacts source It's possible to use a custom Pact source. For this, implement interface `au.com.dius.pact.provider.junit.loader.PactLoader` and annotate the test class with `@PactSource(MyOwnPactLoader.class)`. **Note:** class `MyOwnPactLoader` must have a default empty constructor or a constructor with one argument of class `Class` which at runtime will be the test class so you can get custom annotations of test class. ### Filtering the interactions that are verified By default, the pact runner will verify all pacts for the given provider. You can filter the pacts and interactions by the following methods. #### Filtering by Consumer You can run only those pacts for a particular consumer by adding a `@Consumer` annotation to the test class. For example: ```java @RunWith(PactRunner.class) @Provider("Activity Service") @Consumer("Activity Consumer") @PactBroker(host = "localhost", port = "80") public class PactJUnitTest { @TestTarget public final Target target = new HttpTarget(5050); } ``` #### Interaction Filtering You can filter the interactions that are executed by adding a `@PactFilter` annotation to your test class. The pact filter annotation will then only verify interactions that have a matching value, by default provider state. You can provide multiple values to match with. The filter criteria is defined by the filter property. The filter must implement the `au.com.dius.pact.provider.junit.filter.InteractionFilter` interface. Also check the `InteractionFilter` interface for default filter implementations. For example: ```java @RunWith(PactRunner.class) @PactFilter("Activity 100 exists in the database") public class PactJUnitTest { } ``` You can also use regular expressions with the filter. For example: ```java @RunWith(PactRunner.class) @PactFilter(values = {"^\\/somepath.*"}, filter = InteractionFilter.ByRequestPath.class) public class PactJUnitTest { } ``` **NOTE!** You will only be able to publish the verification results if all interactions have been verified. If an interaction is not covered because it was filtered out, you will not be able to publish. ##### Filtering the interactions that are run **(version 4.1.2+)** You can filter the interactions that are run by setting the JVM system property `pact.filter.description`. This propery takes a regular expression to match against the interaction description. **NOTE!** this property needs to be set on the test JVM if your build is running with Gradle or Maven. ### Setting the test to not fail when no pacts are found By default the pact runner will fail the verification test if no pact files are found to verify. To change the failure into a warning, add a `@IgnoreNoPactsToVerify` annotation to your test class. #### Ignoring IO errors loading pact files You can also set the test to ignore any IO and parser exceptions when loading the pact files by setting the `ignoreIoErrors` attribute on the annotation to `"true"` or setting the JVM system property `pact.verification.ignoreIoErrors` to `true`. ** WARNING! Do not enable this on your CI server, as this could result in your build passing with no providers having been verified due to a configuration error. ** ### Overriding the handling of a body data type **NOTE: version 4.1.3+** By default, bodies will be handled based on their content types. For binary contents, the bodies will be base64 encoded when written to the Pact file and then decoded again when the file is loaded. You can change this with an override property: `pact.content_type.override.<TYPE>.<SUBTYPE>=text|json|binary`. For instance, setting `pact.content_type.override.application.pdf=text` will treat PDF bodies as a text type and not encode/decode them. ### Controlling the generation of diffs **NOTE: version 4.2.7+** When there are mismatches with large bodies the calculation of the diff can take a long time . You can turn off the generation of the diffs with the JVM system property: `pact.verifier.generateDiff=true|false|<dataSize>`, where `dataSize`, if specified, must be a valid data size (for instance `100kb` or `1mb`). This will turn off the diff calculation for payloads that exceed this size. For instance, setting `pact.verifier.generateDiff=false` will turn off the generation of diffs for all bodies, while `pact.verifier.generateDiff=512kb` will only turn off the diffs if the actual or expected body is larger than 512kb. ## Test target The field in test class of type `au.com.dius.pact.provider.junit.target.Target` annotated with `au.com.dius.pact.provider.junit.target.TestTarget` will be used for actual Interaction execution and asserting of contract. **Note:** there must be exactly 1 such field, otherwise an `InitializationException` will be thrown. ### HttpTarget `au.com.dius.pact.provider.junit.target.HttpTarget` - out-of-the-box implementation of `au.com.dius.pact.provider.junit.target.Target` that will play pacts as http request and assert response from service by matching rules from pact. You can also specify the protocol, defaults to "http". ### MessageTarget `au.com.dius.pact.provider.junit.target.MessageTarget` - out-of-the-box implementation of `au.com.dius.pact.provider.junit.target.Target` that will play pacts as an message and assert response from service by matching rules from pact. **Note for Maven users:** If you use Maven to run your tests, you will have to make sure that the Maven Surefire plugin is at least version 2.22.1 uses an isolated classpath. For example, configure it by adding the following to your POM: ```xml <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.22.1</version> <configuration> <useSystemClassLoader>false</useSystemClassLoader> </configuration> </plugin> ``` #### Modifying the requests before they are sent **NOTE: `@TargetRequestFilter` is only for JUnit 4. For JUnit 5 see [JUnit 5 docs](/provider/junit5/README.md#modifying-the-requests-before-they-are-sent).** 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 HttpTarget supports request filters by annotating methods on the test class with `@TargetRequestFilter`. These methods must be public void methods that take a single HttpRequest parameter of type `org.apache.http.HttpRequest` (4.2.x and before) or `org.apache.hc.core5.http.HttpRequest` (4.3.0+). For example: ```java @TargetRequestFilter public void exampleRequestFilter(HttpRequest request) { request.addHeader("Authorization", "OAUTH hdsagasjhgdjashgdah..."); } ``` __*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 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. ### Custom Test Target It's possible to use custom `Target`, for that interface `Target` should be implemented and this class can be used instead of `HttpTarget`. # Verification Reports The default test behaviour is to display the verification being done to the console, and pass or fail the test via the normal JUnit mechanism. Additional reports can be generated from the tests. ## Enabling additional reports via annotations on the test classes A `@VerificationReports` annotation can be added to any pact test class which will control the verification output. The annotation takes a list report types and an optional report directory (defaults to "target/pact/reports"). The currently supported report types are `console`, `markdown` and `json`. For example: ```java @VerificationReports({"console", "markdown"}) public class MyPactTest { ``` will enable the markdown report in addition to the normal console output. And, ```java @VerificationReports(value = {"markdown"}, reportDir = "/myreports") public class MyPactTest { ``` will disable the normal console output and write the markdown reports to "/myreports". ## Enabling additional reports via Java system properties or environment variables The additional reports can also be enabled with Java System properties or environment variables. The following two properties have been introduced: `pact.verification.reports` and `pact.verification.reportDir`. `pact.verification.reports` is the comma separated list of report types to enable (e.g. `console,json,markdown`). `pact.verification.reportDir` is the directory to write reports to (defaults to "target/pact/reports"). ## Additional Reports The following report types are available in addition to console output (`console`, which is enabled by default): `markdown`, `json`. You can also provide a fully qualified classname as report so custom reports are also supported. This class must implement `au.com.dius.pact.provider.reporters.VerifierReporter` interface in order to be correct custom implementation of a report. # Publishing verification results to a Pact Broker 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. You need to set the version of the provider that is verified using the `pact.provider.version` system property. To enable publishing of results, set the Java system property or environment variable `pact.verifier.publishResults` to `true`. ### IMPORTANT NOTE!!!: this property needs to be set on the test JVM if your build is running with Gradle or Maven. Gradle and Maven do not pass in the system properties in to the test JVM from the command line. The system properties specified on the command line only control the build JVM (the one that runs Gradle or Maven), but the tests will run in a new JVM. See [Maven Surefire Using System Properties](https://maven.apache.org/surefire/maven-surefire-plugin/examples/system-properties.html) and [Gradle Test docs](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.testing.Test.html#org.gradle.api.tasks.testing.Test:systemProperties). ## Tagging the provider before verification results are published [4.0.1+] You can have a tag pushed against the provider version before the verification results are published. To do this you need set the `pact.provider.tag` JVM system property to the tag value. From 4.1.8+, you can specify multiple tags with a comma separated string for the `pact.provider.tag` system property. ## Setting the provider branch before verification results are published [4.3.0-beta.7+] Pact Broker version 2.86.0 or later You can have a branch pushed against the provider version before the verification results are published. To do this you need set the `pact.provider.branch` JVM system property to the branch value. ## Setting the build URL for verification results [4.2.16/4.3.2+] You can specify a URL to link to your CI build output. To do this you need to set the `pact.verifier.buildUrl` JVM system property to the URL value. # Pending Pact Support (version 4.1.3 and later) If your Pact broker supports pending pacts, you can enable support for that by enabling that on your Pact broker annotation or with JVM system properties. You also need to provide the tags that will be published with your provider's verification results. The broker will then label any pacts found that don't have a successful verification result as pending. That way, if they fail verification, the verifier will ignore those failures and not fail the build. For example, with annotation: ```java @Provider("Activity Service") @PactBroker(host = "test.pactflow.io", tags = {"test"}, scheme = "https", enablePendingPacts = "true", providerTags = "master" ) public class PactJUnitTest { ``` You can also use the `pactbroker.enablePending` and `pactbroker.providerTags` JVM system properties. Then any pending pacts will not cause a build failure. # Work In Progress (WIP) Pact Support (version 4.1.5 and later) If your Pact broker supports wip pacts, you can enable support by enabling it on your Pact broker annotation, or with JVM system properties. You also need to enable pending pacts. Once enabled, your provider will verify any "work in progress" pacts that have been published since a given date. A WIP pact is a pact that is the latest for its tag that does not have any successful verification results with the provider tag. ```java @Provider("Activity Service") @PactBroker(host = "test.pactflow.io", tags = {"test"}, scheme = "https", enablePendingPacts = "true", providerTags = "master" includeWipPactsSince = "2020-06-19" ) public class PactJUnitTest { ``` You can also use the `pactbroker.includeWipPactsSince` JVM system property. Since all WIP pacts are also pending pacts, failed verifications will not cause a build failure. # Verifying V4 Pact files that require plugins (version 4.3.0+) Pact files that require plugins can be verified with version 4.3.0+. For details on how plugins work, see the [Pact plugin project](https://github.com/pact-foundation/pact-plugins). Each required plugin is defined in the `plugins` section in the Pact metadata in the Pact file. The plugins will be loaded from the plugin directory. By default, this is `~/.pact/plugins` or the value of the `PACT_PLUGIN_DIR` environment variable. Each plugin required by the Pact file must be installed there. You will need to follow the installation instructions for each plugin, but the default is to unpack the plugin into a sub-directory `<plugin-name>-<plugin-version>` (i.e., for the Protobuf plugin 0.0.0 it will be `protobuf-0.0.0`). The plugin manifest file must be present for the plugin to be able to be loaded. # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

gradle

au.com.dius.pact.provider : gradle

# Gradle plugin to verify a provider 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. __*Important Note: Any properties that need to be set when using the Gradle plugin need to be provided with `-P` and not `-D` as with the other Pact-JVM modules!*__ ## To Use It ### For Gradle versions 2.1+ ```groovy plugins { id "au.com.dius.pact" version "4.1.0" } ``` ### For Gradle versions prior to 2.1 #### 1.1. Add the gradle jar file to your build script class path: ```groovy buildscript { repositories { mavenCentral() } dependencies { classpath 'au.com.dius.pact.provider:gradle:4.1.0' } } ``` #### 1.2. Apply the pact plugin ```groovy apply plugin: 'au.com.dius.pact' ``` ### 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` # 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| |`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.filter.pacturl`|This filter allows just the just the changed pact specified in a webhook to be run. It should be used in conjunction with `pact.filter.consumers` | |`pact.verifier.publishResults`|Publishing of verification results will be skipped unless this property is set to 'true'| |`pact.verifier.ignoreNoConsumers`|If set to `true`, don't fail the build if there are no consumers to verify [4.1.19+]| The following project properties must be specified as system properties: |Property|Description| |--------|-----------| |`pact.verifier.disableUrlPathDecoding`|Disables decoding of request paths| |`pact.pactbroker.httpclient.usePreemptiveAuthentication`|Enables preemptive authentication with the pact broker when set to `true`| |`pact.provider.tag`|Sets the provider tag to push before publishing verification results (can use a comma separated list)| |`pact.provider.branch`|Sets the provider branch to push before publishing verification results| |`pact.content_type.override.<TYPE>.<SUBTYPE>=<VAL>` where `<VAL>` may be `text`, `json` or `binary`|Overrides the handling of a particular content type [4.1.3+]| |`pact.verifier.enableRedirectHandling`|Enables automatically handling redirects [4.1.8+]| |`pact.verifier.generateDiff`|Controls the generation of diffs. Can be set to `true`, `false` or a size threshold (for instance `1mb` or `100kb`) which only enables diffs for payloads of size less than that [4.2.7+]| |`pact.verifier.buildUrl`|Specifies buildUrl to report to the broker when publishing verification results [4.2.16/4.3.2+]| ## 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') } } } } ``` You can also give a Closure as the provider `port`. ## Specifying the pact file or URL at runtime 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` 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 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 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 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 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 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 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. ## Overriding the handling of a body data type **NOTE: version 4.1.3+** By default, bodies will be handled based on their content types. For binary contents, the bodies will be base64 encoded when written to the Pact file and then decoded again when the file is loaded. You can change this with an override property: `pact.content_type.override.<TYPE>.<SUBTYPE>=text|binary`. For instance, setting `pact.content_type.override.application.pdf=text` will treat PDF bodies as a text type and not encode/decode them. ## 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 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 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 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 } } } } } ``` #### Returning values that can be injected You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. There are methods on the consumer DSLs that can provider an expression that contains variables (like '/api/user/au.com.dius.pact.provider:gradle:jar:4.4.0-beta.2' for the path). The provider state callback can then return a map for values, and the `id` attribute from the map will be expanded in the expression. For URL callbacks, the values need to be returned as JSON in the response body. ## 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 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 Pact-JVM 4.1.0 and later #### First: Add a `broker` configuration block You can enable Pact broker support by adding a `broker` configuration block to the `pact` block. For example: ```groovy pact { broker { pactBrokerUrl = 'https://your-broker-url/' // To use basic auth pactBrokerUsername = '<USERNAME>' pactBrokerPassword = '<PASSWORD>' // OR to use a bearer token pactBrokerToken = '<TOKEN>' } } ``` #### Second: Define your service provider ```groovy pact { serviceProviders { myProvider { // Define the name of your provider here fromPactBroker { selectors = latestTags('test') // specify your tags here. You can leave this out to just use the latest pacts } } } } ``` ### For Pact-JVM versions before 4.1.0 You configure your service provider and then use the `hasPactsFrom..` methods. 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. Or with a bearer token: ```groovy pact { serviceProviders { provider1 { hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Bearer', pactBrokerToken]) } } } ``` Preemptive Authentication can be enabled by setting the `pact.pactbroker.httpclient.usePreemptiveAuthentication` property to `true`. **NOTE:** If you're using [pactflow.io](https://pactflow.io/), follow these instructions for configuring your [bearer token](https://docs.pactflow.io/docs/getting-started/#configuring-your-api-token). ### Allowing just the changed pact specified in a webhook to be verified [4.0.6+] When a consumer publishes a new version of a pact file, the Pact broker can fire off a webhook with the URL of the changed pact file. To allow only the changed pact file to be verified, you can override the URL by using the `pact.filter.pacturl` project properties. For example, running: ```console gradle pactVerify -Ppact.filter.pacturl=https://test.pact.dius.com.au/pacts/provider/Activity%20Service/consumer/Foo%20Web%20Client/version/1.0.1 ``` will only run the verification with the given pact file URL. ## Verifying pact files from a S3 bucket **NOTE:** You will need to add the Amazon S3 SDK jar file to your project. 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 **NOTE**: There is a pact CLI that can be used to publish pacts. See https://github.com/pact-foundation/pact-ruby-cli. 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. If you have configured your broker details in a broker configuration block, the task will use that. Otherwise, configure the broker details on the publish block. 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 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. You can override this with the `consumerVersion` property. Make sure you have set one otherwise the broker will reject the pact files. ## Publishing to an authenticated pact broker To publish to a broker protected by basic auth, include the username/password in the broker configuration For example: ```groovy pact { broker { pactBrokerUrl = 'https://your-broker-url/' // To use basic auth pactBrokerUsername = '<USERNAME>' pactBrokerPassword = '<PASSWORD>' // OR to use a bearer token pactBrokerToken = '<TOKEN>' } } ``` You can add the username and password as properties on the publish block. ```groovy pact { publish { pactBrokerUrl = 'https://mypactbroker.com' pactBrokerUsername = 'username' pactBrokerPassword = 'password' } } ``` or with a bearer token ```groovy pact { publish { pactBrokerUrl = 'https://mypactbroker.com' pactBrokerToken = 'token' } } ``` ## Excluding pacts from being published You can exclude some of the pact files from being published by providing a list of regular expressions that match against the base names of the pact files. For example: ```groovy pact { publish { excludes = [ '.*\\-\\d+$' ] // exclude all pact files that end with a dash followed by a number in the name } } ``` ## Including the consumer branch when publishing [min versions 4.1.33/4.2.19/4.3.4] The consumer branch and build URL can be included when the pacts are published. This requires Pact Broker version **2.86.0 or later**. The branch name and build URL can either be configured in the project or as system properties or environment variables. ### Configured in the build There are attributes on the `publish` block to set these values. ```groovy pact { publish { consumerBranch = 'feat/test' // build URL is optional consumerBuildUrl = 'https://github.com/pact-foundation/pact-jvm/actions/runs/1685674772' } } ``` ## Configured as JVM system properties You can configure these values as system properties using the following keys: * `pact.publish.consumer.buildUrl` * `pact.publish.consumer.branchName` * `pact.publish.consumer.version` ## Configured as environment variables You can configure these values as environment variables using the following keys: * `pact.publish.consumer.buildUrl` * `pact.publish.consumer.branchName` * `pact.publish.consumer.version` OR * `PACT_PUBLISH_CONSUMER_BUILDURL` * `PACT_PUBLISH_CONSUMER_BRANCHNAME` * `PACT_PUBLISH_CONSUMER_VERSION` # Verifying a message provider 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. # Verification Reports The default behaviour is to display the verification being done to the console, and pass or fail the build via the normal Gradle mechanism. 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 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`. To provide the build URL, set the JVM system property `pact.verifier.buildUrl`. By default, the Gradle project version will be used as the provider version. You can override this by setting the `providerVersion` property. ```groovy pact { serviceProviders { provider1 { providerVersion = { branchName() + '-' + abbreviatedId() } hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Basic', pactBrokerUser, pactBrokerPassword]) } } } ``` ## Tagging the provider before verification results are published [4.0.1+] You can have a tag pushed against the provider version before the verification results are published. There are two ways to do this with the Gradle plugin. You can provide a closure in a similar way to the provider version, i.e. ```groovy pact { serviceProviders { provider1 { providerVersion = { branchName() + '-' + abbreviatedId() } providerTags = { [ branchName() ] } hasPactsFromPactBroker('http://pact-broker:5000/', authentication: ['Basic', pactBrokerUser, pactBrokerPassword]) } } } ``` or you can set the `pact.provider.tag` JVM system property. For example: ```console $ ./gradlew -d pactverify -Ppact.verifier.publishResults=true -Dpact.provider.tag=Test2 ``` From 4.1.8+, you can specify multiple tags with an array for the `providerTag` value, or a comma separated string for the `pact.provider.tag` system property. # Pending Pact Support (version 4.1.0 and later) If your Pact broker supports pending pacts, you can enable support for that by enabling that on your Pact broker annotation or with JVM system properties. You also need to provide the tags that will be published with your provider's verification results. The broker will then label any pacts found that don't have a successful verification result as pending. That way, if they fail verification, the verifier will ignore those failures and not fail the build. For example: ```groovy pact { serviceProviders { myProvider { fromPactBroker { selectors = latestTags('test') // specify your tags here. You can leave this out to just use the latest pacts enablePending = true // enable pending pacts support providerTags = ['master'] // specify the provider main-line tags } } } } ``` Then any pending pacts will not cause a build failure. # Can I Deploy check There is a `canIDeploy` Gradle task that you can use to preform a deployment safety check. This task requires two parameters: `pacticipant` and either `pacticipantVersion` or `latest=true`. It will use the configuration from the `broker` section of your Gradle build. ```console $ ./gradlew canideploy -Ppacticipant='Activity Service' -Platest=true > Task :canIDeploy FAILED Computer says no ¯\_(ツ)_/¯ The verification between the latest version of Foo Web Client 2 (1.2.3/AB) and the latest version of Activity Service (0.0.3) failed There is no verified pact between the latest version of Foo Web Client (1.2.3/AB) and the latest version of Activity Service (0.0.3) FAILURE: Build failed with an exception. * What went wrong: Can you deploy? Computer says no ¯\_(ツ)_/¯ * Try: Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights. * Get more help at https://help.gradle.org BUILD FAILED in 1s ``` ## Enabling retry when there are unknown results (4.1.11+) It can happen that there are still unknown results in the Pact broker because the provider verification is still running. You can enable a retry with a wait interval to poll for the results to become available. There are two settings that can be added to the `broker` configuration to enable this: `retryCountWhileUnknown` and `retryWhileUnknownInterval`. |Field|Description|Default| |-----|-----------|-------| |retryCountWhileUnknown|The amount of times to retry while there are unknown results|0| |retryWhileUnknownInterval|The number of seconds to wait between retries|10| Example use: ```groovy pact { broker { pactBrokerUrl = 'http://localhost:1234/' retryCountWhileUnknown = 3 retryWhileUnknownInterval = 120 // 2 minutes between retries } } ``` # Verifying V4 Pact files that require plugins (version 4.3.0+) Pact files that require plugins can be verified with version 4.3.0+. For details on how plugins work, see the [Pact plugin project](https://github.com/pact-foundation/pact-plugins). Each required plugin is defined in the `plugins` section in the Pact metadata in the Pact file. The plugins will be loaded from the plugin directory. By default, this is `~/.pact/plugins` or the value of the `PACT_PLUGIN_DIR` environment variable. Each plugin required by the Pact file must be installed there. You will need to follow the installation instructions for each plugin, but the default is to unpack the plugin into a sub-directory `<plugin-name>-<plugin-version>` (i.e., for the Protobuf plugin 0.0.0 it will be `protobuf-0.0.0`). The plugin manifest file must be present for the plugin to be able to be loaded. # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

support

au.com.dius.pact.core : support

# pact-jvm-support Support module with common utilities

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

pactbroker

au.com.dius.pact.core : pactbroker

Pact Broker Client ================== This module contains the client classes for interacting with a pact broker.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

base32768

org.webjars.npm : base32768

WebJar for base32768

Последняя версия: 2.0.2

Дата: 27 апр. 2022 г.

model

au.com.dius.pact.core : model

Pact model ========== The model project is responsible for providing: * a model to represent pacts * serialization and deserialization * comparison between two parts of the pact model * conversion between the pact model and whatever third party libraries used by the pact-consumer and pact-provider requires You should never need to include this project directly

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

matchers

au.com.dius.pact.core : matchers

Pact JVM Matchers ================= > Implements matchers for pact requests, responses and messages. This library implements the core matching logic required for matching HTTP requests and responses. It is based on the [V3 pact specification](https://github.com/pact-foundation/pact-specification/tree/version-3) and [V4 pact specification](https://github.com/pact-foundation/pact-specification/tree/version-4). ## Matching request and response parts V3 specification matching is supported for both JSON and XML bodies, headers, query strings and request paths. To understand the basic rules of matching, see [Gotchas](https://docs.pact.io/getting_started/matching/gotchas). For example test cases for matching, see the [Pact Specification Project, version 3](https://github.com/bethesque/pact-specification/tree/version-3). By default, Pact will use string equality matching following Postel's Law. This means that for an actual value to match an expected one, they both must consist of the same sequence of characters. For collections (basically Maps and Lists), they must have the same elements that match in the same sequence, with cases where the additional elements in an actual Map are ignored. Matching rules can be defined for both request and response elements based on a pseudo JSON-Path syntax. ### Matching Bodies For the most part, matching involves matching request and response bodies in JSON or XML format. Other formats will either have their own matching rules, or will follow the JSON one. #### JSON body matching rules Bodies consist of Objects (Maps of Key-Value pairs), Arrays (Lists) and values (Strings, Numbers, true, false, null). Body matching rules are prefixed with `$.`. The following method is used to determine if two bodies match: 1. If both the actual body and expected body are empty, the bodies match. 2. If the actual body is non-empty, and the expected body empty, the bodies match. 3. If the actual body is empty, and the expected body non-empty, the bodies don't match. 4. Otherwise do a comparison on the contents of the bodies. ##### For the body contents comparison: 1. If the actual and expected values are both Objects, compare as Maps. 2. If the actual and expected values are both Arrays, compare as Lists. 3. If the expected value is an Object, and the actual is not, they don't match. 4. If the expected value is an Array, and the actual is not, they don't match. 5. Otherwise, compare the values ##### For comparing Maps 1. If the actual map is non-empty while the expected is empty, they don't match. 2. If we allow unexpected keys, and the number of expected keys is greater than the actual keys, they don't match. 3. If we don't allow unexpected keys, and the expected and actual maps don't have the same number of keys, they don't match. 4. Otherwise, for each expected key and value pair: 1. if the actual map contains the key, compare the values 2. otherwise they don't match Postel's law governs if we allow unexpected keys or not. ##### For comparing lists 1. If there is a body matcher defined that matches the path to the list, default to that matcher and then compare the list contents. 2. If the expected list is empty and the actual one is not, the lists don't match. 3. Otherwise 1. compare the list sizes 2. compare the list contents ###### For comparing list contents 1. For each value in the expected list: 1. If the index of the value is less than the actual list's size, compare the value with the actual value at the same index using the method for comparing values. 2. Otherwise the value doesn't match ##### For comparing values 1. If there is a matcher defined that matches the path to the value, default to that matcher 2. Otherwise compare the values using equality. #### XML body matching rules Bodies consist of a root element, Elements (Lists with children), Attributes (Maps) and values (Strings). Body matching rules are prefixed with `$.`. The following method is used to determine if two bodies match: 1. If both the actual body and expected body are empty, the bodies match. 2. If the actual body is non-empty, and the expected body empty, the bodies match. 3. If the actual body is empty, and the expected body non-empty, the bodies don't match. 4. Otherwise do a comparison on the contents of the bodies. ##### For the body contents comparison: Start by comparing the root element. ##### For comparing elements 1. If there is a body matcher defined that matches the path to the element, default to that matcher on the elements name or children. 2. Otherwise the elements match if they have the same name. Then, if there are no mismatches: 1. compare the attributes of the element 2. compare the child elements 3. compare the text nodes ##### For comparing attributes Attributes are treated as a map of key-value pairs. 1. If the actual map is non-empty while the expected is empty, they don't match. 2. If we allow unexpected keys, and the number of expected keys is greater than the actual keys, they don't match. 3. If we don't allow unexpected keys, and the expected and actual maps don't have the same number of keys, they don't match. Then, for each expected key and value pair: 1. if the actual map contains the key, compare the values 2. otherwise they don't match Postel's law governs if we allow unexpected keys or not. Note for matching paths, attribute names are prefixed with an `@`. ###### For comparing child elements 1. If there is a matcher defined for the path to the child elements, then pad out the expected child elements to have the same size as the actual child elements. 2. Otherwise 1. If the actual children is non-empty while the expected is empty, they don't match. 2. If we allow unexpected keys, and the number of expected children is greater than the actual children, they don't match. 3. If we don't allow unexpected keys, and the expected and actual children don't have the same number of elements, they don't match. Then, for each expected and actual element pair, compare them using the rules for comparing elements. ##### For comparing text nodes Text nodes are combined into a single string and then compared as values. 1. If there is a matcher defined that matches the path to the text node (text node paths end with `#text`), default to that matcher 2. Otherwise compare the text using equality. ##### For comparing values 1. If there is a matcher defined that matches the path to the value, default to that matcher 2. Otherwise compare the values using equality. ### Matching Paths Paths are matched by the following: 1. If there is a matcher defined for `path`, default to that matcher. 2. Otherwise paths are compared as Strings ### Matching Queries 1. If the actual and expected query strings are empty, they match. 2. If the actual is not empty while the expected is, they don't match. 3. If the actual is empty while the expected is not, they don't match. 4. Otherwise convert both into a Map of keys mapped to a list values, and compare those. #### Matching Query Maps Query strings are parsed into a Map of keys mapped to lists of values. Key value pairs can be in any order, but when the same key appears more than once the values are compared in the order they appear in the query string. ### Matching Headers 1. Do a case-insensitive sort of the headers by keys 2. For each expected header in the sorted list: 1. If the actual headers contain that key, compare the header values 2. Otherwise the header does not match For matching header values: 1. If there is a matcher defined for `header.<HEADER_KEY>`, default to that matcher 2. Otherwise strip all whitespace after commas and compare the resulting strings. #### Matching Request Headers Request headers are matched by excluding the cookie header. #### Matching Request cookies If the list of expected cookies contains all the actual cookies, the cookies match. ### Matching Status Codes Status codes are compared as integer values. ### Matching HTTP Methods The actual and expected methods are compared as case-insensitive strings. ## Matching Rules Pact supports extending the matching rules on each type of object (Request or Response) with a `matchingRules` element in the pact file. This is a map of JSON path strings to a matcher. When an item is being compared, if there is an entry in the matching rules that corresponds to the path to the item, the comparison will be delegated to the defined matcher. Note that the matching rules cascade, so a rule can be specified on a value and will apply to all children of that value. ## Matcher Path expressions Pact does not support the full JSON path expressions, only ones that match the following rules: 1. All paths start with a dollar (`$`), representing the root. 2. All path elements are separated by periods (`.`), except array indices which use square brackets (`[]`). 3. Path elements represent keys. 4. A star (`*`) can be used to match all keys of a map or all items of an array (one level only). So the expression `$.item1.level[2].id` will match the highlighted item in the following body: ```js { "item1": { "level": [ { "id": 100 }, { "id": 101 }, { "id": 102 // <---- $.item1.level[2].id }, { "id": 103 } ] } } ``` while `$.*.level[*].id` will match all the ids of all the levels for all items. ### Matcher selection algorithm Due to the star notation, there can be multiple matcher paths defined that correspond to an item. The first, most specific expression is selected by assigning weightings to each path element and taking the product of the weightings. The matcher with the path with the largest weighting is used. * The root node (`$`) is assigned the value 2. * Any path element that does not match is assigned the value 0. * Any property name that matches a path element is assigned the value 2. * Any array index that matches a path element is assigned the value 2. * Any star (`*`) that matches a property or array index is assigned the value 1. * Everything else is assigned the value 0. So for the body with highlighted item: ```js { "item1": { "level": [ { "id": 100 }, { "id": 101 }, { "id": 102 // <--- Item under consideration }, { "id": 103 } ] } } ``` The expressions will have the following weightings: | expression | weighting calculation | weighting | |------------|-----------------------|-----------| | $ | $(2) | 2 | | $.item1 | $(2).item1(2) | 4 | | $.item2 | $(2).item2(0) | 0 | | $.item1.level | $(2).item1(2).level(2) | 8 | | $.item1.level[1] | $(2).item1(2).level(2)[1(2)] | 16 | | $.item1.level[1].id | $(2).item1(2).level(2)[1(2)].id(2) | 32 | | $.item1.level[1].name | $(2).item1(2).level(2)[1(2)].name(0) | 0 | | $.item1.level[2] | $(2).item1(2).level(2)[2(0)] | 0 | | $.item1.level[2].id | $(2).item1(2).level(2)[2(0)].id(2) | 0 | | $.item1.level[*].id | $(2).item1(2).level(2)[*(1)].id(2) | 16 | | $.\*.level[\*].id | $(2).*(1).level(2)[*(1)].id(2) | 8 | So for the item with id 102, the matcher with path `$.item1.level[1].id` and weighting 32 will be selected. ## Supported matchers The following matchers are supported: | matcher | Spec Version | example configuration | description | |---------|--------------|-----------------------|-------------| | Equality | V1 | `{ "match": "equality" }` | This is the default matcher, and relies on the equals operator | | Regex | V2 | `{ "match": "regex", "regex": "\\d+" }` | This executes a regular expression match against the string representation of a values. | | Type | V2 | `{ "match": "type" }` | This executes a type based match against the values, that is, they are equal if they are the same type. | | MinType | V2 | `{ "match": "type", "min": 2 }` | This executes a type based match against the values, that is, they are equal if they are the same type. In addition, if the values represent a collection, the length of the actual value is compared against the minimum. | | MaxType | V2 | `{ "match": "type", "max": 10 }` | This executes a type based match against the values, that is, they are equal if they are the same type. In addition, if the values represent a collection, the length of the actual value is compared against the maximum. | | MinMaxType | V2 | `{ "match": "type", "max": 10, "min": 2 }` | This executes a type based match against the values, that is, they are equal if they are the same type. In addition, if the values represent a collection, the length of the actual value is compared against the minimum and maximum. | | Include | V3 | `{ "match": "include", "value": "substr" }` | This checks if the string representation of a value contains the substring. | | Integer | V3 | `{ "match": "integer" }` | This checks if the type of the value is an integer. | | Decimal | V3 | `{ "match": "decimal" }` | This checks if the type of the value is a number with decimal places. | | Number | V3 | `{ "match": "number" }` | This checks if the type of the value is a number. | | Timestamp | V3 | `{ "match": "datetime", "format": "yyyy-MM-dd HH:ss:mm" }` | Matches the string representation of a value against the datetime format | | Time | V3 | `{ "match": "time", "format": "HH:ss:mm" }` | Matches the string representation of a value against the time format | | Date | V3 | `{ "match": "date", "format": "yyyy-MM-dd" }` | Matches the string representation of a value against the date format | | Null | V3 | `{ "match": "null" }` | Match if the value is a null value (this is content specific, for JSON will match a JSON null) | | Boolean | V3 | `{ "match": "boolean" }` | Match if the value is a boolean value (booleans and the string values `true` and `false`) | | ContentType | V3 | `{ "match": "contentType", "value": "image/jpeg" }` | Match binary data by its content type (magic file check) | | Values | V3 | `{ "match": "values" }` | Match the values in a map, ignoring the keys | | ArrayContains | V4 | `{ "match": "arrayContains", "variants": [...] }` | Checks if all the variants are present in an array. | | StatusCode | V4 | `{ "match": "statusCode", "status": "success" }` | Matches the response status code. | | NotEmpty | V4 | `{ "match": "notEmpty" }` | Value must be present and not empty (not null or the empty string) | | Semver | V4 | `{ "match": "semver" }` | Value must be valid based on the semver specification | | EachKey | V4 | `{ "match": "eachKey", "rules": [{"match": "regex", "regex": "\\$(\\.\\w+)+"}], "value": "$.test.one" }` | Allows defining matching rules to apply to the keys in a map | | EachValue | V4 | `{ "match": "eachValue", "rules": [{"match": "regex", "regex": "\\$(\\.\\w+)+"}], "value": "$.test.one" }` | Allows defining matching rules to apply to the values in a collection. For maps, delgates to the Values matcher. | ### Matching Rule Definition Each matching rule definition is a comma-separated list of functions with a number of arguments within brackets. Most of the time only a single definition is required for a value, but in they case were more than one is required, they just need to be separated by a comma. #### Matching functions The main function is the `matching` function. This creates a matching rule based on a type and a number of values. The values required are dependent on the type of the matching rule. For example, matching with a regular expression: `matching(regex, '\\$(\\.\\w+)+', '$.test.one')` ##### equalTo Specifies that the attribute/field must be equal to the example value. Parameters: * example (Primitive value) Example: ``` matching(equalTo, 'TEXT') ``` ##### type Specifies that the attribute/field must have the same type as the example value. Parameters: * example (Primitive value) Example: ``` matching(type, 100) ``` ##### number types (number, integer, decimal) Specifies that the attribute/field must be a number type. `number` will match any numeric value, `integer` will match numeric values with no decimals (no significant figures after the decimal point) and `decimal` will match numeric values that have decimals (at least one significant figure after the decimal point). Parameters: * example (integer or decimal value) Example: ``` matching(integer, 100) matching(decimal, 100.1234) ``` ##### date and time matchers (datetime, date, time) Specifies that the string representation of the attribute/field must match the format specifier. These are based on the Java DateTimeFormatter. Parameters: * format (string) * example (string) Example: ``` matching(datetime, 'yyyy-MM-dd HH:mm:ss', '2021-10-07 13:00:13') matching(date, 'yyyy-MM-dd', '2021-10-07') matching(time, 'HH:mm:ss', '13:00:13') ``` ##### Regex Specifies that the string representation of the attribute/field must match the provided regular expression. Parameters: * regex (string) * example (string) Example: ``` matching(regex, '\w+ \w+', 'Hello World') ``` ##### Include Specifies that the string representation of the attribute/field must include the given string. Parameters: * example (string) Example: ``` matching(include, 'Hello World') ``` ##### Boolean Specifies that the attribute/field must be a boolean value or its string representation must be the strings `true` or `false`. Parameters: * example (boolean) Example: ``` matching(boolean, false) ``` ##### Semver Specifies that the string representation of the attribute/field must be a valid semantic version as per the semver specification. Parameters: * example (string) Example: ``` matching(semver, '1.0.0') ``` ##### Content Type Specifies that the byte string representation of the attribute/field must match the given content type using a magic file number check. This compares the first few bytes with a database of rules to determine the type of the contents. Parameters: * content type in MIME format (string) * example (string) Example: ``` matching(contentType, 'application/json', '{}') ``` ##### Matching an example type by reference Type matching can also be specified by a reference to an example. References are defined by a dollar (`$`) followed by a string value. The string value must be the attribute/field name that contains the example type. Parameters: * reference name Example: ``` matching($'items') // where items is the name of the example to match the types against ``` #### NotEmpty Specifies that the attribute field must be present and contain a value (not null or an empty string). Parameters: * example (primitive value) Example: ``` notEmpty('DateTime') ``` #### EachKey Allows a matching rule definition to be applied to the keys in a map. Parameters: * definition* (comma-separated list of matching rule definitions) Example: ``` eachKey(matching(regex, '\\$(\\.\\w+)+', '$.test.one')) ``` #### EachValue Allows a matching rule definition to be applied to the values in a collection (list/array or map form). Parameters: * definition* (comma-separated list of matching rule definitions) Example: ``` eachValue(matching($'items')) ``` ### Grammar The grammar for the Matching Rule Definition Language (ANTLR 4 format) ```antlrv4 grammar MatcherDefinition; matchingDefinition : matchingDefinitionExp ( COMMA matchingDefinitionExp )* EOF ; matchingDefinitionExp : ( 'matching' LEFT_BRACKET matchingRule RIGHT_BRACKET | 'notEmpty' LEFT_BRACKET primitiveValue RIGHT_BRACKET | 'eachKey' LEFT_BRACKET matchingDefinitionExp RIGHT_BRACKET | 'eachValue' LEFT_BRACKET matchingDefinitionExp RIGHT_BRACKET ) ; matchingRule : ( ( 'equalTo' | 'type' ) COMMA primitiveValue ) | 'number' COMMA ( DECIMAL_LITERAL | INTEGER_LITERAL ) | 'integer' COMMA INTEGER_LITERAL | 'decimal' COMMA DECIMAL_LITERAL | ( 'datetime' | 'date' | 'time' ) COMMA string COMMA string | 'regex' COMMA string COMMA string | 'include' COMMA string | 'boolean' COMMA BOOLEAN_LITERAL | 'semver' COMMA string | 'contentType' COMMA string COMMA string | DOLLAR string ; primitiveValue : string | DECIMAL_LITERAL | INTEGER_LITERAL | BOOLEAN_LITERAL ; string : STRING_LITERAL | 'null' ; INTEGER_LITERAL : '-'? DIGIT+ ; DECIMAL_LITERAL : '-'? DIGIT+ '.' DIGIT+ ; fragment DIGIT : [0-9] ; LEFT_BRACKET : '(' ; RIGHT_BRACKET : ')' ; STRING_LITERAL : '\'' (~['])* '\'' ; BOOLEAN_LITERAL : 'true' | 'false' ; COMMA : ',' ; DOLLAR : '$'; WS : [ \t\n\r] + -> skip ; ```

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

kotlin

au.com.dius.pact.consumer : kotlin

# Kotlin consumer DSL for Pact-JVM

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

junit5

au.com.dius.pact.consumer : junit5

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.pact.consumer` * artifact-id = `junit5` * version-id = `4.2.X` ## Usage ### 1. Add the Pact consumer test extension to the test class. To write Pact consumer tests with JUnit 5, you need to add `@ExtendWith(PactConsumerTestExt)` to your test class. This replaces the `PactRunner` used for JUnit 4 tests. The rest of the test follows a similar pattern as for JUnit 4 tests. ```java @ExtendWith(PactConsumerTestExt.class) class ExampleJavaConsumerPactTest { ``` ### 2. create a method annotated with `@Pact` that returns the interactions for the test For each test (as with JUnit 4), you need to define a method annotated with the `@Pact` annotation that returns the interactions for the test. ```java @Pact(provider="ArticlesProvider", consumer="test_consumer") public RequestResponsePact createPact(PactDslWithProvider builder) { return builder .given("test state") .uponReceiving("ExampleJavaConsumerPactTest test interaction") .path("/articles.json") .method("GET") .willRespondWith() .status(200) .body("{\"responsetest\": true}") .toPact(); } ``` ### 3. Link the mock server with the interactions for the test with `@PactTestFor` Then the final step is to use the `@PactTestFor` annotation to tell the Pact extension how to setup the Pact test. You can either put this annotation on the test class, or on the test method. For examples see [ArticlesTest](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit5/src/test/java/au/com/dius/pact/consumer/junit5/ArticlesTest.java) and [MultiTest](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit5/src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy). The `@PactTestFor` annotation allows you to control the mock server in the same way as the JUnit 4 `PactProviderRule`. It allows you to set the hostname to bind to (default is `localhost`) and the port (default is to use a random port). You can also set the Pact specification version to use (default is V3). ```java @ExtendWith(PactConsumerTestExt.class) @PactTestFor(providerName = "ArticlesProvider") public class ExampleJavaConsumerPactTest { ``` **NOTE on the hostname**: The mock server runs in the same JVM as the test, so the only valid values for hostname are: | hostname | result | | -------- | ------ | | `localhost` | binds to the address that localhost points to (normally the loopback adapter) | | `127.0.0.1` or `::1` | binds to the loopback adapter | | host name | binds to the default interface that the host machines DNS name resolves to | | `0.0.0.0` or `::` | binds to the all interfaces on the host machine | #### Matching the interactions by provider name If you set the `providerName` on the `@PactTestFor` annotation, then the first method with a `@Pact` annotation with the same provider name will be used. See [ArticlesTest](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit5/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](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit5/src/test/groovy/au/com/dius/pact/consumer/junit5/MultiTest.groovy) for an example. ### Injecting the mock server into the test You can get the mock server injected into the test method by adding a `MockServer` parameter to the test method. ```java @Test void test(MockServer mockServer) throws IOException { HttpResponse httpResponse = Request.Get(mockServer.getUrl() + "/articles.json").execute().returnResponse(); assertThat(httpResponse.getStatusLine().getStatusCode(), is(equalTo(200))); } ``` This helps with getting the base URL of the mock server, especially when a random port is used. ## Changing the directory pact files are written to By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.basedir}/target</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` ### Using `@PactDirectory` annotation You can override the directory the pacts are written in a test by adding the `@PactDirectory` annotation to the test class. ## Forcing pact files to be overwritten By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. # Having values injected from provider state callbacks You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods all you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/au.com.dius.pact.consumer:junit5:jar:4.4.0-beta.2", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ``` ## Overriding the expression markers `${` and `}` (4.1.25+) You can change the markers of the expressions using the following system properties: - `pact.expressions.start` (default is `${`) - `pact.expressions.end` (default is `}`) ## Using HTTPS You can enable a HTTPS mock server by setting `https=true` on the `@PactTestFor` annotation. Note that this mock server will use a self-signed certificate, so any client code will need to accept self-signed certificates. ## Using own KeyStore You can provide your own KeyStore file to be loaded on the MockServer. In order to do so you should fulfill the properties `keyStorePath`, `keyStoreAlias`, `keyStorePassword`, `privateKeyPassword` on the `@PactTestFor` annotation. Please bear in mind you should also enable HTTPS flag. ## Using multiple providers in a test (4.2.5+) It is advisable to focus on a single interaction with each test, but you can enable multiple providers in a single test. In this case, a separate mock server will be started for each configured provider. To enable this: 1. Create a method to create the Pact for each provider annotated with the `@Pact(provider = "....")` annotation. The provider name must be set on the annotation. You can create as many of these as required, but each must have a unique provider name. 2. In the test method, use the `pactMethods` attribute on the `@PactTestFor` annotation with the names of all the methods defined in step 1. 3. Add a MockServer parameter to the test method for each provider configured in step 1 with a `@ForProvider` annotation with the name of the provider. 4. In your test method, interact with each of the mock servers passed in step 3. Note that if any mock server does not get the requests it expects, it will fail the test. For an example, see [MultiProviderTest](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit5/src/test/groovy/au/com/dius/pact/consumer/junit5/MultiProviderTest.groovy). ## Dealing with persistent HTTP/1.1 connections (Keep Alive) As each test will get a new mock server, connections can not be persisted between tests. HTTP clients can cache connections with HTTP/1.1, and this can cause subsequent tests to fail. See [#342](https://github.com/pact-foundation/pact-jvm/issues/342) and [#1383](https://github.com/pact-foundation/pact-jvm/issues/1383). One option (if the HTTP client supports it, Apache HTTP Client does) is to set the system property `http.keepAlive` to `false` in the test JVM. The other option is to set `pact.mockserver.addCloseHeader` to `true` to force the mock server to send a `Connection: close` header with every response (supported with Pact-JVM 4.2.7+). # Testing messages You can use Pact to test interactions with messaging systems. There are two main types of message support: asynchronous messages and synchronous request/response messages. ## Asynchronous messages Asynchronous messages are you normal type of single shot or fire and forget type messages. They are typically sent to a message queue or topic as a notification or event. With Pact tests, we will be testing that our consumer of the messages works with the messages setup as the expectations in test. This should be the message handler code that processes the actual messages that come off the message queue in production. You can use either the V3 Message Pact or the V4 Asynchronous Message interaction to test these types of interactions. For a V3 message pact example, see [AsyncMessageTest](https://github.com/pact-foundation/pact-jvm/blob/ac6a0eae0b18183f6f453eafddb89b90741ace42/consumer/junit5/src/test/java/au/com/dius/pact/consumer/junit5/AsyncMessageTest.java). For a V4 asynchronous message example, see [V4AsyncMessageTest](https://github.com/pact-foundation/pact-jvm/blob/master/consumer/junit5/src/test/groovy/au/com/dius/pact/consumer/junit5/V4AsyncMessageTest.groovy). ### Matching message metadata You can also use matching rules for the metadata associated with the message. There is a `MetadataBuilder` class to help with this. You can access it via the `withMetadata` method that takes a Java Consumer on the `MessagePactBuilder` class. For example: ```java builder.given("SomeProviderState") .expectsToReceive("a test message with metadata") .withMetadata(md -> { md.add("metadata1", "metadataValue1"); md.add("metadata2", "metadataValue2"); md.add("metadata3", 10L); md.matchRegex("partitionKey", "[A-Z]{3}\\d{2}", "ABC01"); }) .withContent(body) .toPact(); ``` ### V4 Synchronous request/response messages Synchronous request/response messages are a form of message interchange were a request message is sent to another service and one or more response messages are returned. Examples of this would be things like Websockets and gRPC. For a V4 synchronous request/response message example, see [V4AsyncMessageTest](https://github.com/pact-foundation/pact-jvm/blob/master/consumer/junit5/src/test/groovy/au/com/dius/pact/consumer/junit5/V4SyncMessageTest.groovy). # Using Pact plugins (version 4.3.0+) The `PactBuilder` consumer test builder supports using Pact plugins. Plugins are defined in the [Pact plugins project](https://github.com/pact-foundation/pact-plugins). To use plugins requires the use of Pact specification V4 Pacts. To use a plugin, first you need to let the builder know to load the plugin (using the `usingPlugin` method) and then configure the interaction based on the requirements for the plugin. Each plugin may have different requirements, so you will have to consult the plugin docs on what is required. The plugins will be loaded from the plugin directory. By default, this is `~/.pact/plugins` or the value of the `PACT_PLUGIN_DIR` environment variable. Then you need to use the `with` method that takes a Map-based data structure and passed it on to the plugin to setup the interaction. For example, if we use the CSV plugin from the plugins project, our test would look like: ```java @ExtendWith(PactConsumerTestExt.class) class CsvClientTest { /** * Setup an interaction that makes a request for a CSV report */ @Pact(consumer = "CsvClient") V4Pact pact(PactBuilder builder) { return builder // Tell the builder to load the CSV plugin .usingPlugin("csv") // Interaction we are expecting to receive .expectsToReceive("request for a report", "core/interaction/http") // Data for the interaction. This will be sent to the plugin .with(Map.of( "request.path", "/reports/report001.csv", "response.status", "200", "response.contents", Map.of( "pact:content-type", "text/csv", "csvHeaders", false, "column:1", "matching(type,'Name')", "column:2", "matching(number,100)", "column:3", "matching(datetime, 'yyyy-MM-dd','2000-01-01')" ) )) .toPact(); } /** * Test to get the CSV report */ @Test @PactTestFor(providerName = "CsvServer", pactMethod = "pact") void getCsvReport(MockServer mockServer) throws IOException { // Setup our CSV client class to point to the Pact mock server CsvClient client = new CsvClient(mockServer.getUrl()); // Fetch the CSV report List<CSVRecord> csvData = client.fetch("report001.csv", false); // Verify it is as expected assertThat(csvData.size(), is(1)); assertThat(csvData.get(0).get(0), is(equalTo("Name"))); assertThat(csvData.get(0).get(1), is(equalTo("100"))); assertThat(csvData.get(0).get(2), matchesRegex("\\d{4}-\\d{2}-\\d{2}")); } } ``` # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

junit

au.com.dius.pact.consumer : junit

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.pact.consumer` * artifact-id = `junit` * version-id = `4.2.9` ## Usage ### Using the base ConsumerPactTest To write a pact spec extend ConsumerPactTest. This base class defines the following four methods which must be overridden in your test class. * *providerName:* Returns the name of the API provider that Pact will mock * *consumerName:* Returns the name of the API consumer that we are testing. * *createFragment:* Returns the PactFragment containing the interactions that the test setup using the ConsumerPactBuilder DSL * *runTest:* The actual test run. It receives the URL to the mock server as a parameter. Here is an example: ```java import au.com.dius.pact.consumer.dsl.PactDslWithProvider; import au.com.dius.pact.consumer.junit.exampleclients.ConsumerClient; import au.com.dius.pact.consumer.ConsumerPactTest; import au.com.dius.pact.model.PactFragment; import org.junit.Assert; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static org.junit.Assert.assertEquals; public class ExampleJavaConsumerPactTest extends ConsumerPactTest { @Override protected RequestResponsePact createFragment(PactDslWithProvider builder) { Map<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, PactTestExecutionContext context) 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 PactProviderRule mockProvider = new PactProviderRule("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(); } ``` 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); } ``` 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](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/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](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/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 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](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/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](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit/src/test/java/org/apache/http/client/fluent/InsecureHttpsRequest.java). ### Requiring the mock server to run with HTTPS with a keystore The mock server can be started running with HTTPS using a keystore. To enable this set the `https` parameter to `true`, set the keystore path/file, and the keystore'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](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/pactproviderrule/PactProviderHttpsKeystoreTest.java). ### Setting default expected request and response values If you have a lot of tests that may share some values (like headers), you can setup default values that will be applied to all the expected requests and responses for the tests. To do this, you need to create a method that takes single parameter of the appropriate type (`PactDslRequestWithoutPath` or `PactDslResponse`) and annotate it with the default marker annotation (`@DefaultRequestValues` or `@DefaultResponseValues`). For example: ```java @DefaultRequestValues public void defaultRequestValues(PactDslRequestWithoutPath request) { Map<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](https://github.com/DiUS/pact-jvm/blob/master/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/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.junit.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, context) -> { 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](/consumer/java8/README.md). 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 | | nullValue | Matches the JSON Null value | _\* Note:_ JSON only supports double precision floating point values. Depending on the language implementation, they may be parsed as integer, floating point or decimal numbers. #### Ensuring all items in a list match an example Lots of the time you might not know the number of items that will be in a list, but you want to ensure that the list has a minimum or maximum size and that each item in the list matches a given example. You can do this with the `arrayLike`, `minArrayLike` and `maxArrayLike` functions. | function | description | |----------|-------------| | `eachLike` | Ensure that each item in the list matches the provided example | | `maxArrayLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `minArrayLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java DslPart body = new PactDslJsonBody() .minArrayLike("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. 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(); ``` #### Ignoring the list order (V4 specification) If the order of the list items is not known, you can use the `unorderedArray` matcher functions. These will match the actual list against the expected one, except will match the items in any order. | function | description | |----------|-------------| | `unorderedArray` | Ensure that the list matches the provided example, ignoring the order | | `unorderedMinArray` | Ensure that the list matches the provided example and the list is not smaller than the provided min | | `unorderedMaxArray` | Ensure that the list matches the provided example and the list is no bigger than the provided max | | `unorderedMinMaxArray` | Ensure that the list matches the provided example and the list is constrained to the provided min and max | #### Array contains matcher (V4 specification) The array contains matcher functions allow you to match the actual list against a list of required variants. These work by matching each item against the variants, and the matching succeeds if each variant matches at least one item. Order of items in the list is not important. The variants can have a totally different structure, and can have their own matching rules to apply. For an example of how these can be used to match a hypermedia format like Siren, see [Example Pact + Siren project](https://github.com/pactflow/example-siren). | function | description | |----------|-------------| | `arrayContaining` | Matches the items in an array against a number of variants. Matching is successful if each variant occurs once in the array. Variants may be objects containing matching rules. | ```java .arrayContaining("actions") .object() .stringValue("name", "update") .stringValue("method", "PUT") .matchUrl("href", "http://localhost:9000", "orders", regex("\\d+", "1234")) .closeObject() .object() .stringValue("name", "delete") .stringValue("method", "DELETE") .matchUrl("href", "http://localhost:9000", "orders", regex("\\d+", "1234")) .closeObject() .closeArray() ``` #### Root level arrays that match all items If the root of the body is an array, you can create PactDslJsonArray classes with the following methods: | function | description | |----------|-------------| | `arrayEachLike` | Ensure that each item in the list matches the provided example | | `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java PactDslJsonArray.arrayEachLike() .date("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 } ] ``` You can specify the number of example items to generate in the array. The default is 1. #### Matching JSON values at the root For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("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 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 [ArticlesTest](https://github.com/pact-foundation/pact-jvm/blob/master/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/examples/ArticlesTest.java). #### 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). ### Overriding the handling of a body data type **NOTE: version 4.1.3+** By default, bodies will be handled based on their content types. For binary contents, the bodies will be base64 encoded when written to the Pact file and then decoded again when the file is loaded. You can change this with an override property: `pact.content_type.override.<TYPE>.<SUBTYPE>=text|binary|json`. For instance, setting `pact.content_type.override.application.pdf=text` will treat PDF bodies as a text type and not encode/decode them. ### Matching on paths You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide a real path as a second value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("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 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 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 By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory" } ``` For maven, use the systemPropertyVariables configuration: ```xml <project> [...] <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.18</version> <configuration> <systemPropertyVariables> <pact.rootDir>some/other/directory</pact.rootDir> <buildDirectory>${project.basedir}/target</buildDirectory> [...] </systemPropertyVariables> </configuration> </plugin> </plugins> </build> [...] </project> ``` For SBT: ```scala fork in Test := true, javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory") ``` ### Using `@PactDirectory` annotation You can override the directory the pacts are written in a test by adding the `@PactDirectory` annotation to the test class. ## Forcing pact files to be overwritten (3.6.5+) By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. # Publishing your pact files to a pact broker If you use Gradle, you can use the [pact Gradle plugin](/provider/gradle/README.md#publishing-pact-files-to-a-pact-broker) to publish your pact files. # Pact Specification V3 Version 3 of the pact specification changes the format of pact files in the following ways: * Query parameters are stored in a map form and are un-encoded (see [#66](https://github.com/DiUS/pact-jvm/issues/66) and [#97](https://github.com/DiUS/pact-jvm/issues/97) for information on what this can cause). * Introduces a new message pact format for testing interactions via a message queue. * Multiple provider states can be defined with data parameters. ## Generating V2 spec pact files To have your consumer tests generate V2 format pacts, you can set the specification version to V2. If you're using the `ConsumerPactTest` base class, you can override the `getSpecificationVersion` method. For example: ```java @Override protected PactSpecVersion getSpecificationVersion() { return PactSpecVersion.V2; } ``` If you are using the `PactProviderRule`, you can pass the version into the constructor for the rule. ```java @Rule public PactProviderRule mockTestProvider = new PactProviderRule("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/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/v3/ExampleMessageConsumerTest.java) ### Matching message metadata You can also use matching rules for the metadata associated with the message. There is a `MetadataBuilder` class to help with this. You can access it via the `withMetadata` method that takes a Java Consumer on the `MessagePactBuilder` class. For example: ```java builder.given("SomeProviderState") .expectsToReceive("a test message with metadata") .withMetadata(md -> { md.add("metadata1", "metadataValue1"); md.add("metadata2", "metadataValue2"); md.add("metadata3", 10L); md.matchRegex("partitionKey", "[A-Z]{3}\\d{2}", "ABC01"); }) .withContent(body) .toPact(); ``` # Having values injected from provider state callbacks (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods all you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/au.com.dius.pact.consumer:junit:jar:4.4.0-beta.2", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ``` ## Overriding the expression markers `${` and `}` (4.1.25+) You can change the markers of the expressions using the following system properties: - `pact.expressions.start` (default is `${`) - `pact.expressions.end` (default is `}`) ## Dealing with persistent HTTP/1.1 connections (Keep Alive) As each test will get a new mock server, connections can not be persisted between tests. HTTP clients can cache connections with HTTP/1.1, and this can cause subsequent tests to fail. See [#342](https://github.com/pact-foundation/pact-jvm/issues/342) and [#1383](https://github.com/pact-foundation/pact-jvm/issues/1383). One option (if the HTTP client supports it, Apache HTTP Client does) is to set the system property `http.keepAlive` to `false` in the test JVM. The other option is to set `pact.mockserver.addCloseHeader` to `true` to force the mock server to send a `Connection: close` header with every response (supported with Pact-JVM 4.2.7+). # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

groovy

au.com.dius.pact.consumer : groovy

pact-jvm-consumer-groovy ========================= Groovy DSL for Pact JVM ## Dependency The library is available on maven central using: * group-id = `au.com.dius.pact.consumer` * artifact-id = `groovy` * version-id = `4.1.0` ## Usage Add the `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.consumer:groovy:4.1.0' } In order to avoid the name collision between `au.com.dius.pact.consumer:groovy` and Groovy Gradle plugin's [automatic configuraiton of `groovyClasspath`](https://docs.gradle.org/current/userguide/groovy_plugin.html#sec:automatic_configuration_of_groovyclasspath) add the following configuration to your `build.gradle`: ```groovy compileTestGroovy { groovyClasspath = configurations.testCompileClasspath } ``` 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 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 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. 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. 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') ]) ``` An `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. #### Array contains matcher (V4 specification) The array contains matcher functions allow you to match the actual list against a list of required variants. These work by matching each item against the variants, and the matching succeeds if each variant matches at least one item. Order of items in the list is not important. The variants can have a totally different structure, and can have their own matching rules to apply. For an example of how these can be used to match a hypermedia format like Siren, see [Example Pact + Siren project](https://github.com/pactflow/example-siren). ```groovy actions arrayContaining([ { name 'update' method 'PUT' href url('http://localhost:9000', 'orders', regexp('\\d+', '1234')) }, { name 'delete' method 'DELETE' href url('http://localhost:9000', 'orders', regexp('\\d+', '1234')) } ]) ``` ### Matching any key in a map The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/313). In this case you can use the `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](https://github.com/DiUS/pact-jvm/blob/master/consumer/groovy/src/test/groovy/au/com/dius/pact/consumer/groovy/WildcardPactSpec.groovy). ### Matching with an OR 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 } ``` ### Overriding the handling of a body data type **NOTE: version 4.1.3+** By default, bodies will be handled based on their content types. For binary contents, the bodies will be base64 encoded when written to the Pact file and then decoded again when the file is loaded. You can change this with an override property: `pact.content_type.override.<TYPE>.<SUBTYPE>=text|json|binary`. For instance, setting `pact.content_type.override.application.pdf=text` will treat PDF bodies as a text type and not encode/decode them. ## Changing the directory pact files are written to By default, pact files are written to `target/pacts` (or `build/pacts` if you use Gradle), but this can be overwritten with the `pact.rootDir` system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests. For Gradle, add this to your build.gradle: ```groovy test { systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory" } ``` ## Forcing pact files to be overwritten (3.6.5+) By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. # Publishing your pact files to a pact broker If you use Gradle, you can use the [pact Gradle plugin](/provider/gradle/README.md#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 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 We have invoked the message handling code with a message from the Pact file, but we need to do a light-weight check that everything worked ok. In this example, we have recieved a "order confirmation message". The handler was meant to have processed the message and set the status of the corresponding order to "confirmed", so let's check that. ```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. # Having values injected from provider state callbacks (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The DSL method `fromProviderState` allows you to set an expression that will be parsed with the values returned from the provider states. For the body, you can use the key value instead of an expression. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```groovy service { given('User harry exists') uponReceiving('a request for user harry') withAttributes(method: 'get', path: fromProviderState('/api/user/au.com.dius.pact.consumer:groovy:jar:4.4.0-beta.2', '/api/user/100')) withBody { name(fromProviderState('userName', 'harry')) // looks up the value using the userName key } } ``` ## Overriding the expression markers `${` and `}` (4.1.25+) You can change the markers of the expressions using the following system properties: - `pact.expressions.start` (default is `${`) - `pact.expressions.end` (default is `}`) # Test Analytics We are tracking anonymous analytics to gather important usage statistics like JVM version and operating system. To disable tracking, set the 'pact_do_not_track' system property or environment variable to 'true'.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

provider

au.com.dius.pact : provider

Pact provider ============= The pact provider is responsible for verifying that an API provider adheres to a number of pacts authored by its clients This library provides the basic tools required to automate the process, and should be usable on its own in many instances. Framework and build tool specific bindings will be provided in separate libraries that build on top of this core functionality. ### Provider State Before each interaction is executed, the provider under test will have the opportunity to enter a state. Generally the state maps to a set of fixture data for mocking out services that the provider is a consumer of (they will have their own pacts) The pact framework will instruct the test server to enter that state by sending: POST "${config.stateChangeUrl.url}/setup" { "state" : "${interaction.stateName}" } ### An example of running provider verification with junit This example uses Groovy, JUnit 4 and Hamcrest matchers to run the provider verification. As the provider service is a DropWizard application, it uses the DropwizardAppRule to startup the service before running any test. **Warning:** It only grabs the first interaction from the pact file with the consumer, where there could be many. (This could possibly be solved with a parameterized test) ```groovy class ReadmeExamplePactJVMProviderJUnitTest { @ClassRule public static final TestRule startServiceRule = new DropwizardAppRule<DropwizardConfiguration>( TestDropwizardApplication, ResourceHelpers.resourceFilePath('dropwizard/test-config.yaml')) private static ProviderInfo serviceProvider private static Pact<RequestResponseInteraction> testConsumerPact private static ConsumerInfo consumer @BeforeClass static void setupProvider() { serviceProvider = new ProviderInfo('Dropwizard App') serviceProvider.setProtocol('http') serviceProvider.setHost('localhost') serviceProvider.setPort(8080) serviceProvider.setPath('/') consumer = new ConsumerInfo() consumer.setName('test_consumer') consumer.setPactSource(new UrlSource( ReadmeExamplePactJVMProviderJUnitTest.getResource('/pacts/zoo_app-animal_service.json').toString())) testConsumerPact = DefaultPactReader.INSTANCE.loadPact(consumer.getPactSource()) } @Test void runConsumerPacts() { // grab the first interaction from the pact with consumer Interaction interaction = testConsumerPact.interactions.get(0) // setup the verifier ProviderVerifier verifier = setupVerifier(interaction, serviceProvider, consumer) // setup any provider state // setup the client and interaction to fire against the provider ProviderClient client = new ProviderClient(serviceProvider, new HttpClientFactory()) Map<String, Object> failures = new HashMap<>() VerificationResult result = verifier.verifyResponseFromProvider(serviceProvider, interaction, interaction.getDescription(), failures, client) // normally assert all good, but in this example it will fail assertThat(failures, is(instanceOf(VerificationResult.Failed))) verifier.displayFailures(result) } private ProviderVerifier setupVerifier(Interaction interaction, ProviderInfo provider, ConsumerInfo consumer) { ProviderVerifier verifier = new ProviderVerifier() verifier.initialiseReporters(provider) verifier.reportVerificationForConsumer(consumer, provider, new UrlSource('http://example.example')) if (!interaction.getProviderStates().isEmpty()) { for (ProviderState providerState: interaction.getProviderStates()) { verifier.reportStateForInteraction(providerState.getName(), provider, consumer, true) } } verifier.reportInteractionDescription(interaction) return verifier } } ``` ### An example of running provider verification with spock This example uses groovy and spock to run the provider verification. Again the provider service is a DropWizard application, and is using the DropwizardAppRule to startup the service. This example runs all interactions using spocks Unroll feature ```groovy class ReadmeExamplePactJVMProviderSpockSpec extends Specification { @ClassRule @Shared TestRule startServiceRule = new DropwizardAppRule<DropwizardConfiguration>(TestDropwizardApplication, ResourceHelpers.resourceFilePath('dropwizard/test-config.yaml')) @Shared ProviderInfo serviceProvider ProviderVerifier verifier def setupSpec() { serviceProvider = new ProviderInfo('Dropwizard App') serviceProvider.protocol = 'http' serviceProvider.host = 'localhost' serviceProvider.port = 8080 serviceProvider.path = '/' serviceProvider.hasPactWith('zoo_app') { consumer -> consumer.pactSource = new FileSource(new File(ResourceHelpers.resourceFilePath('pacts/zoo_app-animal_service.json'))) } } def setup() { verifier = new ProviderVerifier() } def cleanup() { // cleanup provider state // ie. db.truncateAllTables() } def cleanupSpec() { // cleanup provider } @Unroll def "Provider Pact - With Consumer #consumer"() { expect: verifyConsumerPact(consumer) instanceof VerificationResult.Ok where: consumer << serviceProvider.consumers } private VerificationResult verifyConsumerPact(ConsumerInfo consumer) { verifier.initialiseReporters(serviceProvider) def result = verifier.runVerificationForConsumer([:], serviceProvider, consumer) if (result instanceof VerificationResult.Failed) { verifier.displayFailures([result]) } result } } ```

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

pact-jvm-server

au.com.dius.pact : pact-jvm-server

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. /publish -> For publishing contracts. It takes a contract from disk and publishes it to the configured broker ## Running the server 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 -b <value> | --broker <value> The baseUrl of the broker to publish contracts to (for example https://organization.broker.com -t <value | --token <value> API token for authentication to the pact broker --debug run with debug logging ``` ### Using trust store Trust store can be used. However, it is limited to a single port for the time being. ### Using a distribution archive You can download a [distribution from maven central](http://search.maven.org/remotecontent?filepath=au/com/dius/pact/pact-jvm-server/4.1.0/). 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: $ ./gradlew :pact-jvm-server:installdist This will create an app bundle in `build/install/pact-jvm-server`. You can then execute it with: $ java -jar pact-jvm-server/build/install/pact-jvm-server/lib/pact-jvm-server-4.0.1.jar or with the generated bundle script file: $ pact-jvm-server/build/install/pact-jvm-server/bin/pact-jvm-server 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. * The client will call `/publish` to publish the created contract to the configured pact broker ## 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. ### /publish Once all interactions have been tested the `/publish` endpoint can be called to publish the created pact to the pact broker For this it is required to run the pact-jvm-server with the -b parameter to configure the pact broker to publish the pacts to. Optionaly an authentication token can be used for authentication against the broker. For example: POST http://localhost:29999/publish '{ "consumer": "Zoo", "consumerVersion": "0.0.1", "provider": "Animal_Service" }' This will cause the Pact server to check for the pact `Zoo-Animal_Service.json` on disk under `target` and publish it to the configured pact broker. After a successful publish the pact will be removed from disk. ### / 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] }'

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

consumer

au.com.dius.pact : consumer

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.pact` * artifact-id = `consumer` * version-id = `4.2.x` ## 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 | | nullValue | Matches the JSON Null value | _\* Note:_ JSON only supports double precision floating point values. Depending on the language implementation, they may be parsed as integer, floating point or decimal numbers. #### Ensuring all items in a list match an example Lots of the time you might not know the number of items that will be in a list, but you want to ensure that the list has a minimum or maximum size and that each item in the list matches a given example. You can do this with the `arrayLike`, `minArrayLike` and `maxArrayLike` functions. | function | description | |----------|-------------| | `eachLike` | Ensure that each item in the list matches the provided example | | `maxArrayLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `minArrayLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java DslPart body = new PactDslJsonBody() .minArrayLike("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. #### Ignoring the list order (V4 specification) If the order of the list items is not known, you can use the `unorderedArray` matcher functions. These will match the actual list against the expected one, except will match the items in any order. | function | description | |----------|-------------| | `unorderedArray` | Ensure that the list matches the provided example, ignoring the order | | `unorderedMinArray` | Ensure that the list matches the provided example and the list is not smaller than the provided min | | `unorderedMaxArray` | Ensure that the list matches the provided example and the list is no bigger than the provided max | | `unorderedMinMaxArray` | Ensure that the list matches the provided example and the list is constrained to the provided min and max | #### Array contains matcher (V4 specification) The array contains matcher functions allow you to match the actual list against a list of required variants. These work by matching each item against the variants, and the matching succeeds if each variant matches at least one item. Order of items in the list is not important. The variants can have a totally different structure, and can have their own matching rules to apply. For an example of how these can be used to match a hypermedia format like Siren, see [Example Pact + Siren project](https://github.com/pactflow/example-siren). | function | description | |----------|-------------| | `arrayContaining` | Matches the items in an array against a number of variants. Matching is successful if each variant occurs once in the array. Variants may be objects containing matching rules. | ```java .arrayContaining("actions") .object() .stringValue("name", "update") .stringValue("method", "PUT") .matchUrl("href", "http://localhost:9000", "orders", regex("\\d+", "1234")) .closeObject() .object() .stringValue("name", "delete") .stringValue("method", "DELETE") .matchUrl("href", "http://localhost:9000", "orders", regex("\\d+", "1234")) .closeObject() .closeArray() ``` #### Matching JSON values at the root For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("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 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 | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMinLike` | 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 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 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 [ArticlesTest](https://github.com/pact-foundation/pact-jvm/blob/master/consumer/junit/src/test/java/au/com/dius/pact/consumer/junit/examples/ArticlesTest.java). ### Matching on paths You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide a real path as a second value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("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 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 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\"}") ``` # Forcing pact files to be overwritten By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. # Having values injected from provider state callbacks You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods allow you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/au.com.dius.pact:consumer:jar:4.4.0-beta.2", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ``` # A Lambda DSL for Pact This is an extension for the pact DSL. 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 }) }); ``` ## Usage Start with a static import of `LambdaDsl`. This class contains factory methods for the lambda dsl extension. When you come accross the `body()` method of `PactDslWithProvider` builder start using the new extensions. The call to `LambdaDsl` replaces the call to instance `new PactDslJsonArray()` and `new PactDslJsonBody()` of the pact library. ```java io.pactfoundation.consumer.dsl.LambdaDsl.* ``` ### Response body as json array ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonArray; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonArray((a) -> { a.stringValue("a1"); a.stringValue("a2"); }).build()); ``` ### Response body as json object ```java import static io.pactfoundation.consumer.dsl.LambdaDsl.newJsonBody; ... PactDslWithProvider builder = ... builder.given("some state") .uponReceiving("a request") .path("/my-app/my-service") .method("GET") .willRespondWith() .status(200) .body(newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build()); ``` ### Examples #### Simple Json object When creating simple json structures the difference between the two approaches isn't big. ##### JSON ```json { "bar": "Bar", "foo": "Foo" } ``` ##### Pact DSL ```java new PactDslJsonBody() .stringValue("foo", "Foo") .stringValue("bar", "Bar") ``` ##### Lambda DSL ```java newJsonBody((o) -> { o.stringValue("foo", "Foo"); o.stringValue("bar", "Bar"); }).build(); ``` #### An array of arrays When we come to more complex constructs with arrays and nested objects the beauty of lambdas become visible! ##### JSON ```json [ ["a1", "a2"], [1, 2], [{"foo": "Foo"}] ] ``` ##### Pact DSL ```java new PactDslJsonArray() .array() .stringValue("a1") .stringValue("a2") .closeArray() .array() .numberValue(1) .numberValue(2) .closeArray() .array() .object() .stringValue("foo", "Foo") .closeObject() .closeArray(); ``` ##### Lambda DSL ```java newJsonArray((rootArray) -> { rootArray.array((a) -> a.stringValue("a1").stringValue("a2")); rootArray.array((a) -> a.numberValue(1).numberValue(2)); rootArray.array((a) -> a.object((o) -> o.stringValue("foo", "Foo"))); }).build(); ``` ##### Kotlin Lambda DSL ```kotlin newJsonArray { newArray { stringValue("a1") stringValue("a2") } newArray { numberValue(1) numberValue(2) } newArray { newObject { stringValue("foo", "Foo") } } } ``` ## Dealing with persistent HTTP/1.1 connections (Keep Alive) As each test will get a new mock server, connections can not be persisted between tests. HTTP clients can cache connections with HTTP/1.1, and this can cause subsequent tests to fail. See [#342](https://github.com/pact-foundation/pact-jvm/issues/342) and [#1383](https://github.com/pact-foundation/pact-jvm/issues/1383). One option (if the HTTP client supports it, Apache HTTP Client does) is to set the system property `http.keepAlive` to `false` in the test JVM. The other option is to set `pact.mockserver.addCloseHeader` to `true` to force the mock server to send a `Connection: close` header with every response (supported with Pact-JVM 4.2.7+).

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

pact-specification-test

au.com.dius.pact : pact-specification-test

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.

Последняя версия: 4.4.0-beta.2

Дата: 27 апр. 2022 г.

Zemeckis Core Library

org.realityforge.zemeckis : zemeckis-core

Последняя версия: 0.14

Дата: 27 апр. 2022 г.

MRZ Java Parser

com.github.bordertech.mrz : mrz-java

Provides Java MRZ parser

Последняя версия: 0.8

Дата: 27 апр. 2022 г.

core

io.pact.plugin.driver : core

Pact Plugin Driver implementation

Последняя версия: 0.1.3

Дата: 27 апр. 2022 г.

api-repository

com.tencent.bk.repo : api-repository

Последняя версия: 1.0.0

Дата: 27 апр. 2022 г.

api-auth

com.tencent.bk.repo : api-auth

Последняя версия: 1.0.0

Дата: 27 апр. 2022 г.

cosmos

com.immomo.baseutil : mmdevice

project description

Последняя версия: 3.0.0

Дата: 27 апр. 2022 г.

The Annotation processor

org.realityforge.grim : grim-processor

Последняя версия: 0.09

Дата: 27 апр. 2022 г.

The assertion library

org.realityforge.grim : grim-asserts

Последняя версия: 0.09

Дата: 27 апр. 2022 г.

The annotations

org.realityforge.grim : grim-annotations

Последняя версия: 0.09

Дата: 27 апр. 2022 г.

id-sdk

com.gitee.tinyservices : id-sdk

Последняя версия: 1.0.0

Дата: 27 апр. 2022 г.

id-core

com.gitee.tinyservices : id-core

Последняя версия: 1.0.0

Дата: 27 апр. 2022 г.

api-webhook

com.tencent.bk.repo : api-webhook

Последняя версия: 1.0.0

Дата: 27 апр. 2022 г.

id-common

com.gitee.tinyservices : id-common

Последняя версия: 1.0.0

Дата: 27 апр. 2022 г.

tinyservices-id

com.gitee.tinyservices : tinyservices-id

Последняя версия: 1.0.0

Дата: 27 апр. 2022 г.

kala-template

org.glavo.kala : kala-template

Kala Platform

Последняя версия: 0.1.0

Дата: 27 апр. 2022 г.

Arcus Java Client

com.jam2in.arcus : arcus-java-client

Java client for Arcus memcached

Последняя версия: 1.13.3

Дата: 27 апр. 2022 г.

common-util

kr.jadekim : common-util

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

common-util

kr.jadekim : common-util-jvm

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

common-util

kr.jadekim : common-util-js

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

common-hash

kr.jadekim : common-hash

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

common-hash

kr.jadekim : common-hash-jvm

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

common-hash

kr.jadekim : common-hash-js

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

common-exception

kr.jadekim : common-exception

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

participant-state-kvutils-tools_2.13

com.daml : participant-state-kvutils-tools_2.13

TBD

Последняя версия: 2.2.0-snapshot.20220426.9797.0.00c944ae

Дата: 27 апр. 2022 г.

participant-state-kvutils-app_2.13

com.daml : participant-state-kvutils-app_2.13

TBD

Последняя версия: 2.2.0-snapshot.20220426.9797.0.00c944ae

Дата: 27 апр. 2022 г.

kvutils-tests-lib_2.13

com.daml : kvutils-tests-lib_2.13

TBD

Последняя версия: 2.2.0-snapshot.20220426.9797.0.00c944ae

Дата: 27 апр. 2022 г.

participant-state-kvutils_2.13

com.daml : participant-state-kvutils_2.13

TBD

Последняя версия: 2.2.0-snapshot.20220426.9797.0.00c944ae

Дата: 27 апр. 2022 г.

common-exception

kr.jadekim : common-exception-jvm

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.

participant-state-kvutils-proto

com.daml : participant-state-kvutils-proto

TBD

Последняя версия: 2.2.0-snapshot.20220426.9797.0.00c944ae

Дата: 27 апр. 2022 г.

participant-state-kvutils-java-proto

com.daml : participant-state-kvutils-java-proto

TBD

Последняя версия: 2.2.0-snapshot.20220426.9797.0.00c944ae

Дата: 27 апр. 2022 г.

common-exception

kr.jadekim : common-exception-js

Kotlin Commons

Последняя версия: 2.0.3-alpha1

Дата: 27 апр. 2022 г.