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

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

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

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

## Dependency

The library is available on maven central using:

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

## DSL Usage

Example in a JUnit test:

```java
import au.com.dius.pact.model.MockProviderConfig;
import au.com.dius.pact.model.PactFragment;
import org.junit.Test;

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

import static org.junit.Assert.assertEquals;

public class PactTest {

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

        MockProviderConfig config = MockProviderConfig.createDefault();
        VerificationResult result = pactFragment.runConsumer(config, new TestRun() {
            @Override
            public void run(MockProviderConfig config) {
                Map expectedResponse = new HashMap();
                expectedResponse.put(&quot;hello&quot;, &quot;harry&quot;);
                try {
                    assertEquals(new ProviderClient(config.url()).hello(&quot;{\&quot;name\&quot;: \&quot;harry\&quot;}&quot;),
                            expectedResponse);
                } catch (IOException e) {}
            }
        });

        if (result instanceof PactError) {
            throw new RuntimeException(((PactError)result).error());
        }

        assertEquals(ConsumerPactTest.PACT_VERIFIED, result);
    }

}

```

The DSL has the following pattern:

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

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

### Building JSON bodies with PactDslJsonBody DSL

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

For example:

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

#### DSL Matching methods

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

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

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

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

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

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

For example:

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

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


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

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

For example:

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

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

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

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

For example:

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

This will then match a body like:

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

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

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

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

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

For example (with GeoJSON structure):

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

This generated the following JSON:

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

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

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

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

For example:

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

```

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

**NOTE:** The `eachKeyLike` method adds a `*` to the matching path, so the matching definition will be applied to all keys
 of the map if there is not a more specific matcher defined for a particular key. Having more than one `eachKeyLike` condition
 applied to a map will result in only one being applied when the pact is verified (probably the last).

### Matching on paths (version 2.1.5+)

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

For example:

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

### Matching on headers (version 2.2.2+)

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

For example:

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

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

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

For example:

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

Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team

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

pact-jvm-consumer_2.10

Travis Dixon

Ronald Holshausen

Inherit

Block

Ignore

Monitor

Warn

License

Maintenance

Miscellaneous

Quality

Supply chain risk

Vulnerability

Legal

Operational

Security

Are you sure you want to delete this note?

The **{{action}}** action was chosen based on the **{{actionSourceType}}**.

Admins only

Organization members

Dashboard

Grouping: Directs

Grouping: None

Artifact: <code>{{- fullArtifactDisplayName}}</code>

Dependency tree

<upgradeLink>Upgrade</upgradeLink> to access this feature

Achievements

Why Socket?

Blog

Customer Stories

Languages

Impersonation Mode Active

Update your browser to the latest version for the best experience.

Your web browser is outdated

Use another browser for the best experience.

Your web browser is unsupported

{{count, number}} commits last two months

{{count, number}} critical severity alert

{{count, number}} critical severity alerts

{{count, number}} dependency vulnerability

{{count, number}} dependency vulnerabilities

{{count, number}} development dependencies

{{count, number}} transitive dependencies

{{count, number}} version published last month

{{count, number}} versions published last month

{{count, number}} version published in last two months

{{count, number}} versions published in last two months

{{count, number}} version published last week

{{count, number}} versions published last week

{{count, number}} version published last year

{{count, number}} versions published last year

Socket undergoes annual SOC2 Type II audits. Socket customers can request a copy of the full SOC2 Type II report.

Allows organization owners and admins to access detailed records of actions taken by members of their organization, complete with timestamps.

Prevent compromised packages from infiltrating your supply chain by monitoring for changes in real-time.

Join our Discord community to get help from Socket engineers and other Socket users.

Compare millions of open source packages on socket.dev

Detect malicious code and risky behavior (e.g. network) in your dependencies using "deep package inspection"

All data is encrypted in transit and at rest using industry standard encryption algorithms.

Get a dedicated Socket account manager and access to Socket’s Customer Success team.

Get dedicated support from Socket engineers via email and Slack.

"Shift left" with the Socket Chrome extension and give intervene early, before developers choose risky or low quality dependencies.

Catch developers using risky dependencies and give them a "speed bump" to encourage good behavior

Install the Socket GitHub app to receive real-time dependency scanning and reports with every pull request.

Integrate Socket into your GitHub SCM to prevent risky dependencies from being installed.

Socket scans for vulnerabilities in your dependencies, including CVEs, security advisories, and more.

Socket supports dependencies in many languages, with most popular ecosystems coming in 2024. We've got you covered no matter what languages you use.

Enforce license policies across your organization

Receive a Microsoft Teams message to the channel of your choice anytime Socket runs a new analysis, has a new finding, or a policy has changed.

Get help migrating from Socket's free plan to Socket's paid plans.

Run Socket on-premises or in your own cloud environment.

Query for any dependency (at any version) across your entire organization

Integrate Socket into your CI/CD pipeline to prevent risky dependencies from being deployed to production.

Analyze an entire project to find supply chain risks

Tag projects to organize and filter your projects

Restrict access based on the roles of individual users within an organization.

Receive a Slack message to the channel of your choice anytime Socket runs a new analysis, has a new finding, or a policy has changed.

Socket is SOC2 Type II compliant and undergoes annual audits.

The Socket CLI allows teams to prevent risky dependencies from being installed, and to get dependency insights from the command line.

Socket supports SAML SSO for single sign-on and identity management.

Integrate Socket into your VS Code IDE to prevent risky dependencies from being installed.

Get a POST request anytime Socket runs a new analysis, has a new finding, or a policy has changed.

Socket will analyzed your SBOMs up to a maximum number of dependencies.

API that allows you to analyze a project, lookup package scores and alerts, and more.

Create API tokens to authenticate with the Socket API and CLI.

The number of developers in your team. A developer is someone who made a commit to your organization's repositories scanned by Socket in the past month.

Use Socket to protect your private repositories.

Socket is always free for open source projects.

Socket retains all reporting data for 3 months, 1 year, or a custom term of your choice.

Access the threat feed that powers Socket.

Unlimited scale, self-hosting, and priority support for large teams.

For open-source projects, individuals, and small teams.

For growing teams with enhanced scale, security, and support.

There is a package with a similar name that is downloaded much more often.

There are packages with similar names that are downloaded much more often.

This may not be the package you want!

Instance

Alert Locations

Package

Readme not found for selected version

Provide a detailed description of the threat...

Socket fights vulnerabilities and provides visibility, defense-in-depth, and proactive supply chain protection for JavaScript, Python, and Go dependencies.

Socket - Secure your dependencies. Ship with confidence.

Welcome to Socket

{{count, number}} maintainer

{{count, number}} maintainers

{{- packageName}} - {{ecosystem}} Package Maintainers

{{packageDescription}}Version: {{versionString}} was published by {{publisherName}}. Start using Socket to analyze {{- packageName}} and its dependencies to secure your app from supply chain attacks.

We could not scan this package. Some page functionalities have been disabled

Source code not available

Sorry, it seems this package was removed from the registry

Package was removed

This package version has been unpublished, mostly likely due to security reasons

au.com.dius:pact-jvm-consumer_2.10 - maven Package Maintainers