Mapping Sprawl

## The one thing the endpoint counts A WireMock instance records, for every stub mapping it has loaded, whether that mapping has ever been selected to answer a request. WireMock's `GET /__admin/mappings/unmatched` returns the mappings for which the answer is still no: stubs that were loaded, sat there, and served nothing. `DELETE` on the same path removes exactly that set from the running instance. A mapping is in the list if and only if it has served zero requests since this instance started — nothing else is being measured. That single fact is what makes the endpoint valuable and what makes it easy to over-read. It is the measurable face of a catalogue nobody maintains: a museum ticketing instance that loads four hundred stubs and reports three hundred and ten never-served has a problem you can put a number on, argue about in a review, and watch move build over build. What it is **not** is evidence about whether any individual stub is still *right*. ## The Java surface, and the trap in it From an embedded test the same census is WireMock's `findUnmatchedStubs()`. In WireMock 4 that method is declared on `WireMockServer`, on the `Admin` interface, on `DslWrapper` and on `HttpAdminClient` — and not on the static `WireMock` facade, even though documentation pages present it as though it were. Writing `WireMock.findUnmatchedStubs()` will not compile; you need a handle on the server or on an admin client. The neighbouring names are a separate source of confusion worth keeping straight: - `findUnmatchedStubs()` in WireMock — stubs that served nothing. On `WireMockServer` / `Admin` / `DslWrapper` / `HttpAdminClient`. - `findUnmatchedRequests()` in WireMock — the static form, and it asks about requests, not stubs. - `findAllUnmatchedRequests()` in WireMock — the instance form of that same request-side query. The names are one word apart and answer opposite questions. *Unmatched stubs* means this stub matched nothing; *unmatched requests* means this request matched no stub. ## What "never served" does not mean The endpoint reports over one instance's lifetime and over whatever traffic that instance happened to receive. Both halves matter. | the worry | does WireMock's `GET /__admin/mappings/unmatched` show it? | |---|---| | a stub no test has needed for a year | yes, provided the whole suite ran against this instance | | a stub only one nightly shard exercises | no — to every other run it looks identical to a dead one | | a stub that answered but with a stale body | no — being served is all the endpoint counts | | a request that matched no stub at all | no — that is a question about the request journal | | a stub shadowed by a broader overlapping mapping | it appears, but as an overlap to resolve, not a stub to delete | ## The two failures people expect from it Teams reach for this endpoint hoping it will catch a stale catalogue, and it cannot. A museum ticketing stub for `GET /tickets/{ref}` that returns a body missing the `admittedAt` field the real API now sends is served on every run, so it never appears here — being wrong and being unused are different properties, and only one of them is counted. Equally, a client call to `/exhibitions/SUMMER-26/availability` that no mapping matches is a request-side event. The mapping census has nothing to say about it, because no mapping was involved at all. Read the endpoint for what it is: an inventory question. *How much of what we are loading is doing any work?* ## Using it inside a museum ticketing suite - Take the census **after** the suite finishes, not between tests; the count is cumulative for the instance. - Take it from a **full, unfiltered** run. A sharded or tag-filtered run produces a census about that slice only. - Compare it against the total from WireMock's `GET /__admin/mappings` — the ratio is the number worth tracking, not the raw count. - Circulate the never-served list before deleting anything, because the endpoint cannot distinguish *obsolete* from *only exercised elsewhere*. - Keep it out of per-test assertions; a stub going unserved in one test is entirely normal and says nothing. - Store the list as a build artefact, so two consecutive full runs can agree before anything is removed. Used that way the endpoint turns a vague complaint — *the mapping set is out of control* — into a repeatable measurement a team can act on without guessing. Used carelessly, it becomes the justification for deleting the one stub that only the nightly job needed.