Pact consumer
=============

Pact Consumer is used by projects that are consumers of an API.

Most projects will want to use pact-consumer via one of the test framework specific projects. If your favourite
framework is not implemented, this module should give you all the hooks you need.

Provides a DSL for use with Java to build consumer pacts.

## Dependency

The library is available on maven central using:

* group-id = `au.com.dius`
* artifact-id = `pact-jvm-consumer_2.11`

## DSL Usage

Example in a JUnit test:

```java
import au.com.dius.pact.model.MockProviderConfig;
import au.com.dius.pact.model.RequestResponsePact;
import org.apache.http.entity.ContentType;
import org.jetbrains.annotations.NotNull;
import org.junit.Test;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

import static au.com.dius.pact.consumer.ConsumerPactRunnerKt.runConsumerTest;
import static org.junit.Assert.assertEquals;

public class PactTest {

  @Test
  public void testPact() {
    RequestResponsePact pact = ConsumerPactBuilder
      .consumer(&quot;Some Consumer&quot;)
      .hasPactWith(&quot;Some Provider&quot;)
      .uponReceiving(&quot;a request to say Hello&quot;)
      .path(&quot;/hello&quot;)
      .method(&quot;POST&quot;)
      .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;)
      .willRespondWith()
      .status(200)
      .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;)
      .toPact();

    MockProviderConfig config = MockProviderConfig.createDefault();
    PactVerificationResult result = runConsumerTest(pact, config, new PactTestRun() {
      @Override
      public void run(@NotNull MockServer mockServer) throws IOException {
        Map expectedResponse = new HashMap();
        expectedResponse.put(&quot;hello&quot;, &quot;harry&quot;);
        assertEquals(expectedResponse, new ConsumerClient(mockServer.getUrl()).post(&quot;/hello&quot;,
            &quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;, ContentType.APPLICATION_JSON));
      }
    });

    if (result instanceof PactVerificationResult.Error) {
      throw new RuntimeException(((PactVerificationResult.Error)result).getError());
    }

    assertEquals(PactVerificationResult.Ok.INSTANCE, result);
  }

}
```

The DSL has the following pattern:

```java
.consumer(&quot;Some Consumer&quot;)
.hasPactWith(&quot;Some Provider&quot;)
.given(&quot;a certain state on the provider&quot;)
    .uponReceiving(&quot;a request for something&quot;)
        .path(&quot;/hello&quot;)
        .method(&quot;POST&quot;)
        .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;)
    .willRespondWith()
        .status(200)
        .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;)
    .uponReceiving(&quot;another request for something&quot;)
        .path(&quot;/hello&quot;)
        .method(&quot;POST&quot;)
        .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;)
    .willRespondWith()
        .status(200)
        .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;)
    .
    .
    .
.toPact()
```

You can define as many interactions as required. Each interaction starts with `uponReceiving` followed by `willRespondWith`.
The test state setup with `given` is a mechanism to describe what the state of the provider should be in before the provider
is verified. It is only recorded in the consumer tests and used by the provider verification tasks.

### Building JSON bodies with PactDslJsonBody DSL

The body method of the ConsumerPactBuilder can accept a PactDslJsonBody, which can construct a JSON body as well as
define regex and type matchers.

For example:

```java
PactDslJsonBody body = new PactDslJsonBody()
    .stringType(&quot;name&quot;)
    .booleanType(&quot;happy&quot;)
    .hexValue(&quot;hexCode&quot;)
    .id()
    .ipAddress(&quot;localAddress&quot;)
    .numberValue(&quot;age&quot;, 100)
    .timestamp();
```

#### DSL Matching methods

The following matching methods are provided with the DSL. In most cases, they take an optional value parameter which
will be used to generate example values (i.e. when returning a mock response). If no example value is given, a random
one will be generated.

| method | description |
|--------|-------------|
| string, stringValue | Match a string value (using string equality) |
| number, numberValue | Match a number value (using Number.equals)\* |
| booleanValue | Match a boolean value (using equality) |
| stringType | Will match all Strings |
| numberType | Will match all numbers\* |
| integerType | Will match all numbers that are integers (both ints and longs)\* |
| decimalType | Will match all real numbers (floating point and decimal)\* |
| booleanType | Will match all boolean values (true and false) |
| stringMatcher | Will match strings using the provided regular expression |
| timestamp | Will match string containing timestamps. If a timestamp format is not given, will match an ISO timestamp format |
| date | Will match string containing dates. If a date format is not given, will match an ISO date format |
| time | Will match string containing times. If a time format is not given, will match an ISO time format |
| ipAddress | Will match string containing IP4 formatted address. |
| id | Will match all numbers by type |
| hexValue | Will match all hexadecimal encoded strings |
| uuid | Will match strings containing UUIDs |
| includesStr | Will match strings containing the provided string |
| equalsTo | Will match using equals |
| matchUrl | Defines a matcher for URLs, given the base URL path and a sequence of path fragments. The path fragments could be
             strings or regular expression matchers |

_\* Note:_ JSON only supports double precision floating point values. Depending on the language implementation, they
may parsed as integer, floating point or decimal numbers.

#### Ensuring all items in a list match an example (2.2.0+)

Lots of the time you might not know the number of items that will be in a list, but you want to ensure that the list
has a minimum or maximum size and that each item in the list matches a given example. You can do this with the `arrayLike`,
`minArrayLike` and `maxArrayLike` functions.

| function | description |
|----------|-------------|
| `eachLike` | Ensure that each item in the list matches the provided example |
| `maxArrayLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max |
| `minArrayLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min |

For example:

```java
    DslPart body = new PactDslJsonBody()
        .minArrayLike(&quot;users&quot;)
            .id()
            .stringType(&quot;name&quot;)
        .closeObject()
        .closeArray();
```

This will ensure that the users list is never empty and that each user has an identifier that is a number and a name that is a string.


#### Matching JSON values at the root (Version 3.2.2/2.4.3+)

For cases where you are expecting basic JSON values (strings, numbers, booleans and null) at the root level of the body
and need to use matchers, you can use the `PactDslJsonRootValue` class. It has all the DSL matching methods for basic
values that you can use.

For example:

```java
.consumer(&quot;Some Consumer&quot;)
.hasPactWith(&quot;Some Provider&quot;)
    .uponReceiving(&quot;a request for a basic JSON value&quot;)
        .path(&quot;/hello&quot;)
    .willRespondWith()
        .status(200)
        .body(PactDslJsonRootValue.integerType())
```

#### Root level arrays that match all items (version 2.2.11+)

If the root of the body is an array, you can create PactDslJsonArray classes with the following methods:

| function | description |
|----------|-------------|
| `arrayEachLike` | Ensure that each item in the list matches the provided example |
| `arrayMinLike` | Ensure that each item in the list matches the provided example and the list is no bigger than the provided max |
| `arrayMaxLike` | Ensure that each item in the list matches the provided example and the list is no smaller than the provided min |

For example:

```java
PactDslJsonArray.arrayEachLike()
    .date(&quot;clearedDate&quot;, &quot;mm/dd/yyyy&quot;, date)
    .stringType(&quot;status&quot;, &quot;STATUS&quot;)
    .decimalType(&quot;amount&quot;, 100.0)
.closeObject()
```

This will then match a body like:

```json
[ {
  &quot;clearedDate&quot; : &quot;07/22/2015&quot;,
  &quot;status&quot; : &quot;C&quot;,
  &quot;amount&quot; : 15.0
}, {
  &quot;clearedDate&quot; : &quot;07/22/2015&quot;,
  &quot;status&quot; : &quot;C&quot;,
  &quot;amount&quot; : 15.0
}, {

  &quot;clearedDate&quot; : &quot;07/22/2015&quot;,
  &quot;status&quot; : &quot;C&quot;,
  &quot;amount&quot; : 15.0
} ]
```

#### Matching arrays of arrays (version 3.2.12/2.4.14+)

For the case where you have arrays of arrays (GeoJSON is an example), the following methods have been provided:

| function | description |
|----------|-------------|
| `eachArrayLike` | Ensure that each item in the array is an array that matches the provided example |
| `eachArrayWithMaxLike` | Ensure that each item in the array is an array that matches the provided example and the array is no bigger than the provided max |
| `eachArrayWithMinLike` | Ensure that each item in the array is an array that matches the provided example and the array is no smaller than the provided min |

For example (with GeoJSON structure):

```java
new PactDslJsonBody()
  .stringType(&quot;type&quot;,&quot;FeatureCollection&quot;)
  .eachLike(&quot;features&quot;)
    .stringType(&quot;type&quot;,&quot;Feature&quot;)
    .object(&quot;geometry&quot;)
      .stringType(&quot;type&quot;,&quot;Point&quot;)
      .eachArrayLike(&quot;coordinates&quot;) // coordinates is an array of arrays 
        .decimalType(-7.55717)
        .decimalType(49.766896)
      .closeArray()
      .closeArray()
    .closeObject()
    .object(&quot;properties&quot;)
      .stringType(&quot;prop0&quot;,&quot;value0&quot;)
    .closeObject()
  .closeObject()
  .closeArray()
```

This generated the following JSON:

```json
{
  &quot;features&quot;: [
    {
      &quot;geometry&quot;: {
        &quot;coordinates&quot;: [[-7.55717, 49.766896]],
        &quot;type&quot;: &quot;Point&quot;
      },
      &quot;type&quot;: &quot;Feature&quot;,
      &quot;properties&quot;: { &quot;prop0&quot;: &quot;value0&quot; }
    }
  ],
  &quot;type&quot;: &quot;FeatureCollection&quot;
}
```

and will be able to match all coordinates regardless of the number of coordinates.

#### Matching any key in a map (3.3.1/2.5.0+)

The DSL has been extended for cases where the keys in a map are IDs. For an example of this, see 
[#313](https://github.com/DiUS/pact-jvm/issues/313). In this case you can use the `eachKeyLike` method, which takes an 
example key as a parameter.

For example:

```java
DslPart body = new PactDslJsonBody()
  .object(&quot;one&quot;)
    .eachKeyLike(&quot;001&quot;, PactDslJsonRootValue.id(12345L)) // key like an id mapped to a matcher
  .closeObject()
  .object(&quot;two&quot;)
    .eachKeyLike(&quot;001-A&quot;) // key like an id where the value is matched by the following example
      .stringType(&quot;description&quot;, &quot;Some Description&quot;)
    .closeObject()
  .closeObject()
  .object(&quot;three&quot;)
    .eachKeyMappedToAnArrayLike(&quot;001&quot;) // key like an id mapped to an array where each item is matched by the following example
      .id(&quot;someId&quot;, 23456L)
      .closeObject()
    .closeArray()
  .closeObject();

```

For an example, have a look at [WildcardKeysTest](../pact-jvm-consumer-junit/src/test/java/au/com/dius/pact/consumer/WildcardKeysTest.java).

**NOTE:** The `eachKeyLike` method adds a `*` to the matching path, so the matching definition will be applied to all keys
 of the map if there is not a more specific matcher defined for a particular key. Having more than one `eachKeyLike` condition
 applied to a map will result in only one being applied when the pact is verified (probably the last).
 
**Further Note: From version 3.5.22 onwards pacts with wildcards applied to map keys will require the Java system property 
&quot;pact.matching.wildcard&quot; set to value &quot;true&quot; when the pact file is verified.**

### Matching on paths (version 2.1.5+)

You can use regular expressions to match incoming requests. The DSL has a `matchPath` method for this. You can provide
a real path as a second value to use when generating requests, and if you leave it out it will generate a random one
from the regular expression.

For example:

```java
  .given(&quot;test state&quot;)
    .uponReceiving(&quot;a test interaction&quot;)
        .matchPath(&quot;/transaction/[0-9]+&quot;) // or .matchPath(&quot;/transaction/[0-9]+&quot;, &quot;/transaction/1234567890&quot;)
        .method(&quot;POST&quot;)
        .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;)
    .willRespondWith()
        .status(200)
        .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;)
```

### Matching on headers (version 2.2.2+)

You can use regular expressions to match request and response headers. The DSL has a `matchHeader` method for this. You can provide
an example header value to use when generating requests and responses, and if you leave it out it will generate a random one
from the regular expression.

For example:

```java
  .given(&quot;test state&quot;)
    .uponReceiving(&quot;a test interaction&quot;)
        .path(&quot;/hello&quot;)
        .method(&quot;POST&quot;)
        .matchHeader(&quot;testreqheader&quot;, &quot;test.*value&quot;)
        .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;)
    .willRespondWith()
        .status(200)
        .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;)
        .matchHeader(&quot;Location&quot;, &quot;.*/hello/[0-9]+&quot;, &quot;/hello/1234&quot;)
```

### Matching on query parameters (version 3.3.7+)

You can use regular expressions to match request query parameters. The DSL has a `matchQuery` method for this. You can provide
an example value to use when generating requests, and if you leave it out it will generate a random one
from the regular expression.

For example:

```java
  .given(&quot;test state&quot;)
    .uponReceiving(&quot;a test interaction&quot;)
        .path(&quot;/hello&quot;)
        .method(&quot;POST&quot;)
        .matchQuery(&quot;a&quot;, &quot;\\d+&quot;, &quot;100&quot;)
        .matchQuery(&quot;b&quot;, &quot;[A-Z]&quot;, &quot;X&quot;)
        .body(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;)
    .willRespondWith()
        .status(200)
        .body(&quot;{\&quot;hello\&quot;: \&quot;harry\&quot;}&quot;)
```

# Forcing pact files to be overwritten (3.6.5+)

By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be 
overwritten, set the Java system property `pact.writer.overwrite` to `true`.

# Having values injected from provider state callbacks (3.6.11+)

You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers,
bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example
of where this would be useful is API calls that require an ID which would be auto-generated by the database on the
provider side, so there is no way to know what the ID would be beforehand.

The following DSL methods allow you to set an expression that will be parsed with the values returned from the provider states:

For JSON bodies, use `valueFromProviderState`.&lt;br/&gt;
For headers, use `headerFromProviderState`.&lt;br/&gt;
For query parameters, use `queryParameterFromProviderState`.&lt;br/&gt;
For paths, use `pathFromProviderState`.

For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that
specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an
expression for the path where the ID will be replaced with the value returned from the provider state callback.

```java
    .pathFromProviderState(&quot;/api/users/${id}&quot;, &quot;/api/users/100&quot;)
``` 

You can also just use the key instead of an expression:

```java
    .valueFromProviderState(&apos;userId&apos;, &apos;userId&apos;, 100) // will look value using userId as the key
```

META-INF

MANIFEST.MF

pact-jvm-consumer_2.12.kotlin_module

dius

pact

consumer

BaseMockServer$Companion.class

BaseMockServer$handle$1.class

BaseMockServer$handle$2.class

BaseMockServer$handle$3.class

BaseMockServer$runAndWritePact$1.class

BaseMockServer$runAndWritePact$2.class

BaseMockServer$start$1.class

BaseMockServer$start$2.class

BaseMockServer$stop$1.class

BaseMockServer.class

ConsumerPactBuilder.class

ConsumerPactRunner$.class

ConsumerPactRunner.class

ConsumerPactRunnerKt.class

DefaultMockProvider$.class

DefaultMockProvider.class

Headers.class

InvalidMatcherException.class

MessagePactBuilder$Companion.class

MessagePactBuilder.class

MockHttpServer.class

MockHttpServerKt$calculateCharset$1.class

MockHttpServerKt.class

MockHttpsServer.class

MockProvider.class

MockServer.class

MockServerException.class

Pact.class

PactConsumerConfig.class

PactError$.class

PactError.class

PactFolder.class

PactGenerator$.class

PactGenerator.class

PactMismatch$.class

PactMismatch.class

PactMismatchesException.class

PactSession$.class

PactSession.class

PactSessionResults$.class

PactSessionResults.class

PactTestExecutionContext.class

PactTestRun.class

PactVerificationResult$Error.class

PactVerificationResult$ExpectedButNotReceived.class

PactVerificationResult$Mismatches$getDescription$1.class

PactVerificationResult$Mismatches.class

PactVerificationResult$Ok.class

PactVerificationResult$PartialMismatch.class

PactVerificationResult$UnexpectedRequest.class

PactVerificationResult.class

PactVerified$.class

PactVerified.class

PrettyPrinter$.class

PrettyPrinter.class

ScalaCollectionUtils.class

StatefulMockProvider.class

TestRun.class

UnfilteredHttpsKeystoreMockProvider$Routes$$anonfun$intent$1.class

UnfilteredHttpsKeystoreMockProvider$Routes$.class

UnfilteredHttpsKeystoreMockProvider.class

UnfilteredHttpsMockProvider$Routes$$anonfun$intent$1.class

UnfilteredHttpsMockProvider$Routes$.class

UnfilteredHttpsMockProvider.class

UnfilteredMockProvider$Routes$$anonfun$intent$1.class

UnfilteredMockProvider$Routes$.class

UnfilteredMockProvider.class

UserCodeFailed$.class

UserCodeFailed.class

VerificationResult$.class

VerificationResult.class

ArrayOfPrimitivesBuilder.class

DateMatcher.class

Dsl.class

DslPart.class

EqualsMatcher.class

HexadecimalMatcher.class

IncludeMatcher.class

Matcher.class

Matchers.class

NullMatcher.class

PM.class

PactDslJsonArray.class

PactDslJsonBody.class

PactDslJsonRootValue.class

PactDslRequestBase.class

PactDslRequestWithPath.class

PactDslRequestWithoutPath.class

PactDslResponse.class

PactDslRootValue.class

See how Anthropic automated 95% of dependency reviews with Socket

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

pact-jvm-consumer_2.12

Travis Dixon

Ronald Holshausen

(Experimental) An ambiguous license classifier was found.

What is an ambiguous license classifier?

Ambiguous License Classifier

Source files are encoded using a non-standard text encoding.

What is bad text encoding?

Bad text encoding

Package version is not a valid semantic version (semver).

What is bad semver?

Bad semver

Package has dependencies with an invalid semantic version. This could be a sign of beta, low quality, or unmaintained dependencies.

What is bad dependency semver?

Bad dependency semver

Source files contain bidirectional unicode control characters. This could indicate a Trojan source supply chain attack. See: trojansource.codes for more information.

What are bidirectional unicode control characters?

Bidirectional unicode control characters

This package has multiple bin scripts with the same name. This can cause non-deterministic behavior when installing or could be a sign of a supply chain attack.

What is bin script confusion?

Bin script confusion

Semantic versions published out of chronological order.

What is a chronological version anomaly?

Chronological version anomaly

Project maintainer's SSH key has been compromised.

What is a compromised SSH key?

Compromised SSH key

(Experimental) Copyleft license information was found.

What do I need to know about license files?

Copyleft License

Contains a Critical Common Vulnerability and Exposure (CVE).

What is a critical CVE?

Title

Critical CVE

Contains a high severity Common Vulnerability and Exposure (CVE).

What is a CVE?

High CVE

Uses debug, reflection and dynamic code execution features.

What is debug access?

Debug access

The maintainer of the package marked it as deprecated. This could indicate that a single version should not be used, or that the package is no longer maintained and any new vulnerabilities will not be fixed.

What is a deprecated package?

Deprecated

(Experimental) Contains a known deprecated SPDX license exception.

What is a deprecated SPDX exception?

Deprecated SPDX exception

(Experimental) License is deprecated which may have legal implications regarding the package's use.

What is a deprecated license?

Deprecated license

Package name is similar to other popular packages and may not be the package you want.

What is a typosquat?

Possible typosquat attack

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

What is dynamic require?

Dynamic require

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

What is an empty package?

Empty package

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

What is environment variable access?

Environment variable access

(Experimental) Something was found which is explicitly marked as unlicensed.

Explicitly Unlicensed Item

Package optionally loads a dependency which is not specified within any of the package.json dependency fields. It may inadvertently be importing dependencies specified by other packages.

What are extraneous dependencies?

Name

Extraneous dependency

Contains a dependency which resolves to a file. This can obfuscate analysis and serves no useful purpose.

What are file dependencies?

File dependency

Accesses the file system, and could potentially read sensitive data.

What is filesystem access?

Filesystem access

Package has a dependency with a floating version range. This can cause issues if the dependency publishes a new major version.

What are wildcard dependencies?

Wildcard dependency

Contains a dependency which resolves to a remote git URL. Dependencies fetched from git URLs are not immutable and can be used to inject untrusted code or reduce the likelihood of a reproducible install.

What are git dependencies?

Git dependency

Contains a dependency which resolves to a GitHub URL. Dependencies fetched from GitHub specifiers are not immutable can be used to inject untrusted code or reduce the likelihood of a reproducible install.

What are GitHub dependencies?

GitHub dependency

AI has identified unusual behaviors that may pose a security risk.

What is an AI-detected potential code anomaly?

AI-detected potential code anomaly

AI has identified this package as a potential typosquat of a more popular package. This suggests that the package may be intentionally mimicking another package's name, description, or other metadata.

What is AI-detected potential typosquatting?

AI-detected possible typosquat

AI has identified this package as malware. This is a strong signal that the package may be malicious.

What is AI-detected potential malware?

AI-detected potential malware

AI has determined that this package may contain potential security issues or vulnerabilities.

What are AI-detected potential security risks?

AI-detected potential security risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Why is native code a concern?

Native code

Contains high entropy strings. This could be a sign of encrypted data, leaked secrets or obfuscated code.

What are high entropy strings?

High entropy strings

Contains unicode homoglyphs which can be used in supply chain confusion attacks.

What are unicode homoglyphs?

Unicode homoglyphs

au.com.dius:pact-jvm-consumer_2.12 - maven Package File explorer