In WireMock, what does a NearMiss's MatchResult.getDistance() actually measure?
answer
- a score, not a yes or no
- zero is a perfect fit
- one means nothing lined up
- weighted across the mapping's matchers
- WireMock getDistance orders the near-miss list
basics
~20 sMatchResult.getDistance() scores how badly one request missed one WireMock stub mapping. It runs from 0, meaning every matcher passed, to 1, meaning nothing matched. WireMock ranks a near-miss list by that score, so the closest mapping is listed first.
solid answer
~50 sIn WireMock, a `NearMiss` is a triple: the `LoggedRequest` that arrived, the stub mapping it was compared against, and the `MatchResult` of that comparison. WireMock's `MatchResult.getDistance()` is the single number inside that `MatchResult` — a normalised score where 0 means the mapping matched exactly and 1 means nothing about it lined up. It is a weighted aggregate over the mapping's individual matchers rather than a count of failures, so a mapping that differs on one header alone scores much closer than one that differs on the URL and the method too. WireMock uses it to order the report: `WireMock.findNearMissesForAllUnmatched()` returns candidates closest-first, which is why the top entry is normally the mapping you actually meant to hit. In MockServer, enabling `detailedMatchFailures` makes its log name which matcher rejected the request, which is how that server reaches the same information without scoring the gap.
go deeper
Remember the direction of the scale: in WireMock a near miss with a small distance is a close call, and a large one is a bad fit. Zero means every matcher on that mapping passed.
Be ready to explain that the distance is a weighted, normalised aggregate over a mapping's matchers rather than a count of failures, and that WireMock uses it to order the near-miss report closest-first.
Show what you do with the number in a real failure: treat the top entry as the mapping you meant to hit, read its diff rather than its score, and recognise two near-identical distances as overlapping mappings.
Own the guidance on how much weight a team puts on an automatic score at all: where a ranked report genuinely speeds diagnosis, where it misleads, and when the honest fix is to make the mapping set less overlapping instead.
## What a near miss is made of In WireMock, a `NearMiss` is what the server produces when it compares one request against one stub mapping that did not serve it. That near miss carries three things: the WireMock `LoggedRequest` that arrived, the candidate it was compared against, and the `MatchResult` of that comparison. WireMock's `MatchResult.getDistance()` is the single number inside that third part, and it is the thing that makes a list of near misses useful rather than merely long. ## The scale, and which end is good The distance is **normalised**, running between two fixed endpoints: - **0** — every matcher on that mapping passed. That is the definition of a match, which is why you will never see 0 for a request sitting in the unmatched list. - **1** — nothing about the mapping lined up with the request at all. - **Anything between** — a partial fit, and the smaller the number the better the fit. The direction trips people up, because "distance" reads like "score" and a score usually rewards a big number. Here it is a distance in the geometric sense: how far apart the request and the mapping are. Small is close. ## Weighted, not counted The number is not the count of matchers that failed, and this matters more than it first appears. A WireMock `MatchResult` for a whole request pattern is built by aggregating the results of the individual matchers — the URL, the method, the headers, the query parameters, the body — into one weighted, normalised value. Two consequences follow: 1. A mapping that differs on one header alone scores much closer than one that differs on the URL and the method as well, even though both are simply "wrong". 2. Changing the set of matchers on a mapping changes its distance from a given request even when none of the added matchers is the reason it fails, because they change the aggregate. That is exactly what you want from a ranking: the mapping you meant to hit surfaces above a mapping for an unrelated endpoint that happens to fail only one check. ## Why the ordering matters more than the number Almost nobody needs the value itself. What they need is the order it produces. `WireMock.findNearMissesForAllUnmatched()` returns candidates closest-first, so the top entry for an unmatched vineyard harvest-log POST is normally the mapping you intended to hit, and its diff is the bug. | what you read | what it usually means | |---|---| | one entry clearly closest | that is your mapping; read its diff and fix one side | | two entries at nearly the same distance | overlapping mappings for the same path, and the request satisfies neither | | every entry far from the request | the request is going somewhere you did not intend, or all the mappings are for other endpoints | | an empty report | there were no mappings on that server to compare against | ## Where the number is silent - It says nothing about which mapping would serve the request if two of them *did* match. That is a separate mechanism and a separate question. - It says nothing about whether a mapping is a good mapping. A very close near miss can be a badly over-specified stub. - It is computed against parsed structures, so it cannot see a fault that happened before parsing — a framing or encoding problem produces a confident, useless score. - It is not comparable across requests. A distance for one request against one mapping is only meaningful next to the other candidates for that same request. ## Reading a report in practice 1. Take the top entry and ignore the rest until you have read its diff. 2. Ask whether the field that differed is the client's fault or the mapping's. Over-specified stubs are at least as common as wrong clients. 3. If two entries are effectively tied, look for two mappings covering the same path and differing only in a header or a query parameter — that is a design problem in the stub set rather than a diagnosis problem. 4. Fix one thing, re-run, and confirm the request has left the unmatched list entirely. Used that way, the distance is not a number you quote in a bug report. It is the mechanism that puts the right mapping at the top of the list, so you never have to scan the other forty by eye — and understanding that it is weighted rather than counted is what lets you trust the ordering when it matters.
- Can a near miss in WireMock ever carry a distance of zero?Not for a request that appears in the unmatched list. A distance of 0 means every matcher on that mapping passed, which is the definition of a match, so the request would have been served rather than logged as unmatched. You can see 0 if you ask WireMock's `POST /__admin/near-misses/request` about a request that a mapping does in fact match.
- Two mappings come back at almost identical distances. What does that tell you?That both are plausible candidates and the difference is one field, so read the diff rather than the number. It usually means two overlapping mappings for the same vineyard harvest-log path differing only in a header or a query parameter, and the request satisfies neither. Fix the client, or tighten the mapping you meant to hit.
- Does the distance tell you which mapping would win if the request did match?No. Distance ranks how close each mapping came to matching a request that matched none of them; it says nothing about how WireMock chooses between two mappings that both match. That selection is decided by mapping precedence, which is a separate mechanism with its own rules.
saying these in an interview costs you the question
- Says a higher distance means a closer mapping
- Thinks the distance simply counts how many matchers failed
- Treats a small distance as proof the mapping will match next time
- Assumes a distance of zero can appear for an unmatched request
- Believes the near-miss list is in arrival order rather than by distance