MockServer can import expectations directly from HAR (HTTP Archive) files, Postman Collection v2.x files, and Pact v3 consumer contracts. This lets you record real HTTP traffic, reuse existing collections, or bootstrap stubs from a published contract without writing expectations by hand.

Common use cases:

  • Record-and-replay — capture traffic with browser DevTools (Export HAR) or Postman, then import it to create a mock that replays the recorded responses
  • Migrate existing collections — teams with an existing Postman collection can import their saved example responses into MockServer
  • Bootstrap mocks quickly — import a HAR from staging traffic to get a working mock in seconds, then fine-tune individual expectations as needed
  • Replay a Pact contract — import a Pact v3 consumer contract to create a stub provider that satisfies the contract without standing up the real service
 

Import Endpoint

Send a PUT request to /mockserver/import with the HAR or Postman JSON document as the request body. MockServer creates one expectation per entry (HAR) or per saved example response (Postman) and returns 201 Created with the generated expectations as JSON.

 

Format detection

MockServer auto-detects the format from the JSON structure:

  • If the body contains log.entries, it is treated as HAR
  • If the body contains info and item, it is treated as a Postman Collection
  • If the body contains a top-level interactions array, it is treated as a Pact v3 contract

You can also override auto-detection with the format query parameter:

Query parameter Value Description
format har Force HAR parsing
format postman Force Postman Collection parsing
format pact Force Pact v3 contract parsing

If auto-detection fails and no format parameter is provided, MockServer returns 400 Bad Request with a message suggesting you specify the format explicitly.

Insomnia is not a supported import format — the only recognised formats are har, postman, and pact. Export from Insomnia as HAR, or convert to a Postman collection, then import that instead.

 

Sensitive Data Redaction

MockServer automatically redacts sensitive values from imported files before creating expectations, so that credentials captured in recorded traffic are not stored in your mock configuration.

Headers redacted by default: Authorization, X-Api-Key, X-Auth-Token, Cookie, Set-Cookie, Proxy-Authorization, and similar credential-bearing headers. The header name is preserved in the generated expectation but the value is replaced with a placeholder so the mock does not depend on a specific secret.

JSON body fields redacted by default: common secret field names such as password, secret, token, api_key, apiKey, access_token, and refresh_token are replaced with a placeholder value in request and response bodies.

If you need to disable redaction (for example when importing a file that contains only test credentials and you want exact value matching), or to extend the set of redacted fields for your organisation, pass import options in the query string:

Query parameter Description
redactSensitiveData=false Disable all redaction; imported values are stored as-is
additionalRedactedHeaders=X-My-Secret,X-Internal-Key Comma-separated list of extra header names to redact, in addition to the defaults
additionalRedactedBodyFields=clientSecret,privateKey Comma-separated list of extra JSON body field names to redact, in addition to the defaults
 

Importing from HAR

Each entry in the HAR's log.entries[] array produces one expectation. The request matcher uses the method, path, and query parameters from the recorded request. The response uses the recorded status code, headers, and body.

Volatile header filtering

Not all recorded headers make sense in a mock expectation. MockServer automatically filters out volatile headers that would over-constrain matching or produce stale responses:

  • Request headers excluded from matching: Host, Date, User-Agent, Accept, Accept-Encoding, Cookie, Authorization, Connection, Content-Length, Referer, Origin, trace headers, and others
  • Response headers excluded: Date, Transfer-Encoding, Content-Length, Connection, Set-Cookie, Server, Vary, trace headers, and others

Non-volatile headers (such as Content-Type) are preserved and included in the generated expectations.

Request body handling

When a HAR entry has postData.text, it is included in the request matcher if the body is reasonably sized (under 4 KB). Larger request bodies are omitted from matching to keep expectations permissive.

Base64 response bodies

HAR files sometimes encode response bodies as Base64 (indicated by content.encoding: "base64"). MockServer automatically decodes these back to plain text for the generated response body.

curl -v -X PUT "http://localhost:1080/mockserver/import" \
  -H "Content-Type: application/json" \
  --data-binary @traffic.har

Or explicitly specify the format:

curl -v -X PUT "http://localhost:1080/mockserver/import?format=har" \
  -H "Content-Type: application/json" \
  --data-binary @traffic.har

MockServer returns 201 Created with the generated expectations as JSON.

 

Importing from Postman

MockServer supports Postman Collection v2.0 and v2.1 formats. Collections are walked recursively, so requests inside folders are imported correctly.

For each request item that has saved example responses (the response[] array), one expectation is created per example. Requests without saved examples are skipped (with a count logged), since there is no response to mock.

The Postman url field is handled whether it appears as a plain string or as the structured object format with path[] and query[] arrays.

curl -v -X PUT "http://localhost:1080/mockserver/import?format=postman" \
  -H "Content-Type: application/json" \
  --data-binary @my-collection.postman_collection.json

MockServer returns 201 Created with the generated expectations as JSON.

 

Importing from a Pact v3 Contract

MockServer accepts a Pact v3 consumer contract and generates one expectation per interaction. This is the inverse of the Pact export endpoint: rather than producing a contract from active expectations, it creates expectations directly from the contract, turning a published contract into a ready-to-use stub provider.

For each interaction, the importer builds:

  • A request matcher from the interaction's request object (method, path, query, headers, body)
  • A response from the interaction's response object (status, headers, body)

JSON request bodies are matched semantically (key-order and whitespace insensitive) rather than by exact string equality.

The expectation ID is set to the interaction's description field, or pact-<index> when the description is blank.

Pact matchingRules mapping

Pact v3 contracts carry optional matchingRules.request instructions that relax exact-equality matching. MockServer translates them to matcher values:

Pact rule MockServer matcher value
regex The supplied regex pattern (MockServer matches it as a regular expression)
include .*<value>.* — a substring regex
type / number / integer / decimal / boolean .+ — any non-empty value (MockServer has no first-class type matcher for string fields)
Unrecognised rule / no rule The concrete example value from the contract (exact match)

Unrecognised rule types fall back to exact matching and are logged at DEBUG.

Dedicated endpoint

A dedicated URL is also available for Pact-only imports; it behaves identically to PUT /mockserver/import?format=pact but without needing the query parameter:

PUT /mockserver/pact/import

Both the generic and dedicated endpoints accept the same redaction query parameters and return 201 Created with the generated expectations as JSON.

curl -v -X PUT "http://localhost:1080/mockserver/import?format=pact" \
  -H "Content-Type: application/json" \
  --data-binary @consumer-provider.json

Or use the dedicated endpoint:

curl -v -X PUT "http://localhost:1080/mockserver/pact/import" \
  -H "Content-Type: application/json" \
  --data-binary @consumer-provider.json

MockServer returns 201 Created with the generated expectations as JSON.

 

What gets generated

Each imported expectation is assigned a stable ID based on the source format and entry index (e.g. har-0, har-1, or postman-0-get-users). Re-importing the same file updates the existing expectations in place rather than creating duplicates.

The generated expectations use unlimited times and unlimited time-to-live, so they will match repeatedly until cleared or reset. You can modify individual expectations after import using the standard PUT /mockserver/expectation endpoint.

 

Error responses

Status Cause
201 Import succeeded; body contains the generated expectations as JSON
400 Empty body, invalid JSON, unrecognised format, or missing required structure (log.entries for HAR, info/item for Postman, interactions array for Pact)
 

Related Pages