Pact Contract
Import, Export & Verification

MockServer supports the complete Pact v3 contract-testing loop: import a contract to generate stub expectations, export active expectations as a new contract, and verify that existing expectations satisfy a contract. Each direction is a separate endpoint.

Pact Import Endpoint

Send a PUT request to /mockserver/pact/import with a Pact v3 consumer contract as the request body. MockServer generates one expectation per interaction and returns 201 Created with the generated expectations as JSON.

This is the inverse of the export endpoint below: rather than producing a contract from active expectations, it creates expectations from the contract, turning a published contract into a ready-to-use stub provider.

The same operation is also available at the generic import endpoint with the ?format=pact query parameter, or via auto-detection (a body with a top-level interactions array is auto-detected as Pact). See Importing Expectations for the generic endpoint and redaction options.

How interactions become expectations

For each interaction, the importer builds:

• A request matcher from request.method, request.path, request.query, request.headers, and request.body
• A response from response.status, response.headers, and response.body

JSON request bodies are matched semantically (key-order and whitespace insensitive). The expectation ID is set to the interaction's description field, or pact-<index> when the description is blank. Re-importing the same contract updates existing expectations in place.

Provider states

A Pact interaction's provider state — its providerState (v2) or providerStates (v3) "given ..." precondition — is preserved on import. The generated expectation is gated on a scenario named pact-provider-state whose required state is the provider-state name, so the interaction only matches once that provider state has been activated. Interactions without a provider state are unaffected and always match.

During verification MockServer activates each interaction's provider state before matching it, so a contract that uses provider states verifies end-to-end. Provider states are also round-tripped on export. Only the first provider state on an interaction gates matching (a scenario holds one active state at a time).

matchingRules mapping

Pact v3 matchingRules.request are translated to MockServer matcher values:

Sensitive data redaction

The same redaction rules apply as for HAR and Postman imports: credential-bearing headers and common secret body fields are masked by default. Pass ?redactSensitiveData=false to import values verbatim. See Sensitive Data Redaction for the full list of query parameters.

curl -v -X PUT "http://localhost:1080/mockserver/pact/import" \
  -H "Content-Type: application/json" \
  -d '{
    "consumer": {"name": "frontend"},
    "provider": {"name": "users-service"},
    "interactions": [{
      "description": "get users",
      "request": {"method": "GET", "path": "/api/users"},
      "response": {"status": 200, "headers": {"content-type": ["application/json"]}, "body": {"users": []}}
    }],
    "metadata": {"pactSpecification": {"version": "3.0.0"}}
  }'

[ {
  "id" : "get users",
  "httpRequest" : {
    "method" : "GET",
    "path" : "/api/users"
  },
  "httpResponse" : {
    "statusCode" : 200,
    "headers" : {
      "content-type" : [ "application/json" ]
    },
    "body" : "{\"users\":[]}"
  }
} ]

Pact Export Endpoint

Send a PUT request to /mockserver/pact to export the currently active response expectations as a Pact v3 consumer contract JSON document.

MockServer responds with HTTP 200 and the Pact contract as pretty-printed JSON.

What Gets Exported

Only expectations that have a concrete HTTP request matcher and a response action are exported. Expectations using forward, callback, or template actions have no direct Pact equivalent and are skipped.

• Expectations whose method or path is a notted matcher (match anything except) are skipped — there is no positive Pact equivalent.
• Notted header or query-parameter values are dropped from the exported interaction; non-notted values are included.
• JSON bodies are embedded as structured JSON in the Pact interaction rather than as escaped strings.
• The interaction description is the expectation ID when a meaningful (non-UUID) ID was set, otherwise METHOD path (e.g. GET /api/users).
• The exported contract uses Pact specification version 3.0.0. Matcher values are emitted as concrete example values (Pact's default exact matching); MockServer matching rules (regex, JSON-schema, XPath) are not translated into Pact matchingRules.

Example

Given an active expectation that mocks GET /api/users, export a Pact contract for the frontend consumer and users-service provider:

curl -v -X PUT "http://localhost:1080/mockserver/pact?consumer=frontend&provider=users-service"

{
  "consumer" : {
    "name" : "frontend"
  },
  "provider" : {
    "name" : "users-service"
  },
  "interactions" : [ {
    "description" : "GET /api/users",
    "request" : {
      "method" : "GET",
      "path" : "/api/users"
    },
    "response" : {
      "status" : 200,
      "headers" : {
        "content-type" : [ "application/json" ]
      },
      "body" : {
        "users" : [ ]
      }
    }
  } ],
  "metadata" : {
    "pactSpecification" : {
      "version" : "3.0.0"
    }
  }
}

Consumer-Driven Contract Testing Workflow

A typical workflow using MockServer with Pact:

1. Mock the provider — create expectations in MockServer for each API endpoint your consumer calls. Use expectation IDs that are meaningful to use as Pact interaction descriptions.
2. Run consumer tests — run your consumer's test suite against MockServer. Tests pass because MockServer returns the expected responses.
3. Export the contract — call PUT /mockserver/pact?consumer=my-consumer&provider=my-provider to get the Pact JSON.
4. Publish to Pact Broker — publish the exported JSON to your Pact Broker or PactFlow instance so the provider team can verify against it.

Recordings made through MockServer's proxy/spy mode (see Operating Mode) can also be exported: after recording real traffic through a SPY or CAPTURE session, the captured response expectations appear as active expectations and can be exported directly.

Verifying a Pact Contract

Send a PUT request to /mockserver/pact/verify with a Pact v3 contract as the request body. MockServer verifies that its currently-active expectations satisfy every interaction in the contract.

For each interaction, MockServer:

1. Builds an HTTP request from the interaction's request fields (method, path, query, headers, body).
2. Finds the first active expectation whose request matcher matches this request.
3. Compares the matched expectation's response against the interaction's expected response:
   • Status code must be equal.
   • Headers use subset matching — each header in the Pact response must be present in MockServer's response, but extra headers are allowed.
   • Body — if both bodies parse as JSON, they are compared structurally; otherwise string equality is used.

Response Codes

Result Format

The JSON response body contains an overall verified flag and a per-interaction breakdown:

{
  "verified" : false,
  "interactions" : [ {
    "description" : "get users",
    "verified" : true
  }, {
    "description" : "create user",
    "verified" : false,
    "reason" : "status code mismatch: expected 201 but was 200"
  } ]
}

Limitations

• Only expectations with a static response action (single response or response sequence) can be verified. Expectations using forward, callback, or template actions will fail verification with the reason "unverifiable (non-static action)".
• For response sequences, verification compares against the first response in the sequence.

curl -v -X PUT "http://localhost:1080/mockserver/pact/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "consumer": {"name": "frontend"},
    "provider": {"name": "users-service"},
    "interactions": [{
      "description": "get users",
      "request": {"method": "GET", "path": "/api/users"},
      "response": {"status": 200, "body": {"users": []}}
    }],
    "metadata": {"pactSpecification": {"version": "3.0.0"}}
  }'

{
  "verified" : true,
  "interactions" : [ {
    "description" : "get users",
    "verified" : true
  } ]
}

Full Consumer-Driven Contract Loop

With import, export, and verify, MockServer supports the complete consumer-driven contract testing loop:

1. Consumer side — create expectations in MockServer and run consumer tests against them.
2. Export — call PUT /mockserver/pact to export the contract.
3. Provider side — import the contract into a separate MockServer instance with PUT /mockserver/pact/import to stub the provider, or call PUT /mockserver/pact/verify to verify that existing provider expectations satisfy the contract.
4. Publish — optionally publish the contract to a Pact Broker for cross-team visibility.