Overlap and Priority

## The number is a rank, not a weight WireMock does not evaluate mappings one at a time and stop at the strongest. It gathers every stub whose criteria fit the incoming request, sorts that collection, and serves whichever stub sorts first. Priority is the primary sort key and it sorts **ascending**, so the smallest number ends up at position one and is the mapping that answers. Once you read the value that way, the behaviour stops being surprising. `atPriority(1)` is not "strength one out of ten"; it is "first in the queue". `atPriority(10)` is not "ten times as important"; it is "tenth in line". Raising a number therefore moves a stub *back*, and it will keep moving back for every increment you add. ## Where the default sits on that scale A stub that never calls `atPriority()` is registered at `DEFAULT_PRIORITY`, whose value is five. Five is an ordinary position on the same scale as everything else, not a floor and not a ceiling, which gives you room on both sides: - `atPriority(1)` through `atPriority(4)` sit **ahead** of every unnumbered stub. - Five is where the ordinary body of the stub set lives, written by omission. - `atPriority(6)` and upward sit **behind** every unnumbered stub. So the everyday shape of an intentional overlap is: pin the specific mapping low, and either leave the broad one alone or push it high. In a falconry weight-log suite that reads as `atPriority(1)` on the stub for `/falconry/v1/birds/kestrel-7/weights` and `atPriority(10)` on the mapping that covers every ring, and it produces the ordering you meant no matter which `stubFor` call ran first. ## The mistake and how it presents The failure is almost always the same story. Someone has a stub that is not answering, reasons that it needs to be "more important", and writes a big number on it — `atPriority(50)`, or `atPriority(100)` for good measure. The stub then answers even less often than before, because it has just been sent to the back of a queue where every unnumbered mapping in the set is ahead of it. The symptom is a change that makes the problem strictly worse while looking, in the diff, like a reasonable escalation. The tell in an interview is the same: a candidate who says "give it a higher priority" without saying what the number does is describing an intention, not a mechanism. ## Three products, three conventions The direction is a per-product convention, not a law of stub servers, and getting it from memory across tools is how people end up inverted. Each row below names its owner: | product | what decides which definition answers | what breaks a tie among equals | |---|---|---| | WireMock | the priority number, ascending: the lowest number is served first | the most recently registered mapping | | MockServer | the priority number, descending: the highest number is served first | the earliest created expectation | | Mountebank | ordering is positional: the imposter's stub array is searched in order | not applicable — the first stub whose predicates match answers | Read across that table and the lesson is that "priority" tells you almost nothing on its own. What you need for any given tool is the sort direction and the tie-break, and those two facts are what this leaf is about. ## Practical consequences of the direction 1. **Reserve low numbers for overrides.** A specific stub that must beat a broad one goes low, and one to three is a wide enough band for almost any suite. 2. **Reserve high numbers for fallbacks.** A mapping meant to answer only what nothing else claims goes high, where its number states that intention. 3. **Never write a large number to force a win.** It does the opposite, and it is the single most common `atPriority()` bug. 4. **Do not read the number as importance in review.** Read it as a queue position, and check what is ahead of it. ## The one thing the direction does not change Sorting only ever runs over stubs that already matched. A mapping at `atPriority(1)` whose criteria do not fit the request never enters the sorted collection at all, so no number can rescue a matcher that is wrong. If a stub is not answering, the first question is whether it matches; only once you know it does is the priority number the right place to look. That ordering of questions matters, because the two failures look identical from the outside — in both cases your stub did not answer — and only one of them is fixed by a number. Finally, the direction is stable in both the Java DSL and a mapping written as JSON: the file's `priority` field carries exactly the value `atPriority()` would set, and it sorts the same ascending way.