To analyse the requests that a system makes the proxy can be used to record all requests and their corresponding responses.

All requests and responses can be retrieved as expectations (called recorded expectations) in Java code or JSON. This allows an easy way to replay a recording from the proxy.

Unlike conventional record-replay approaches typically provided by other proxies, MockServer allows easy editing of the recorded requests because the recording is provided as Java code or JSON. This ensures that if minor changes are made to an API the recording can easily be modified and no re-recording required avoiding the need to update test assertions.

 

One-Command Record & Replay

The fastest way to record from a real upstream is a single retrieve call with the optional forwardUnmatchedTo parameter. It arms record-and-forward in one step — any request that does not match an existing expectation is forwarded to the upstream and recorded — so you no longer need to separately configure proxyRemoteHost / proxyRemotePort and attemptToProxyIfNoMatchingExpectation before you start:

# 1. point MockServer at the upstream (this call arms recording for the session)
curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=java&forwardUnmatchedTo=https://api.example.com"

# 2. run your application / tests against http://localhost:1080 so real traffic is recorded

# 3. retrieve the recording as ready-to-use code (or JSON) — in any supported format
curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=java"

The forwardUnmatchedTo value accepts a bare host (api.example.com), a host and port (api.example.com:9090), or a full URL (http://api.example.com:9090 / https://api.example.com, which default to port 80/443). The upstream host is validated against the same private-network / cloud-metadata SSRF protection as the normal forward and replay paths before any connection is made — a blocked upstream returns 403 and a malformed value returns 400, in both cases leaving the configuration untouched.

Recording is traffic-driven: the first call only arms recording, it does not generate any traffic itself. Combine with the deduplicateRecordedExpectations property to collapse structurally-identical calls (e.g. /users/1 and /users/2) into a single templatized /users/{id} expectation in the retrieved output.

By default only id-like path segments are templatized. Enable the templatizeRecordedValues property (in addition to deduplicateRecordedExpectations) to also generalize volatile-looking query parameter, header and JSON body values — UUIDs, long ids, ISO-8601 / epoch-millis timestamps, JWTs and long opaque tokens — into regex matchers, so the recorded expectation matches future requests instead of being pinned to one captured value. It is conservative: stable values (short strings, words, booleans, small numbers such as a page size or status code) are kept verbatim. Both properties are off by default, so recorded output is unchanged unless you opt in.

 

Consolidate a Recording Into Reusable Mocks

Without any options, a recording is a verbatim one-to-one dump: recording 50 hits to GET /users/123 gives you 50 identical single-use expectations. Add consolidate=true to the retrieve call to collapse a recording into a compact, reusable mock set in one step — without having to set any server property first:

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&consolidate=true"

With consolidate=true MockServer groups recorded calls by request shape and, for each shape, returns a single unlimited-use expectation (so it keeps matching instead of expiring after one call). Calls that differ only in an id path segment (/users/123, /users/456) collapse into one /users/{id} expectation; volatile request headers (Authorization, User-Agent, tracing headers, …) are dropped from the matcher; and when the same request returned different responses over time, those responses are attached as a sequence (the first call gets the first response, the next call the second, and so on). Add parameterize=true as well to also generalize volatile query-parameter, header and JSON-body values (UUIDs, timestamps, tokens) into matchers.

Recording with no query parameter is unchanged, so existing scripts keep working.

 

Promote a Recording to Active Mocks

To turn a recording directly into active mocks on the running server — consolidated, parameterized, secret-redacted and ready to serve — call the promote endpoint after recording:

# promote all recorded traffic to active mocks
curl -v -X PUT "http://localhost:1080/mockserver/recordings/promote"

# or promote only traffic matching a request filter (JSON body)
curl -v -X PUT "http://localhost:1080/mockserver/recordings/promote" \
  -d '{ "path": "/users/.*" }'

The promote endpoint retrieves the matching recorded traffic, redacts credentials (on by default), consolidates and parameterizes it (both on by default — add ?consolidate=false or ?parameterize=false to turn either off), then activates the resulting unlimited-use expectations and returns them as JSON with a 201 Created status. After that you can switch the real dependency off and serve the recording back with no further configuration.

 

Export Recorded Expectations as Client Code

Recorded (and active) expectations can be exported as ready-to-paste client code so you can drop a recording straight into a test. Use the retrieve API with type=RECORDED_EXPECTATIONS (or type=ACTIVE_EXPECTATIONS) and a code format:

One client call is generated per expectation. For example, to export the recorded expectations as JavaScript:

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=javascript"

or as Python:

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=python"

or as Go, C#, Ruby, Rust or PHP — e.g. Go:

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=go"

Every language's output embeds the expectation's JSON inside a real client call, so it is correct for the published client packages (mockserver-client for Node.js, mockserver for Python, mockserver-client-go for Go, MockServer.Client for C#, the mockserver-client gem for Ruby, the mockserver-client crate for Rust, and mock-server/mockserver-client for PHP) and round-trips back into MockServer. In the dashboard, all of these formats are available under Library → Export, each with a Copy as code button; the same Export tab can also generate verification code from the recorded requests in Java, JavaScript, Python, Go, C#, Ruby and Rust.

 

HAR Export

Recorded requests and responses can be exported as a HAR (HTTP Archive) 1.2 file, which is a standard format supported by browser DevTools and other HTTP analysis tools.

To export as HAR, use the retrieve API with type=REQUEST_RESPONSES and format=HAR:

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUEST_RESPONSES&format=HAR"
 

Automatic Persistence of Recorded Expectations

By default, recorded proxy traffic is only held in memory and lost when MockServer restarts. To automatically persist recorded expectations to a JSON file, configure the following properties:

The file is updated whenever a new request is forwarded through the proxy. The saved file can be loaded back into MockServer using the initializationJsonPath property to replay the recorded traffic.

{% include_subpage ../mock_server/_includes/retrieve_code_example.html %}