How to Stub a 401 Response in WireMock
Prove your client handles a slow auth failure, not just happy paths
Prerequisites
- Docker or Java 17+
- WireMock standalone
Steps
Start WireMock
Boot the standalone server with Docker.
docker run -p 8080:8080 wiremock/wiremockStub the delayed 401
POST a mapping that returns 401 after 1200ms.
curl -X POST localhost:8080/__admin/mappings -d @401.jsonCall it
Hit the endpoint and observe the slow failure path.
curl -i localhost:8080/api/userVerify
You should receive HTTP 401 after ~1.2s, proving your client tolerates a slow auth path rather than assuming instant success.
A delayed 401 is the classic scenario where a UI that assumes instant responses breaks. Stubbing it makes the failure path a first-class test, not a surprise in production.
Why this matters: most auth bugs are not "I got denied," they are "I got denied slowly." A client that fires a request and blocks the UI on the response will hang or show a spinner forever if the 401 arrives after a second instead of instantly. Forcing the delay in a stub is the cheapest way to prove the client degrades gracefully.
Troubleshooting tip: if your client times out before the 1200ms delay fires, your test is actually catching a real config gap — check the client’s timeout against the mock’s delay. That mismatch is exactly the kind of production incident this stub is designed to surface.
What you’ll have when you finish
When the steps are done, you’ll have a running WireMock instance that answers GET /api/user with a 401 after a deliberate 1200ms delay. That single stub is a reproducible proof that your client degrades gracefully under a slow auth failure instead of assuming the response is instant.
More importantly, you’ll have a pattern. The mapping file is portable: commit it to the repo and the same slow-failure double runs in every CI pipeline, so the test isn’t a one-off on your laptop but a guard the whole team inherits.
Troubleshooting
If the client times out before the 1200ms delay fires, that’s the test working — it surfaced a real timeout gap between client and mock. Check the client’s timeout against the delay and decide which is wrong; usually the client is too tight for a realistic auth path.
If you get a 404 instead of the 401, the mapping didn’t register. Confirm the POST to /__admin/mappings returned 201, and that the request path and method in the mapping exactly match what you curl. WireMock matches on both, and a mismatch silently falls through.
If the delay seems ignored, verify you’re not hitting a cached response or a different server on 8080. A stray process on that port is the usual culprit; change the port or kill the conflict.
Variations
Swap the fixed delay for random jitter to simulate variable network conditions: most engines let you set a jitter window instead of a constant. That catches clients that only tolerate a specific slowness, not slowness in general.
Add a fault handler instead of a status to simulate a dropped connection, and a 500 variant to cover server-side failure. A small matrix of these stubs — slow, broken, errored — is the cheapest way to harden a client against the conditions real auth paths actually produce.