In MockServer, what does withSpecUrlOrPayload() accept, and what changes when you point it at a URL?

## One string, three meanings MockServer's `OpenAPIExpectation.withSpecUrlOrPayload(String)` is unusually honest for a method name: it says outright that its single argument is either a **spec URL** or a **payload**. In practice it covers three inputs: - a **URL** the server fetches, typically the published beehive telemetry document on an internal host; - a **file or classpath location** it reads, such as `org/apiary/openapi/hive-telemetry.yaml` packaged with the tests; - the **document itself, inline**, handed over as a JSON or YAML string — useful for a fragment written for one test rather than a whole surface. The same string also reaches MockServer's `openAPIExpectation(` when you use the factory form, so this choice exists whichever way you build the expectation. Nothing else about the derived set changes: the request side of each expectation still comes from the operation, and the reply side still comes from the response the document declares. ## When it is resolved This is the part that decides everything downstream. `MockServerClient.upsert(OpenAPIExpectation...)` resolves the string, builds the expectations and registers them. From that moment MockServer matches incoming beehive telemetry requests against the **registered expectations**, not against the document. So: - The document is read **once per upsert**, not once per request. - Editing the published document changes nothing on a running mock until something calls MockServer's `upsert(` again. - Whatever the source served at that instant is what your suite is testing against, for the rest of the run. ## The URL form: current, and not reproducible Pointing at `https://apiary.internal/specs/hive-telemetry.yaml` means your mock is built from whatever the apiary platform team published most recently. That is the appealing property and the whole reason this leaf exists: the expectation set tracks the document instead of tracking your memory of it. It buys that with three costs that show up in a pipeline rather than on a laptop: 1. **A runtime dependency on a host you do not own.** If it is unreachable or slow, the mock is never built and every test that needed it fails for a reason unrelated to the code under test. 2. **Non-reproducibility.** Identical test code, identical commit, two different days, potentially two different expectation sets. A red build cannot be reasoned about from the commit alone. 3. **A silent behaviour change.** Nobody on your team edited anything, and the mock behaves differently, because somebody on another team edited the document. ## The pinned form: reproducible, and only as fresh as its last refresh A copy of the document committed on the classpath inverts every one of those. The run is offline, hermetic and reproducible; a red build is explained by the commit. The cost is stated plainly rather than hidden: the copy is exactly as current as the last time a person refreshed it, and that refresh has to be somebody's job or it does not happen. This is the honest version of the tradeoff, and it is worth saying in an interview in exactly these terms: - A URL keeps the mock **current** and makes the build depend on a host outside your control. - A committed copy makes the build **reproducible** and makes currency a scheduled human act. - An inline payload makes a single test **self-contained** and does not scale past a fragment. ## Choosing, in a real repository Most teams that have lived with this land on a split rather than a rule: pinned copies in the suites that gate a merge, because a merge gate must be reproducible, and a URL in a separate, non-gating job whose entire purpose is to notice that the published document moved. The second job is allowed to be red for a reason unrelated to your commit, because that is what it is for; the first is not. What you should be able to state, either way, is who owns the refresh, and what the expectation set was built from on the run you are looking at. A build log that does not record which document produced the expectations is a build you cannot debug later. One attribution note, since three servers share this vocabulary: `withSpecUrlOrPayload(` is MockServer's, on `OpenAPIExpectation`, and it is a member of the same small family as `withOperationsAndResponses(`. **In WireMock the same beehive telemetry stubs are typed by hand with `stubFor(...)` and `aResponse()`**, so a sentence about deriving an expectation set from a published document is a MockServer sentence and should name MockServer.