Pact-JVM Documentation

When dealing with JSON arrays, you can use specific DSL functions to enforce size constraints and matching rules for elements:

Size Constraints:

• eachLike: Ensures every item in the list matches the provided example.
• minArrayLike(key, min): Ensures the list matches the example and has at least min items.
• maxArrayLike(key, max): Ensures the list matches the example and has at most max items.

Unordered Lists (V4):

• unorderedArray: Matches the list regardless of item order.
• unorderedMinArray / unorderedMaxArray: Matches regardless of order with size constraints.
• unorderedMinMaxArray: Matches regardless of order with both min and max constraints.

Array Contains (V4):

• arrayContaining(key): Matches the array against a set of required variants. The matching succeeds if each variant occurs at least once in the array (order does not matter).

// Example: Ensuring a list of users has at least 2 items with specific types
DslPart body = new PactDslJsonBody()
    .minArrayLike("users", 2)
        .id()
        .stringType("name")
    .closeObject()
    .closeArray();

You can instruct the provider to switch to a specific state before an interaction by providing a stateChangeUrl. The verifier will send a POST request to this URL containing the providerState description and any parameters.

Configuration Options

• stateChangeUrl: The URL to receive the state change request.
• stateChangeUsesBody: Determines how data is sent.
  • true (default): Data is sent as a JSON body: { "state" : "...", "params": { ... } }.
  • false: Data is passed as query parameters.
• stateChangeRequestFilter: A closure to manipulate the state change request itself (e.g., adding auth headers).

Teardown

Set stateChangeTeardown = true on the provider to enable teardown calls. The verifier will call the URL with an action parameter set to setup before the test, and action=teardown after the test.

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 ->
                    req.addHeader('Authorization', 'OAUTH ...')
                }
            }
        }
    }
}

The Kotlin DSL supports two ways to define interactions:

1. BDD Style: Uses given at the top level (before the interaction) and uponReceiving to define the interaction. given applies to the next interaction block. You can call given multiple times to attach multiple provider states to a single interaction.

2. Declarative Style: Uses interaction as the entry point and declares given states inside the interaction block. This keeps provider states and the interaction co-located.

Note: uponReceiving and interaction are aliases and can be used interchangeably.

// BDD Style
pact(consumer = "C", provider = "P") {
    given("state 1")
    given("state 2")
    uponReceiving("description") {
        // ...
    }
}

// Declarative Style
pact(consumer = "C", provider = "P") {
    interaction("description") {
        given("state 1")
        // ...
    }
}