In WireMock, what does GET /__admin/requests/unmatched return during a failing test?

## What the endpoint holds `GET /__admin/requests/unmatched` is WireMock's list of requests that reached the server and found no stub mapping willing to serve them. When that happens WireMock answers the client with a 404, but it does not throw the request away: it records it in the request journal like any other, and this endpoint is the filtered view of that journal showing only the ones nothing served. Each entry is a WireMock `LoggedRequest`. That means you get the request as WireMock actually parsed it — the method, the absolute URL including its query string, the headers, the cookies and the body — rather than what your client's own logging claims it sent. On a vineyard harvest-log suite that is usually enough on its own: you see immediately that the client called `/vineyard/harvest-log` while the mapping was registered for `/vineyard/harvest-logs`, or that it sent no `X-Vineyard-Estate` header at all. ## The two Java spellings, and why they differ This is the small trap in this corner of the API, and it catches people who learned it from autocomplete: - `WireMock.findUnmatchedRequests()` is the **static** entry point. It is what you get from a static import in a test that talks to one statically configured server. - `findAllUnmatchedRequests()` is the **instance** method on a configured `WireMock` client, and it is what the static form delegates to. The names run longer and shorter in the opposite direction from what most people guess, so it is worth committing to memory: the *shorter* name is the *static* one. In a test with a single WireMock server the static form is the ergonomic choice; the moment you run two servers in one test you hold a client per server and call the instance method on each. ## The requests view is not the mappings view Two admin paths differ by one word and answer opposite questions: | WireMock endpoint | question it answers | |---|---| | `GET /__admin/requests/unmatched` | which requests arrived that nothing served? | | `GET /__admin/mappings/unmatched` | which stub mappings has nothing ever served? | The first is a debugging tool for a failing test. The second is a hygiene tool for a stub set nobody maintains. Reaching for the wrong one is the commonest way to answer confidently while talking about something else entirely. ## When the list is not enough The unmatched list tells you *that* a request found nothing. It does not tell you which mapping was closest, or on which field the two disagreed. For that WireMock has the near-miss report at `GET /__admin/requests/unmatched/near-misses`, and in Java `WireMock.findNearMissesForAllUnmatched()`. The natural workflow is: 1. Read the unmatched list. Is the request there at all, and does it look like the request you meant to send? 2. If it is there and looks right, ask for the near-miss report and read the closest mapping's diff. 3. Fix whichever side is wrong — the client that built the URL, or the mapping that expected a different one. ## When the list is empty and the test still fails An empty unmatched list is evidence, not an absence of it. If a stub-backed test failed with a 404 and nothing appears here, the likeliest explanation is that the request never reached this WireMock server at all: - the client was pointed at the wrong port, often a hard-coded one against a dynamically assigned server; - a base URL was built before the server started and captured a placeholder; - the call went through a proxy, or to a real host that answered 404 of its own; - the test asserted against a different server instance than the one it stubbed. Confirm the port the client used against the port the server actually bound before you touch a single matcher. Diagnosing a matcher that was never consulted is the most expensive way to spend an afternoon in this part of the tooling, and the empty list is the signal that tells you to stop and check. ## Why this is the first thing to learn here Everything else in stub-server diagnosis builds on the fact that the server keeps what it could not serve. Near-miss scoring, raw traffic dumps and stub-set hygiene all assume you already know that a 404 from WireMock is the beginning of an investigation rather than the end of one, and that a single endpoint will hand you the evidence in the shape the server saw it.