Staying Current

## The switch, and the two things it decides In WireMock, `makeStubsPersistent(` sits on the record specification and answers exactly one question: when the recorder turns captured traffic into stub mappings, do those mappings exist only as objects inside the running instance, or also as files on disk? Left at its default of `true`, each regenerated mapping is serialised as JSON under the WireMock instance's `mappings/` directory, and any response body the recorder extracts to its own file is written beside it under `__files/`. Set to `false`, the same mappings are registered in the running instance and **nothing is written at all**. Both settings produce a working stub server. WireMock's `GET /__admin/mappings` lists the regenerated mappings either way, and the district heating meter API stubs answer `GET /v1/meters/DE-HH-4471/readings` either way. The difference is entirely about what survives the process. ## Why a refresh almost always wants true Refreshing means regenerating a mapping set from the live upstream and comparing it to the set already committed in the repository. That comparison needs two sets of files sitting still long enough for a diff tool, a reviewer and a commit to touch them. In-memory stubs cannot be diffed, cannot be reviewed in a pull request, and cannot be partially accepted. So the persistent branch is the one that makes a refresh a refresh: - The regenerated mappings land in a directory you can point `diff` at. - Extracted bodies land under WireMock's `__files/` directory, where the committed set already keeps its bodies, so like compares to like. - A reviewer can accept some regenerated mappings and reject others, file by file. - The run is reproducible: the same replay against the same upstream leaves the same artefacts to look at again tomorrow. ## When false is the right answer - **Exploring an unfamiliar endpoint.** You want to see what the meter API returns for a substation flow query, and you have no intention of keeping it. - **A capture inside a single test method** whose stubs should die with the instance, so no later test inherits them. - **A read-only or containerised working directory** where writing into WireMock's `mappings/` would either fail or pollute an image layer. - **A first pass whose only job is to size the problem** — how many distinct calls does the client actually make? — before you decide what to record properly. ## What persistence does not do - It does not tidy the output. Persisted mappings are raw recordings: literal matchers, whatever headers were captured, whatever body came back. - It does not merge with the committed set. Regenerated files are new files in whichever root the instance is using; they do not update the old ones in place. - It does not make the stubs authoritative. A persisted mapping is a candidate you have not reviewed yet. - It does not stop the recorder from being pointed at the wrong place. Persisting a capture taken from staging simply gives you a durable record of staging. ## What lands on disk | artefact | WireMock directory | notes | |---|---|---| | regenerated stub mapping | `mappings/` | one JSON file per mapping, named by WireMock from the request plus a generated suffix | | extracted response body | `__files/` | written only when WireMock's recorder pulls the body out into its own file | | nothing at all | — | what WireMock's `makeStubsPersistent(false)` writes | The directory those two live under is whichever root the instance was started with, so a refresh that means to leave the committed set alone starts a second WireMock instance on a clean root and persists there. That combination — WireMock's `makeStubsPersistent(true)` plus a root that is not the committed one — is the safe default shape for a refresh run. ## Reading the result Once the files exist, the interesting work begins. Open the regenerated mappings for the paths you care about and read them against their committed counterparts: same status code, same body shape, same headers that the committed matchers depend on? A persisted refresh is worth exactly as much as the attention someone pays to its output, and its value decays fast — a set regenerated three months ago and never reviewed is just a second stale set. One practical habit: persist into a directory whose name records when and against what the capture was taken, such as `refreshed-meters-prod/`. It costs nothing, and it stops a reviewer six weeks later from having to guess whether the files in front of them came from production or from somebody's laptop pointing at a staging deployment of the meter API.