skip to content

In WireMock, how do you remove one run-time stub without clearing every other mapping?

level: middleimportance: must knowfreq 62%

answer

  1. precision beats a clean slate
  2. one mapping has its own address
  3. keep what registration handed you
  4. WireMock: DELETE /__admin/mappings/{id}
  5. collection DELETE empties everything

basics

~20 s

Call DELETE /__admin/mappings/{id} with the id WireMock returned when the stub was registered. That removes exactly that mapping and leaves the rest in place, while DELETE on the collection path clears every registered mapping at once.

solid answer

~50 s

The admin API offers two DELETEs on the same collection and they differ only in blast radius. In WireMock, `DELETE /__admin/mappings/{id}` removes the single mapping held under that id, while `DELETE /__admin/mappings` empties the registered set entirely. The id comes from the response to `POST /__admin/mappings`, which returns the stored mapping with the id WireMock assigned it, or from `GET /__admin/mappings` if the registering code did not keep it. Capturing the id at registration is what makes precise teardown possible: a case that stubbed `GET /lighthouses/BEACHY-HEAD/lamp` to answer 503 can remove exactly that stub and leave a neighbouring fixture's lighthouse mappings untouched. If you have the definition but not the id, WireMock's `POST /__admin/mappings/remove` identifies the mapping from the body you post instead. Reaching for the collection DELETE because the id was inconvenient trades a one-line lookup for a whole class of cross-fixture failures.

code

bash · 12 lines
bash
# register the stub and keep the id WireMock assigns it
ID=$(curl -s -X POST http://localhost:8080/__admin/mappings \
       -H 'Content-Type: application/json' \
       --data @beachy-head-lamp.json | jq -r '.id')

# ... the case runs against the lighthouse maintenance API ...

# remove only that mapping; every other lighthouse stub survives
curl -s -X DELETE "http://localhost:8080/__admin/mappings/$ID"

# the blunt alternative, which empties the whole registered set
curl -s -X DELETE http://localhost:8080/__admin/mappings

go deeper

for a junior

Know that the id in the path is what makes removal surgical, and that the same DELETE without an id empties the whole registered set. Being able to state both is the answer at this level.

for a middle

Explain where the id comes from — the response to the registering POST, or a read of the collection — and why a helper that registers a mapping should hand its id back to the caller.

for a senior

Show that you design fixtures so no case ever needs the blunt call: ids captured at registration, teardown that runs whatever the outcome, and no fixture reaching past its own registrations.

for a principal

Own the convention that decides this across suites — who may clear a server's whole set and who may only remove what they registered — because the failure it prevents shows up in someone else's test, not the offender's.

## Two DELETEs on one collection WireMock's admin API exposes removal at two levels, and the whole question is which one you are entitled to use. | WireMock call | what goes | |---|---| | `DELETE /__admin/mappings/{id}` | exactly the mapping held under that id | | `DELETE /__admin/mappings` | every mapping registered on the server | | `POST /__admin/mappings/remove` | the mapping identified by the definition you post | | `POST /__admin/mappings/remove-by-metadata` | the mappings selected by the metadata criteria you post | The collection DELETE is the one people reach for because it is easy to call and needs nothing remembered. It is also the one that reaches past your own fixture. If two suites, two fixtures or two helpers are registering lighthouse mappings on the same server during a run, clearing the collection to remove one stale stub takes the others with it, and the failure surfaces somewhere else entirely — usually as a request that suddenly matches nothing. ## Where the id comes from The id is not something you invent or count out; it is handed to you: - `POST /__admin/mappings` returns the stored mapping **with the id WireMock assigned it**. Capturing it at registration is one line and saves the whole problem. - WireMock's `GET /__admin/mappings` lists the registered set, and every entry carries its id. This is the recovery path when the registering code discarded it. - WireMock's `GET /__admin/mappings/{id}` confirms an id you already hold still addresses the mapping you think it does. The practical discipline is simple: **whatever registers a mapping owns its id, and whatever owns the id owns the teardown**. A helper that registers a lighthouse stub and returns nothing to its caller has made precise removal impossible for everyone downstream. ## Removing without an id Sometimes the id genuinely is not available — a fixture was loaded in bulk, or the registration happened in another process. Two routes on the same surface cover that: 1. WireMock's `POST /__admin/mappings/remove` identifies the mapping from the definition you post rather than from a path segment. You need the mapping, not its id. 2. WireMock's `POST /__admin/mappings/remove-by-metadata` selects mappings by the metadata criteria you post, which is how a batch registered with a common marker can be removed together. Both are narrower than clearing the collection, which is the point. Reaching for WireMock's `DELETE /__admin/mappings` because the id was inconvenient is trading a five-second lookup for a whole class of cross-fixture failures. ## Why precision matters within a single run A server that holds mappings from more than one source is the normal case, not an exotic one. Consider a lighthouse maintenance suite where a shared fixture registers the healthy replies for three stations, and one case additionally registers a 503 for `START-POINT` to exercise a failure path. That case must remove **its** mapping when it finishes: - Removing it by id leaves the shared fixture intact and the next case sees the healthy set it expects. - Clearing the collection destroys the shared fixture as well, and the next case's requests match nothing at all. - Leaving the 503 registered means the next case's `START-POINT` request gets a failure it never asked for. The first is the only correct answer, and it costs one captured id. ## A checklist for teardown over the admin API 1. Capture the id in the same statement that registers the mapping. 2. Remove with WireMock's `DELETE /__admin/mappings/{id}` in whatever teardown the harness guarantees will run. 3. If the id was lost, list the collection and find the mapping rather than clearing everything. 4. Reserve WireMock's `DELETE /__admin/mappings` for the case where one owner controls the whole server's set and genuinely wants it empty. 5. Do not treat re-registering as a substitute for removing: registering again adds a registration, it does not retire the earlier one. ## A note on ids and identity An id addresses **one registration**, not a stub by name. Delete a mapping and register an equivalent one, and you have a new registration to track; the old id no longer addresses anything. That is why the id belongs in a variable held for the lifetime of the registration rather than in a constant somewhere, and why code that hard-codes an id from a previous run is code that will fail in a way nobody enjoys diagnosing. Treat the id as the receipt for a registration: valid while the registration lives, worthless afterwards, and the only thing that makes removal surgical.

  • What happens to a mapping's id when an equivalent stub is registered again?
    A fresh `POST /__admin/mappings` creates a new registration, and the id you captured before the delete no longer addresses anything. Treat the id as the receipt for one registration rather than a stable name for a stub: capture it when you register, use it while that registration lives, and drop it once the mapping is gone.
  • When is clearing the whole set with DELETE /__admin/mappings the right call?
    When one owner controls the server's entire registered set and genuinely wants it empty — a per-case WireMock instance being wiped between scenarios, for example. It is wrong whenever another fixture registered mappings on the same server, because the call cannot distinguish yours from theirs.

saying these in an interview costs you the question

  • Clears every mapping when only one is stale
  • Thinks DELETE /__admin/mappings/{id} needs the mapping in the body
  • Cannot say where the mapping id comes from
  • Registers a replacement instead of removing the old mapping
  • Believes a stub can only be removed by restarting WireMock