Verifying Requests

MockServer supports verification of requests it has received, including both proxied requests and requests that have matched an expectation.

Verification can be specified as follows:

a request matcher and a condition indicating the number of times the request should be matched
a sequence of request matchers that is matched in order

How Verification Works

MockServer records all received requests in an in-memory event log (separate from application logs). Verification checks this event log:

For request matcher count verification: MockServer filters the event log to find all RECEIVED_REQUEST entries matching your request matcher, counts them, and compares the count against your constraint (atLeast(n), exactly(n), etc.). Returns HTTP 202 if the count matches, or HTTP 406 with an error message if it does not.

For expectation ID verification: MockServer retrieves all events associated with the specified expectation ID (including EXPECTATION_RESPONSE and FORWARDED_REQUEST entries) and verifies the count.

For sequence verification: MockServer scans recorded requests in order, checking that each expected request appears after the previous match. This is not a simple count comparison—order matters.

Important notes for parallel testing:

The event log size is bounded by the maxLogEntries configuration property (default: minimum of free heap KB / 8 and 100,000 entries—see configuration). When this limit is reached, the oldest entries are evicted. If you run many parallel tests generating thousands of requests, consider increasing this value.
Event recording uses an asynchronous ring buffer. However, verification operations are serialized through the same ring buffer in FIFO order, so a request that has reached MockServer and been recorded will be visible to subsequent verification calls. Intermittent failures are more commonly caused by:
- Your application under test sending requests asynchronously—ensure the application has completed sending before you verify
- Cross-test interference—one test's requests appearing in another test's verification
- Log eviction due to high request volume exceeding maxLogEntries
Best practices for parallel tests:
- Use separate MockServer instances (different ports or containers) per test for complete isolation
- If sharing an instance, use unique paths per test (e.g., /test/{testId}/...) or unique headers/query parameters in matchers
- Avoid broad matchers like only path("/api") in parallel tests
- Be careful with clear() or reset()—they affect all tests sharing the instance
- If verification fails intermittently because your system under test is asynchronous, use retry-with-backoff to wait for requests to arrive (not to wait for MockServer to process already-received requests)
To retrieve recorded requests for debugging, use PUT /mockserver/retrieve?type=REQUESTS or mockServerClient.retrieveRecordedRequests(null).

For more details on the internal architecture, see the Event System documentation.

Verification Timing

Note: MockServer processes log entries asynchronously using a ring buffer. When calling verify() immediately after sending requests, there may be a brief delay before log entries are available for verification. If verification fails unexpectedly right after requests are sent, add a small delay (e.g., 100ms) before retrying. This is most commonly needed in high-throughput scenarios or when the system under test sends requests asynchronously.

Verifying Repeating Requests

Verify that a request has been received by MockServer a specific number of times using a Verification

new MockServerClient("localhost", 1080)
    .verify(
        request()
            .withPath("/some/path"),
        VerificationTimes.atLeast(2)
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .verify(
    {
      'path': '/some/path'
    }, 2)
  .then(
    function () {
      console.log("request found at least 2 times");
    },
    function (error) {
      console.log(error);
    }
  );