Skip to main content
MockServer maintains internal state that you can inspect, clear, and persist:
  • Recorded requests — every request received since MockServer last started or was reset
  • Active expectations — all currently registered expectations
  • Recorded expectations — expectations captured from proxied traffic
  • Logs — all internal log events

​
Log levels

The log level controls how much detail MockServer records. Set it using the mockserver.logLevel property or MOCKSERVER_LOG_LEVEL environment variable.
LevelWhat it includes
TRACELow-level details, full request/response content, and verbose matcher internals. Generates a large volume of output.
DEBUGAll matcher results including which specific matchers failed (e.g. a particular header value mismatch). Useful when debugging why a request is not matching.
INFOAll interactions: expectations created, requests matched, expectations cleared, verifications run. (Default)
WARNExceptions and errors only.
ERRORCritical errors only.
OFFNo logging.
Change the log level at runtime without restarting MockServer: 
ConfigurationProperties.logLevel("DEBUG");
Use DEBUG when debugging why an expectation is not matching. Use INFO for normal operation. Use OFF only if logging overhead is a concern and you have no need to inspect state.

​
Retrieving recorded requests

Retrieve all requests MockServer has received since it last started or was reset: 
HttpRequest[] requests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
    );
Filter by request properties to retrieve only matching requests: 
HttpRequest[] requests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/api/users")
            .withMethod("POST")
    );

​
Retrieving active expectations

Retrieve all currently registered expectations: 
Expectation[] expectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
    );
Filter by request matcher to retrieve only expectations that match certain request properties: 
Expectation[] expectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

​
Retrieving recorded logs

Retrieve the log messages MockServer has recorded: 
String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
    );
Filter logs to only those related to a specific path: 
String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
            .withPath("/api/users")
    );

​
Clearing state

Clear state selectively using the type parameter. This is useful between tests to remove expectations or logs without fully resetting MockServer.
TypeWhat is cleared
allRecorded requests, active expectations, recorded expectations, and logs
logRecorded requests and log entries only
expectationsActive and recorded expectations only

​
Clear all state matching a request path

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/api/users")
);

​
Clear only logs for a specific path

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/api/users"),
    ClearType.LOG
);

​
Clear only expectations for a specific path

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/api/users"),
    ClearType.EXPECTATIONS
);
When logLevel is set to DEBUG, clear operations mark log entries as deleted rather than removing them. This keeps the UI’s log history intact so you can still debug interactions that occurred before the clear.

​
Resetting all state

Reset removes all recorded requests, all active expectations, all recorded expectations, and all logs: 
new MockServerClient("localhost", 1080).reset();
Reset is irreversible. All state is discarded immediately. If you need to recover expectations, persist them first (see below).

​
Persisting expectations

By default, expectations exist only in memory and are lost when MockServer restarts. Enable persistence to write expectations to a JSON file that MockServer reloads on startup.

​
Enable persistence

1

Set the persistence properties

MOCKSERVER_PERSIST_EXPECTATIONS=true
MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=mockserverExpectations.json
MOCKSERVER_INITIALIZATION_JSON_PATH=mockserverExpectations.json
2

Confirm the file is reused on restart

Set persistedExpectationsPath and initializationJsonPath to the same file so MockServer both writes to and reads from the same location. On each restart, MockServer loads expectations from this file before accepting requests.
MockServer updates the persistence file automatically whenever expectations are added, cleared, or expire. To watch the initialization file for external changes and reload expectations without restarting: 
mockserver.watchInitializationJson=true