Importing Expectations from HAR & Postman

MockServer can import expectations directly from HAR (HTTP Archive) files and Postman Collection v2.x files. This lets you record real HTTP traffic in your browser or Postman, then replay it through MockServer 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

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

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

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 collections are not supported. Attempting to import an Insomnia export returns a clear error message. Convert Insomnia collections to HAR or Postman format first.

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, Accept-Language) 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

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

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

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

Related Pages

• Creating Expectations — the structure of each expectation you are importing: request matchers and response, forward, callback, and error actions
• Initializing Expectations — load expectations automatically at startup from a JSON file or initializer class
• Persisting Expectations — save expectations so they survive a restart