Pact Contract Export & Verification

MockServer can export its active response expectations as a Pact v3 consumer contract. This bridges MockServer's record/mock workflow with consumer-driven contract testing: mock the API in MockServer during development, then export a Pact contract that can be published to a PactFlow or Pact Broker instance and used to verify the real provider.

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 both 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 — set up the provider's expectations in a separate MockServer instance and call PUT /mockserver/pact/verify with the exported contract to confirm the provider satisfies the consumer's expectations.
4. Publish — optionally publish the contract to a Pact Broker for cross-team visibility.