Skip to main content
Record & Replay lets you capture real HTTP traffic through MockServer’s proxy, then turn those recordings into mock expectations. This is useful when you want to build a realistic test suite against a live service first, then switch to mocks for repeatable CI runs — without manually writing every expectation by hand.

​
Use case

A common workflow looks like this:
  1. Run your application against the real service, with MockServer acting as a proxy.
  2. MockServer records every request and the corresponding response.
  3. You retrieve the recordings and convert them into expectations.
  4. In CI, your application runs against those mock expectations instead of the real service.
This approach lets you test against real behavior initially, then freeze that behavior as a reproducible mock.
Unlike most record-replay tools, MockServer returns recordings as editable JSON or Java code — not an opaque binary format. If the upstream API changes slightly, you can update the recorded expectations by hand instead of re-recording everything.

​
Step-by-step workflow

1

Start MockServer

Start MockServer on any available port. For the web proxy or SOCKS proxy, no extra configuration is needed beyond specifying the port.
java -jar mockserver-netty-jar-with-dependencies.jar -serverPort 1080
Or via Docker:
docker run -d --rm -p 1080:1080 mockserver/mockserver
2

Configure your application to proxy through MockServer

Point your application at MockServer. For JVM-based applications, set the standard proxy system properties:
-Dhttp.proxyHost=localhost -Dhttp.proxyPort=1080
For other clients, see Proxy Overview for per-client configuration examples.
3

Run your application against the real service

Exercise the functionality you want to record. MockServer forwards every request to the real upstream service and stores a copy of the request and response internally.All proxied requests are recorded in the order they are received.
4

Retrieve recorded expectations

Once your application has run, retrieve the recorded expectations using the REST API, Java client, or JavaScript client.
curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS"
MockServer returns the expectations as a JSON array. Each expectation contains the recorded httpRequest and httpResponse.
5

Convert recordings into mock expectations

Register the recorded expectations back into MockServer (or a fresh instance) so they are served as mocks. You can post the JSON output directly back to the expectations endpoint, or edit it first to adjust request matchers or responses.
curl -v -X PUT "http://localhost:1080/mockserver/expectation" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "httpRequest": {
        "method": "GET",
        "path": "/api/books"
      },
      "httpResponse": {
        "statusCode": 200,
        "headers": {
          "Content-Type": ["application/json"]
        },
        "body": "[{\"id\": 1, \"title\": \"Effective Java\"}]"
      }
    }
  ]'
In CI, start MockServer without the proxy configuration and load these expectations at startup — your application will receive the same responses it got from the real service during recording.

​
Filtering recorded expectations

Pass a request matcher to retrieve only the expectations you care about. This is useful when your application talks to multiple services and you want to isolate recordings for one path or method. 
curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS" \
  -d '{
    "path": "/api/books",
    "method": "GET"
  }'

​
Retrieving other recorded data

In addition to full expectations, MockServer lets you retrieve recorded requests or request-response pairs in isolation.

​
Recorded requests only

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS"

​
Recorded requests and responses

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

​
Output format

By default, recorded expectations are returned as JSON. You can also request Java code format, which generates ready-to-use MockServerClient calls you can paste directly into your test setup. 
# JSON format (default)
curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=JSON" \
  -d '{"path": "/api/books"}'

# Java format
curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=JAVA" \
  -d '{"path": "/api/books"}'
All recorded data is stored in memory. If you restart MockServer, recordings are cleared. Export and persist the JSON output before restarting if you intend to reuse it.