When does WireMock standalone read the stub files under its root directory?

## The read happens once, on the way up WireMock standalone resolves its root directory — `--root-dir`, or the working directory when the flag is absent — and builds a stub set out of `mappings/` and `__files/` beneath it as the process starts. From then on the server answers from that set. The files on disk and the set in memory are two different things that happened to agree at one moment. That is easy to miss because both halves feel live. A bind mount is not a copy, so editing `mappings/scaffold-inspections-list.json` on the host changes the bytes inside the container instantly; `cat` proves it. What did not change is the stub set the running server is serving from. ## What that means for a mounted set The symptoms are specific and, once you know them, unmistakable: - A mapping you just added answers 404 while every older mapping works. - A mapping you just corrected keeps serving the old body, including the old `verdict` value. - A mapping you deleted keeps answering, because it is still in the loaded set. - The same stub set behaves correctly on the next pipeline run, because that run starts a fresh process. The last one is what makes the confusion durable: the problem cannot be reproduced by re-running the job, so it gets written off as flakiness rather than diagnosed. ## Two ways to change what a running server serves 1. **Restart the process.** The set is rebuilt from the root, so whatever is on disk becomes what is served. This is the honest option for a file-backed set and the only one that keeps disk and memory in agreement. 2. **Call the server's own admin API.** A running WireMock accepts changes to its stub set over HTTP, and those changes take effect immediately. They are also in-memory: a stub created that way does not appear in `mappings/`, and a restart returns the server to whatever the files say. Mixing the two is where teams get hurt. If a suite edits a running instance over the admin API *and* the directory is the source of truth, then the set that is serving and the set in the repository have quietly diverged, and only a restart reveals by how much. ## Why the once-only read is usually what you want A stub server that reloaded on every file change would be unpredictable in exactly the wrong place. Consider a build agent where one job rewrites the scaffolding-inspection stub directory while another job's tests are mid-flight: with a start-up read, the running job keeps the set it started with and finishes deterministically. Reading once turns *which stubs are in play* into a property of the process, fixed for its whole lifetime, and a fixed property is something a test result can be attributed to. It also matches how the set is deployed. In a container the stub directory arrives with the container and leaves with it, so the process lifetime and the set's lifetime are already the same span. Making the read follow the process rather than the filesystem keeps those two aligned. ## The habit that avoids the confusion - Treat the container, or the process, as the unit of reload: edit the mapping, restart, retest. - Keep the restart cheap. A named container and a one-line script mean the loop costs a couple of seconds and nobody is tempted to hand-patch a running server. - Decide, per suite, whether the directory or the admin API is the source of truth, and do not use both at once for the same stub. - When a mapping is *definitely there* and still 404s, check whether the process predates the file before you touch the matcher. - Prefer restarting to hand-editing when the set is committed: a hand-patched instance is a state nobody else can reproduce from the repository. ## How the neighbouring products frame the same moment The once-at-start-up read is not unique to WireMock, and the vocabulary differs enough to trip people who move between products. In Mountebank, the imposters named by `mb --configfile` are likewise read as the process comes up, and later changes to a running instance go through its own control surface rather than through the file. The shared lesson is worth stating plainly: on every one of these servers, the file on disk configures *the start of a process*, and the running instance is changed over HTTP or not at all. ## What this is not It is not a claim about mapping content, matching or precedence — a stub that loaded and did not match is a different investigation with different tools. And it is not an argument against file-backed stub sets: a directory in the repository, read once as the server starts, is the most reviewable and most reproducible shape a stub set takes. The only thing it asks of you is that you notice which moment the read happened at.