au.com.dius:pact-jvm-consumer_2.12

Release 3.5.20

Pact consumer ============= Pact Consumer is used by projects that are consumers of an API. Most projects will want to use pact-consumer via one of the test framework specific projects. If your favourite framework is not implemented, this module should give you all the hooks you need. Provides a DSL for use with Java to build consumer pacts. ## Dependency The library is available on maven central using: * group-id = `au.com.dius` * artifact-id = `pact-jvm-consumer_2.11` ## DSL Usage Example in a JUnit test: ```java import au.com.dius.pact.model.MockProviderConfig; import au.com.dius.pact.model.RequestResponsePact; import org.apache.http.entity.ContentType; import org.jetbrains.annotations.NotNull; import org.junit.Test; import java.io.IOException; import java.util.HashMap; import java.util.Map; import static au.com.dius.pact.consumer.ConsumerPactRunnerKt.runConsumerTest; import static org.junit.Assert.assertEquals; public class PactTest { @Test public void testPact() { RequestResponsePact pact = ConsumerPactBuilder .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request to say Hello") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .toPact(); MockProviderConfig config = MockProviderConfig.createDefault(); PactVerificationResult result = runConsumerTest(pact, config, new PactTestRun() { @Override public void run(@NotNull MockServer mockServer) throws IOException { Map expectedResponse = new HashMap(); expectedResponse.put("hello", "harry"); assertEquals(expectedResponse, new ConsumerClient(mockServer.getUrl()).post("/hello", "{\"name\": \"harry\"}", ContentType.APPLICATION_JSON)); } }); if (result instanceof PactVerificationResult.Error) { throw new RuntimeException(((PactVerificationResult.Error)result).getError()); } assertEquals(PactVerificationResult.Ok.INSTANCE, result); } } ``` The DSL has the following pattern: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .given("a certain state on the provider") .uponReceiving("a request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .uponReceiving("another request for something") .path("/hello") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") . . . .toPact() ``` You can define as many interactions as required. Each interaction starts with `uponReceiving` followed by `willRespondWith`. The test state setup with `given` is a mechanism to describe what the state of the provider should be in before the provider is verified. It is only recorded in the consumer tests and used by the provider verification tasks. ### Building JSON bodies with PactDslJsonBody DSL The body method of the ConsumerPactBuilder can accept a PactDslJsonBody, which can construct a JSON body as well as define regex and type matchers. For example: ```java PactDslJsonBody body = new PactDslJsonBody() .stringType("name") .booleanType("happy") .hexValue("hexCode") .id() .ipAddress("localAddress") .numberValue("age", 100) .timestamp(); ``` #### DSL Matching methods The following matching methods are provided with the DSL. In most cases, they take an optional value parameter which will be used to generate example values (i.e. when returning a mock response). If no example value is given, a random one will be generated. | method | description | |--------|-------------| | string, stringValue | Match a string value (using string equality) | | number, numberValue | Match a number value (using Number.equals)\* | | booleanValue | Match a boolean value (using equality) | | stringType | Will match all Strings | | numberType | Will match all numbers\* | | integerType | Will match all numbers that are integers (both ints and longs)\* | | decimalType | Will match all real numbers (floating point and decimal)\* | | booleanType | Will match all boolean values (true and false) | | stringMatcher | Will match strings using the provided regular expression | | timestamp | Will match string containing timestamps. If a timestamp format is not given, will match an ISO timestamp format | | date | Will match string containing dates. If a date format is not given, will match an ISO date format | | time | Will match string containing times. If a time format is not given, will match an ISO time format | | ipAddress | Will match string containing IP4 formatted address. | | id | Will match all numbers by type | | hexValue | Will match all hexadecimal encoded strings | | uuid | Will match strings containing UUIDs | | includesStr | Will match strings containing the provided string | | equalsTo | Will match using equals | | matchUrl | Defines a matcher for URLs, given the base URL path and a sequence of path fragments. The path fragments could be strings or regular expression matchers | _\* Note:_ JSON only supports double precision floating point values. Depending on the language implementation, they may parsed as integer, floating point or decimal numbers. #### Ensuring all items in a list match an example (2.2.0+) Lots of the time you might not know the number of items that will be in a list, but you want to ensure that the list has a minimum or maximum size and that each item in the list matches a given example. You can do this with the `arrayLike`, `minArrayLike` and `maxArrayLike` functions. | function | description | |----------|-------------| | `eachLike` | Ensure that each item in the list matches the provided example | | `maxArrayLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `minArrayLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java DslPart body = new PactDslJsonBody() .minArrayLike("users") .id() .stringType("name") .closeObject() .closeArray(); ``` This will ensure that the users list is never empty and that each user has an identifier that is a number and a name that is a string. #### Matching JSON values at the root (Version 3.2.2/2.4.3+) For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic values that you can use. For example: ```java .consumer("Some Consumer") .hasPactWith("Some Provider") .uponReceiving("a request for a basic JSON value") .path("/hello") .willRespondWith() .status(200) .body(PactDslJsonRootValue.integerType()) ``` #### Root level arrays that match all items (version 2.2.11+) If the root of the body is an array, you can create PactDslJsonArray classes with the following methods: | function | description | |----------|-------------| | `arrayEachLike` | Ensure that each item in the list matches the provided example | | `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max | | `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min | For example: ```java PactDslJsonArray.arrayEachLike() .date("clearedDate", "mm/dd/yyyy", date) .stringType("status", "STATUS") .decimalType("amount", 100.0) .closeObject() ``` This will then match a body like: ```json [ { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 }, { "clearedDate" : "07/22/2015", "status" : "C", "amount" : 15.0 } ] ``` #### Matching arrays of arrays (version 3.2.12/2.4.14+) For the case where you have arrays of arrays (GeoJSON is an example), the following methods have been provided: | function | description | |----------|-------------| | `eachArrayLike` | Ensure that each item in the array is an array that matches the provided example | | `eachArrayWithMaxLike` | Ensure that each item in the array is an array that matches the provided example and the array is no bigger than the provided max | | `eachArrayWithMinLike` | Ensure that each item in the array is an array that matches the provided example and the array is no smaller than the provided min | For example (with GeoJSON structure): ```java new PactDslJsonBody() .stringType("type","FeatureCollection") .eachLike("features") .stringType("type","Feature") .object("geometry") .stringType("type","Point") .eachArrayLike("coordinates") // coordinates is an array of arrays .decimalType(-7.55717) .decimalType(49.766896) .closeArray() .closeArray() .closeObject() .object("properties") .stringType("prop0","value0") .closeObject() .closeObject() .closeArray() ``` This generated the following JSON: ```json { "features": [ { "geometry": { "coordinates": [[-7.55717, 49.766896]], "type": "Point" }, "type": "Feature", "properties": { "prop0": "value0" } } ], "type": "FeatureCollection" } ``` and will be able to match all coordinates regardless of the number of coordinates. #### Matching any key in a map (3.3.1/2.5.0+) The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see [#313](https://github.com/DiUS/pact-jvm/issues/313). In this case you can use the `eachKeyLike` method, which takes an example key as a parameter. For example: ```java DslPart body = new PactDslJsonBody() .object("one") .eachKeyLike("001", PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher .closeObject() .object("two") .eachKeyLike("001-A") // key like an id where the value is matched by the following example .stringType("description", "Some Description") .closeObject() .closeObject() .object("three") .eachKeyMappedToAnArrayLike("001") // key like an id mapped to an array where each item is matched by the following example .id("someId", 23456L) .closeObject() .closeArray() .closeObject(); ``` For an example, have a look at [WildcardKeysTest](../pact-jvm-consumer-junit/src/test/java/au/com/dius/pact/consumer/WildcardKeysTest.java). **NOTE:** The `eachKeyLike` method adds a `*` to the matching path, so the matching definition will be applied to all keys of the map if there is not a more specific matcher defined for a particular key. Having more than one `eachKeyLike` condition applied to a map will result in only one being applied when the pact is verified (probably the last). **Further Note: From version 3.5.22 onwards pacts with wildcards applied to map keys will require the Java system property "pact.matching.wildcard" set to value "true" when the pact file is verified.** ### Matching on paths (version 2.1.5+) You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide a real path as a second value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .matchPath("/transaction/[0-9]+") // or .matchPath("/transaction/[0-9]+", "/transaction/1234567890") .method("POST") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` ### Matching on headers (version 2.2.2+) You can use regular expressions to match request and response headers. The DSL has a `matchHeader` method for this. You can provide an example header value to use when generating requests and responses, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchHeader("testreqheader", "test.*value") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") .matchHeader("Location", ".*/hello/[0-9]+", "/hello/1234") ``` ### Matching on query parameters (version 3.3.7+) You can use regular expressions to match request query parameters. The DSL has a `matchQuery` method for this. You can provide an example value to use when generating requests, and if you leave it out it will generate a random one from the regular expression. For example: ```java .given("test state") .uponReceiving("a test interaction") .path("/hello") .method("POST") .matchQuery("a", "\\d+", "100") .matchQuery("b", "[A-Z]", "X") .body("{\"name\": \"harry\"}") .willRespondWith() .status(200) .body("{\"hello\": \"harry\"}") ``` # Forcing pact files to be overwritten (3.6.5+) By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property `pact.writer.overwrite` to `true`. # Having values injected from provider state callbacks (3.6.11+) You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand. The following DSL methods allow you to set an expression that will be parsed with the values returned from the provider states: For JSON bodies, use `valueFromProviderState`.<br/> For headers, use `headerFromProviderState`.<br/> For query parameters, use `queryParameterFromProviderState`.<br/> For paths, use `pathFromProviderState`. For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback. ```java .pathFromProviderState("/api/users/${id}", "/api/users/100") ``` You can also just use the key instead of an expression: ```java .valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key ```

Homepage Maven Kotlin Download

Keywords
consumer-driven-contracts, contract-testing, hacktoberfest, pact, smartbear-supported
License
Apache-2.0

Documentation

Pact-JVM

Pact-JVM Build Maven Central

JVM implementation of the consumer driven contract library pact.

From the Ruby Pact website:

Define a pact between service consumers and providers, enabling "consumer driven contract" testing.

Pact provides an RSpec DSL for service consumers to define the HTTP requests they will make to a service provider and the HTTP responses they expect back. These expectations are used in the consumers specs to provide a mock service provider. The interactions are recorded, and played back in the service provider specs to ensure the service provider actually does provide the response the consumer expects.

This allows testing of both sides of an integration point using fast unit tests.

This gem is inspired by the concept of "Consumer driven contracts". See https://martinfowler.com/articles/consumerDrivenContracts.html for more information.

Read Getting started with Pact for more information on how to get going.

Contact

Links

Tutorial (60 minutes)

Learn everything in Pact in 60 minutes: https://github.com/pact-foundation/pact-workshop-jvm-spring.

The workshop takes you through all of the key concepts of consumer and provider testing using a Spring boot application.

Documentation

Additional documentation can be found at docs.pact.io, in the Pact Wiki, and in the Pact-JVM wiki. Stack Overflow is also a good source of help, as is the Slack workspace.

Supported JDK and specification versions:

Branch Specification JDK Kotlin Version Latest Version Notes
4.6.x master V4 + plugins 17+ 1.8.22 4.6.6
4.5.x V4 + plugins 11+/17+(1) 1.7.20 4.5.8
4.1.x V3 8-12 1.3.72 4.1.42

Notes:

  • 1: Spring6 support library requires JDK 17+. The rest of Pact-JVM 4.5.x libs require 11+.

Previous versions (not actively supported)

Branch Specification JDK Kotlin Version Scala Versions Latest Version
4.4.x V4 + plugins 11+ 1.6.21 N/A 4.4.9
4.3.x V4 11+ 1.6.21 N/A 4.3.19
4.2.x V4 (1) 11-15 (2) 1.4.32 N/A 4.2.21
4.0.x V3 8-12 1.3.71 N/A 4.0.10
3.6.x V3 8 1.3.71 2.12 3.6.15
3.5.x V3 8 1.1.4-2 2.12, 2.11 3.5.25
3.5.x-jre7 V3 7 1.1.4-2 2.11 3.5.7-jre7.0
2.4.x V2 6 N/A 2.10, 2.11 2.4.20

Notes:

  • 1: V4 specification support is only partially implemented with 4.2.x
  • 2: v4.2.x may run on JDK 16, but the build for it does not.

NOTE: The JARs produced by this project have changed with 4.1.x to better align with Java 9 JPMS. The artefacts are now:

au.com.dius.pact:consumer
au.com.dius.pact.consumer:groovy
au.com.dius.pact.consumer:junit
au.com.dius.pact.consumer:junit5
au.com.dius.pact.consumer:java8
au.com.dius.pact.consumer:specs2_2.13
au.com.dius.pact:pact-jvm-server
au.com.dius.pact:provider
au.com.dius.pact.provider:scalatest_2.13
au.com.dius.pact.provider:spring
au.com.dius.pact.provider:maven
au.com.dius.pact:provider
au.com.dius.pact.provider:junit
au.com.dius.pact.provider:junit5
au.com.dius.pact.provider:scalasupport_2.13
au.com.dius.pact.provider:lein
au.com.dius.pact.provider:gradle
au.com.dius.pact.provider:specs2_2.13
au.com.dius.pact.provider:junit5spring
au.com.dius.pact.core:support
au.com.dius.pact.core:model
au.com.dius.pact.core:matchers
au.com.dius.pact.core:pactbroker

Service Consumers

Pact-JVM has a number of ways you can write your service consumer tests.

I Use Scala

You want to look at: pact4s.

I Use Java

You want to look at: junit for JUnit 4 tests and junit5 for JUnit 5 tests. Also, if you are using Java 11 or above, there is an updated DSL for consumer tests.

NOTE: If you are using Java 8, there is no separate Java 8 support library anymore, see the above library.

I Use Groovy or Grails

You want to look at: groovy or junit

(Use Clojure I)

Clojure can call out to Java, so have a look at junit. For an example look at example_clojure_consumer_pact_test.clj.

I Use some other jvm language or test framework

You want to look at: Consumer

My Consumer interacts with a Message Queue

As part of the V3 pact specification, we have defined a new pact file for interactions with message queues. For an implementation of a Groovy consumer test with a message pact, have a look at PactMessageBuilderSpec.groovy.

Service Providers

Once you have run your consumer tests, you will have generated some Pact files. You can then verify your service providers with these files.

I am writing a provider and want to ...

verify pacts with SBT

You want to look at: pact4s or scala-pact

verify pacts with Gradle

You want to look at: pact gradle plugin

verify pacts with Maven

You want to look at: pact maven plugin

verify pacts with JUnit tests

You want to look at: junit provider support for JUnit 4 tests and junit5 for JUnit 5 tests

verify pacts with Leiningen

You want to look at: pact leiningen plugin

verify pacts with a Spring MVC project

Have a look at spring or Spring MVC Pact Test Runner (Not maintained).

I want to verify pacts but don't want to use sbt or gradle or leiningen

You want to look at: provider

verify interactions with a message queue

As part of the V3 pact specification, we have defined a new pact file for interactions with message queues. The Gradle pact plugin supports a mechanism where you can verify V3 message pacts, have a look at pact gradle plugin. The JUnit pact library also supports verification of V3 message pacts, have a look at junit.

I Use Ruby or Go or something else

The pact-jvm libraries are pure jvm technologies and do not have any native dependencies.

However, if you have a ruby provider, the json produced by this library is compatible with the ruby pact library. You'll want to look at: Ruby Pact.

For .Net, there is Pact-net.

For JS, there is Pact-JS.

For Go, there is Pact-go.

For Rust, there is Pact-Rust.

Have a look at implementations in other languages.

I Use something completely different

There's a limit to how much we can help, however check out pact-jvm-server

How do I transport my pacts from consumers to providers?

You want to look at: Pact Broker

Which is a project that aims at providing tooling to coordinate pact generation and delivery between projects.

I want to contribute

Documentation for contributors is here.

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'.

Stats

Dependencies
0
Dependent packages
11
Dependent repositories
4
Total releases
41
Latest release
First release
Stars
1.06K
Forks
473
Watchers
77
Contributors
175
Repository size
16.4 MB
SourceRank
15

Development practices

Source repo 2FA enabled
TEXT!
Package manager 2FA enabled
TEXT!
Is security responsive
TEXT!
Dependencies are managed
TEXT!
Issue-free release available
TEXT!
Succession plan available
TEXT!
Package manager 2FA enabled
TEXT!

The Tidelift Subscription provides access to a continuously curated stream of human-researched and maintainer-verified data on open source packages and their licenses, releases, vulnerabilities, and development practices.

Learn more →

Releases

3.6.15
3.6.14
3.6.13
3.6.12
3.6.11
3.6.10
3.6.9
3.6.8
3.6.7
3.6.6
See all 41 releases

Contributors

Ron Holshausen Travis Dixon Ronald Holshausen Beth Skurrie Piotr Kubowicz Ken Scambler Timothy Jones Kristine Jetzke Alon Pe'er Yousaf Nabi Brent Barker Alex Soto alessio-tw João Farias George Kankava Ryan Dens Radek Koubsky anto Andrew Steffey Pavel Carl Zogheib BenjaminDebeerst Marc Paquette Matt Fellows


See all contributors

Something wrong with this page? Make a suggestion

Export .ABOUT file for this package

Last synced: 2023-12-01 05:40:43 UTC

Login to resync this project