Record and Playback

## What WireMock's recorder actually is WireMock's recorder is not a separate program. It is the same stub server, put into a mode where it forwards what it is asked for to a real service, keeps the real reply, and writes the pair out as a stub mapping. The point is to skip the guessing. Instead of hand-writing a stub for `GET /fleet/boats?site=lower-weir` and inventing what the kayak-rental service returns for it, you put WireMock in front of the real service, drive the client through WireMock, and let the exchanges become mappings. For a standalone WireMock — the shaded jar or the container image — launcher flags arrange that, and they divide cleanly into the ones that make traffic reach a real service and the one that keeps the result. ## The flags that matter - **`--proxy-all=https://kayaks.riverbend.example`** makes WireMock forward every request it receives to that base URL and return the upstream's genuine status, headers and body to the client. On its own it captures nothing; it only guarantees there is a real answer available to capture. - **WireMock's `--record-mappings`** is the half that keeps things. With it on, each proxied exchange is converted into a WireMock stub mapping: the request WireMock saw supplies the match criteria, the upstream's reply supplies the response. - **WireMock's `--match-headers=Accept,X-Kayak-Site`** widens what the generated mappings match on. Without it a recorded mapping keys on method and URL; with it, the named request headers become part of the match as well. Reach for it when the kayak-rental service really does vary its answer by header — a site code, a content type — and not otherwise. - **WireMock's `--enable-browser-proxying`** is the alternative to `--proxy-all` when the client cannot be re-pointed at WireMock's base URL. WireMock then behaves as an HTTP proxy the client is configured to use and takes each destination from the request's own absolute URI, so a single session can capture calls to several hosts. - **WireMock's `--print-all-network-traffic`** prints every request and response as it crosses the server. It records nothing at all, but it is how you prove the client is going through WireMock rather than straight out to the network. ## What lands on disk A recorded mapping is an ordinary WireMock stub mapping — once it exists there is nothing special about it. WireMock writes response bodies large enough to be extracted as separate body files under `__files`, referenced from the mapping instead of being inlined, which keeps a two-hundred-boat availability payload out of the mapping JSON. That gives a WireMock set with a very predictable shape: - one mapping per distinct request WireMock saw, so a client that polls `GET /availability` sixteen times can leave sixteen near-identical mappings behind; - match criteria taken from exactly the URL that was sent, query string and all, so `?site=lower-weir&hours=3` and `?hours=3&site=lower-weir` become two separate mappings; - response bodies that are literally what the kayak-rental service returned that afternoon, including timestamps, generated `rentalId` values and any cookie it issued; - whichever request headers you asked WireMock for with `--match-headers`, and none of the ones you did not. ## Why the output is a first draft The recorder is faithful, not thoughtful. It has no idea which parts of a kayak-rental response are the contract and which are that afternoon's accidents, so it keeps all of them. Three consequences are worth saying out loud: 1. **Secrets travel.** An `Authorization` header, a session cookie or a customer identifier sitting in a recorded body is now in a file you are about to commit, and nothing in WireMock redacts it for you. 2. **Volatile values become fixtures.** A recorded `availableFrom` timestamp is frozen at the instant of capture and will read as stale for as long as the mapping lives. 3. **Over-specific matching becomes flakiness.** Every header you captured is now something the client must reproduce exactly; a correlation identifier that changes per run will simply stop matching. So the honest sequence is record, read, prune, then commit — never record and commit. ## Where capture is switched on, by product | product | how capture is switched on | |---|---| | WireMock, from the launcher | `--record-mappings` alongside `--proxy-all` or `--enable-browser-proxying` | | WireMock, on a running server | `startRecording(...)` and `stopRecording()`, or `POST /__admin/recordings/start` | | Mountebank | `recordRequests` on the imposter, with a `proxy` response leaving recorded stubs behind | ## The mistake that wastes an afternoon The commonest failure here is not a wrong flag; it is a client that never went through WireMock at all. The recorder then produces an empty or near-empty set, and the natural reading — that the flags did not work — is wrong. Check the console first. If `--print-all-network-traffic` prints nothing while you exercise the kayak-rental client, the client is still resolving the real host directly, and no flag on WireMock's side can change that. Fix the client's base URL, or switch to WireMock's `--enable-browser-proxying` and configure the client's proxy settings, and the same two capture flags will start producing mappings immediately.