Skip to main content
An expectation tells MockServer: “when you see a request that looks like this, do that.” Every expectation combines a request matcher with an action. Optionally, you can also control how many times the expectation fires, how long it stays active, and what priority it has relative to other expectations.

​
Expectation structure

An expectation contains:
  • httpRequest — the request matcher that identifies which incoming requests this expectation applies to
  • action — one of httpResponse, httpForward, httpOverrideForwardedRequest, httpResponseTemplate, httpForwardTemplate, httpResponseClassCallback, or httpError (see Response Actions)
  • times (optional) — how many times the expectation should fire before it is deactivated
  • timeToLive (optional) — how long the expectation remains active
  • priority (optional) — matching order relative to other expectations; higher values match first
  • id (optional) — a stable identifier used to update an existing expectation

​
Complete example

new MockServerClient("localhost", 1080)
    .when(
        request()
            .withMethod("POST")
            .withPath("/login")
            .withBody("{username: 'foo', password: 'bar'}")
    )
    .respond(
        response()
            .withStatusCode(302)
            .withCookie(
                "sessionId", "2By8LOhBmaW5nZXJwcmludCIlMDAzMW"
            )
            .withHeader(
                "Location", "https://www.mock-server.com"
            )
    );

​
Field reference

Controls how many times an expectation matches before it is automatically deactivated.
"times": {
  "remainingTimes": 2,
  "unlimited": false
}
Set "unlimited": true to keep the expectation active indefinitely (the default when times is omitted).In Java, use Times.exactly(2), Times.once(), or Times.unlimited().When you register multiple expectations with the same request matcher and different times values, MockServer fires them in registration order. For example, if expectation A fires three times then expectation B fires twice, requests are handled A, A, A, B, B.
Sets an expiry duration after which the expectation is automatically removed, regardless of how many remaining times it has.
"timeToLive": {
  "timeUnit": "SECONDS",
  "timeToLive": 60,
  "unlimited": false
}
In Java, use TimeToLive.exactly(TimeUnit.SECONDS, 60L).
An integer that controls matching order. MockServer evaluates expectations from highest priority first, then by creation order for equal-priority expectations.Use a negative priority to create a catch-all default expectation that only matches after everything else has been tried:
{
  "httpRequest": {},
  "httpResponse": { "body": "default_response" },
  "priority": -10
}
In Java, pass priority as the fourth argument to .when():
new MockServerClient("localhost", 1080)
    .when(
        request().withPath("/some/path"),
        Times.once(),
        TimeToLive.exactly(TimeUnit.SECONDS, 60L),
        10
    )
    .respond(response().withBody("some_response_body"));
A string identifier for the expectation. If you submit an expectation with an id that matches an existing expectation, the existing expectation is replaced entirely. MockServer assigns a UUID automatically when no id is provided.
{
  "id": "630a6e5b-9d61-4668-a18f-a0d3df558583",
  "httpRequest": { "path": "/some/path" },
  "httpResponse": { "body": "updated_response" }
}
This is useful for updating a specific expectation without clearing all others.

​
Matching order

MockServer matches active expectations in priority order, then creation order. Once a matching expectation’s times counter reaches zero, it is deactivated. If no active expectation matches an incoming request and MockServer is not acting as a proxy, it returns a 404.

​
Next steps

Request Matchers

Learn how to match by method, path, headers, body, and more.

Response Actions

Return responses, forward requests, invoke callbacks, or simulate errors.