The typical sequence for using MockServer is as follows:
For example code see the code examples folder in the git repository.
Most of MockServer's power is in step 1, Setup Expectations. Rather than scrolling, jump straight to the capability you need — match the request, choose an action, and (optionally) drive stateful scenarios:
| Match requests | Respond with actions | Sequencing & scenarios |
|---|---|---|
|
Workflow: 0. Start MockServer · 1. Setup Expectations · 2. Run Your Test Scenarios · 3. Verify Requests | Reference: Next Steps · Spring Boot · Upgrading · HTTP/2 Proxy Limitations · Single Port Architecture
With MockServer running and expectations configured, execute your application or test suite. Your application should make requests to MockServer (on the configured port) instead of the real dependencies. MockServer will match incoming requests against the configured expectations and return the specified responses.
Beyond a single fixed response, MockServer lets you control exactly what gets returned on each call.
A stateful scenario is a named state machine that tracks which step of a multi-step conversation the client has reached. Each expectation declares the state it requires (scenarioState) and the state it sets after matching (newScenarioState). Every scenario starts in the "Started" state. This lets you model login flows, pagination, and any API where the correct response depends on what came before.
// First POST /login transitions the scenario from "Started" → "LoggedIn"
// and returns a token.
{
"httpRequest": { "method": "POST", "path": "/login" },
"httpResponse": { "statusCode": 200, "body": "{\"token\": \"abc123\"}" },
"scenarioName": "LoginFlow",
"scenarioState": "Started",
"newScenarioState": "LoggedIn",
"times": { "remainingTimes": 1 }
}
// Subsequent GET /profile only matches once the scenario is in "LoggedIn".
{
"httpRequest": { "method": "GET", "path": "/profile" },
"httpResponse": { "statusCode": 200, "body": "{\"name\": \"Alice\"}" },
"scenarioName": "LoginFlow",
"scenarioState": "LoggedIn"
}See Stateful Scenarios for the full reference including pagination, cross-protocol correlation, and timed flows.
Probabilistic matching adds a percentage field (0–100) to an expectation. MockServer only acts on the expectation for that fraction of structurally matching requests; the rest fall through to the next expectation. Use this to simulate intermittent failures or flaky upstreams — for example, make an endpoint succeed 80% of the time and return 503 the other 20%:
// 80% of GET /api/data requests return 200
{
"httpRequest": { "path": "/api/data" },
"httpResponse": { "statusCode": 200, "body": "{\"result\": \"ok\"}" },
"times": { "unlimited": true },
"timeToLive": { "unlimited": true },
"priority": 10,
"percentage": 80
}
// The remaining 20% return 503
{
"httpRequest": { "path": "/api/data" },
"httpResponse": { "statusCode": 503, "body": "{\"error\": \"Service Unavailable\"}" }
}See Probabilistic Matching for the full reference.
Sequential responses let a single expectation return a different response on each successive call by providing an httpResponses array instead of a single httpResponse. After the last response the list cycles back to the start. Set responseMode to RANDOM to pick randomly instead of in order — useful for simulating unpredictable upstreams:
{
"httpRequest": { "path": "/api/status" },
"httpResponses": [
{ "statusCode": 200, "body": "{\"status\": \"ok\"}" },
{ "statusCode": 503, "body": "{\"status\": \"degraded\"}" },
{ "statusCode": 200, "body": "{\"status\": \"ok\"}" }
]
}
// First call → 200, second call → 503, third call → 200, then cycles.See Sequential / Cycling Responses for the full reference including random mode and the Java client API.
The core mocking flow above covers the most common use case. MockServer also handles more specialised protocols and workflows:
| Capability | When to use it |
|---|---|
| gRPC mocking | Your service communicates over protobuf / HTTP-2 RPC |
| LLM response mocking | Testing an AI application that calls OpenAI, Anthropic, Bedrock, or another LLM provider |
| Chaos & fault injection | Verifying your system degrades gracefully when dependencies misbehave |
| Performance testing / load injection | Driving API traffic at a target with multi-stage VU or arrival-rate profiles and asserting SLOs over the results |
| Interactive breakpoints | Pausing live requests in the dashboard to inspect or mutate them before continuing |
| Mock drift detection | Being warned when a mock no longer matches the real API contract |
| WASM custom rules | Matching or responding with logic written in any language that compiles to WebAssembly |
| AsyncAPI broker mocking | Publishing or recording Kafka / MQTT messages driven by an AsyncAPI spec |
MockServer targets Java 17 as the minimum supported version and uses the jakarta namespace (Jakarta EE / Spring Framework 6+) throughout. This means MockServer is compatible with Spring Boot 3.x and later. Spring Boot 2.x (which uses Spring Framework 5.x and the older javax namespace) is no longer the target.
Spring Boot 3 migrated from the javax namespace to the jakarta namespace, and MockServer has moved to jakarta to match. The Spring Test Execution Listener and JUnit integrations that depend on Spring classpath integration target Spring Boot 3.x and later.
| Spring Boot Version | Spring Framework | Namespace | MockServer Compatible |
|---|---|---|---|
| 3.x and later | 6+ | jakarta | Yes |
| 2.x | 5.x | javax | No (use Docker or standalone) |
When upgrading MockServer between versions, be aware of the following changes that may affect your setup:
It is recommended to run your full test suite after upgrading to catch any compatibility issues early.
MockServer can accept HTTP/2 connections and serve mock responses over HTTP/2. However, when MockServer is used as a proxy and forwards requests to downstream services, HTTP/2 requests are downgraded to HTTP/1.1. This means:
If your tests require end-to-end HTTP/2 proxying (including HTTP/2 to the upstream server), this is not currently supported. Consider using MockServer in mock mode instead of proxy mode for HTTP/2 endpoints.
MockServer serves both mock and proxy traffic on the same port (default 1080). There is no separate port for proxying. The proxyRemotePort and proxyRemoteHost settings specify the upstream target server that unmatched requests are forwarded to — they do not open a separate listening port. All expectations, proxy forwarding, and protocol support (HTTP, HTTPS, SOCKS) share the single serverPort.