In WireMock, what does atPriority() set on a stub, and what is the default?

juniorshould knowfreq 64%

answer

two mappings, one incoming request
the builder takes a plain integer
unset stubs still carry a value
the scale runs like a queue number
atPriority, and a single-digit default

basics

~20 s

WireMock's atPriority sets a stub's precedence number. A stub that never calls it sits at DEFAULT_PRIORITY, which is five. Lower numbers win, so among several matching stubs WireMock serves the lowest-numbered one, whatever order they were registered in.

solid answer

~40 s

In WireMock, atPriority(int) is the explicit precedence number you hang on a stub, and it is the first thing WireMock consults when more than one mapping matches an incoming request. A stub that never calls it is registered at DEFAULT_PRIORITY, whose value is five, so an ordinary stub set is one flat band. The scale runs the way a numbered queue does: lower is stronger, so atPriority(1) outranks the default five and atPriority(10) sits underneath it. That is what lets you register a specific stub for GET /falconry/v1/birds/kestrel-7/weights at atPriority(1) and a broader weight-log stub at atPriority(10), and know the specific one always answers. Priority is only the primary sort key, though — on its own it says nothing about two matching stubs that carry the same number.

In WireMock, `atPriority(int)` is the explicit precedence number you hang on a stub, and it is the first thing WireMock consults when more than one mapping matches an incoming request. A stub that never calls it is registered at `DEFAULT_PRIORITY`, whose value is five, so an ordinary stub set is one flat band. The scale runs the way a numbered queue does: **lower is stronger**, so `atPriority(1)` outranks the default five and `atPriority(10)` sits underneath it. That is what lets you register a specific stub for `GET /falconry/v1/birds/kestrel-7/weights` at `atPriority(1)` and a broader weight-log stub at `atPriority(10)`, and know the specific one always answers. Priority is only the primary sort key, though — on its own it says nothing about two matching stubs that carry the same number.

code

java · 10 lines

java

import static com.github.tomakehurst.wiremock.client.WireMock.*;

// the specific stub, pinned above the ordinary band
stubFor(get(urlPathEqualTo("/falconry/v1/birds/kestrel-7/weights"))
    .atPriority(1)
    .willReturn(aResponse().withStatus(200)));

// the broad stub: no atPriority() call, so DEFAULT_PRIORITY (5)
stubFor(get(urlPathMatching("/falconry/v1/birds/[^/]+/weights"))
    .willReturn(aResponse().withStatus(404)));

go deeper

for a junior

Be ready to say that WireMock decides between two matching stubs with a number, that atPriority() sets it, and that a stub which never calls it is registered at DEFAULT_PRIORITY, whose value is five.

for a middle

Explain that priority is the primary sort key and that WireMock orders it ascending, so atPriority(1) beats the default five. Say clearly what the number does not do: it never makes a non-matching stub match.

for a senior

Show when you actually reach for the number. An explicit priority is a statement that an overlap is intentional, so treat every one you find in a stub set as a claim worth checking against the mappings it outranks.

for a principal

Own the convention. Decide whether teams may write explicit numbers at all, which bands are reserved for what, and how a reviewer distinguishes a deliberate ordering from a number someone tuned until a flaky test went green.

Two stubs, one request

A WireMock stub — a StubMapping — pairs a request pattern with the response WireMock should serve when that pattern matches. Nothing stops two stubs from matching the same incoming request. In a falconry weight-log suite you might register one stub for the exact path /falconry/v1/birds/kestrel-7/weights and a second for a pattern covering every bird's weight log; a GET for kestrel-7 satisfies both of them. WireMock does not treat that as a configuration error, does not merge the two responses, and does not choose between them at random. It collects every stub that matched, sorts them, and serves the first one in that order. atPriority(int) is the number that drives the sort.

What atPriority() sets

It is a call on WireMock's stub mapping builder, chained beside the request matcher and the response: stubFor(get(...).atPriority(1).willReturn(...)).
It takes a plain int. There is no enum, no boolean "preferred" flag, and no relative "put this one above that one" form.
It is optional, and most stubs in a working suite never call it.
atPriority( is WireMock's HTTP control. Reaching for withPriority( on an HTTP stub means you are on the wrong builder.
The number belongs to the mapping, not to the response, so it is independent of what the stub actually returns.
In a mapping written as JSON on disk rather than through the Java DSL, the same value is the mapping's priority field.

The default is a named constant, and its value is five

A stub that never calls atPriority() is not "unprioritised" and is not excluded from the ordering. WireMock assigns it DEFAULT_PRIORITY, whose value is 5. Two consequences follow, and both are worth saying out loud in an interview:

A stub set in which nobody calls atPriority() is one flat band. Every mapping holds the same number, so the priority key separates none of them and something else has to decide the winner.
Five sits deliberately away from either end of the scale. That leaves room to lift one stub above the ordinary band with atPriority(1) and to push another below it with atPriority(10), without renumbering anything you have already written.

Lower wins, because the number is a rank

The direction of the scale is the part candidates get backwards, so state it plainly: the lowest number is served first. Read the value as a place in a queue rather than as a strength or a weight — priority one is at the front and priority ten is further back. Applied to a pair of stubs that both match one weight-log request:

stub A	stub B	which one serves the request
`atPriority(1)`	no `atPriority()` call	A, because one outranks the default five
no `atPriority()` call	`atPriority(10)`	A, because five outranks ten
`atPriority(3)`	`atPriority(7)`	A, because three outranks seven
no `atPriority()` call	no `atPriority()` call	the priority key decides nothing; both sit at five

That last row is the one to remember. The number is only the first sort key, and a stub set where nobody called atPriority() never gets past it.

What the number does not do

It does not make a stub match. A stub at atPriority(1) whose criteria do not fit the request is never in the sorted set at all, so its number is irrelevant.
It does not measure how specific a stub is. WireMock does not rank an exact-path mapping above a pattern mapping by itself; if you want that ordering, you write it as a number.
It does not settle two stubs carrying the same value. A second sort key does that.
It does not change the response the winning stub serves — only which stub is the winner.
It is not scoped to one test. The number is a property of the registered mapping and applies to every request that server instance handles while the mapping is registered.

Using it deliberately in a weight-log suite

In practice you touch atPriority() only where an overlap is intentional. The falconry suite above wants the kestrel-7 stub to answer whenever that exact bird's weight log is requested, and the broad weight-log stub to answer for every other ring. Writing atPriority(1) on the specific stub and leaving the broad one on the default band expresses that in a single number, and it keeps working no matter which order the two stubFor calls happen to run in. A suite that instead relies on the order its fixtures execute is correct by accident rather than by design.

There is a reading benefit too. When you open someone else's mapping and it carries an explicit number, that number is a claim about overlap: it says the author knew another mapping matched the same requests and chose which of them answers. A stub set with no explicit numbers anywhere is making the opposite claim — that no two mappings in it ever compete for the same request.

## Two stubs, one request A WireMock stub — a `StubMapping` — pairs a request pattern with the response WireMock should serve when that pattern matches. Nothing stops two stubs from matching the same incoming request. In a falconry weight-log suite you might register one stub for the exact path `/falconry/v1/birds/kestrel-7/weights` and a second for a pattern covering every bird's weight log; a `GET` for kestrel-7 satisfies both of them. WireMock does not treat that as a configuration error, does not merge the two responses, and does not choose between them at random. It collects every stub that matched, sorts them, and serves the first one in that order. `atPriority(int)` is the number that drives the sort. ## What atPriority() sets - It is a call on WireMock's stub mapping builder, chained beside the request matcher and the response: `stubFor(get(...).atPriority(1).willReturn(...))`. - It takes a plain `int`. There is no enum, no boolean "preferred" flag, and no relative "put this one above that one" form. - It is optional, and most stubs in a working suite never call it. - `atPriority(` is WireMock's HTTP control. Reaching for `withPriority(` on an HTTP stub means you are on the wrong builder. - The number belongs to the mapping, not to the response, so it is independent of what the stub actually returns. - In a mapping written as JSON on disk rather than through the Java DSL, the same value is the mapping's `priority` field. ## The default is a named constant, and its value is five A stub that never calls `atPriority()` is not "unprioritised" and is not excluded from the ordering. WireMock assigns it `DEFAULT_PRIORITY`, whose value is **5**. Two consequences follow, and both are worth saying out loud in an interview: 1. A stub set in which nobody calls `atPriority()` is one flat band. Every mapping holds the same number, so the priority key separates none of them and something else has to decide the winner. 2. Five sits deliberately away from either end of the scale. That leaves room to lift one stub above the ordinary band with `atPriority(1)` and to push another below it with `atPriority(10)`, without renumbering anything you have already written. ## Lower wins, because the number is a rank The direction of the scale is the part candidates get backwards, so state it plainly: **the lowest number is served first**. Read the value as a place in a queue rather than as a strength or a weight — priority one is at the front and priority ten is further back. Applied to a pair of stubs that both match one weight-log request: | stub A | stub B | which one serves the request | |---|---|---| | `atPriority(1)` | no `atPriority()` call | A, because one outranks the default five | | no `atPriority()` call | `atPriority(10)` | A, because five outranks ten | | `atPriority(3)` | `atPriority(7)` | A, because three outranks seven | | no `atPriority()` call | no `atPriority()` call | the priority key decides nothing; both sit at five | That last row is the one to remember. The number is only the first sort key, and a stub set where nobody called `atPriority()` never gets past it. ## What the number does not do - It does not make a stub match. A stub at `atPriority(1)` whose criteria do not fit the request is never in the sorted set at all, so its number is irrelevant. - It does not measure how specific a stub is. WireMock does not rank an exact-path mapping above a pattern mapping by itself; if you want that ordering, you write it as a number. - It does not settle two stubs carrying the same value. A second sort key does that. - It does not change the response the winning stub serves — only which stub is the winner. - It is not scoped to one test. The number is a property of the registered mapping and applies to every request that server instance handles while the mapping is registered. ## Using it deliberately in a weight-log suite In practice you touch `atPriority()` only where an overlap is intentional. The falconry suite above wants the kestrel-7 stub to answer whenever that exact bird's weight log is requested, and the broad weight-log stub to answer for every other ring. Writing `atPriority(1)` on the specific stub and leaving the broad one on the default band expresses that in a single number, and it keeps working no matter which order the two `stubFor` calls happen to run in. A suite that instead relies on the order its fixtures execute is correct by accident rather than by design. There is a reading benefit too. When you open someone else's mapping and it carries an explicit number, that number is a claim about overlap: it says the author knew another mapping matched the same requests and chose which of them answers. A stub set with no explicit numbers anywhere is making the opposite claim — that no two mappings in it ever compete for the same request.

Does a WireMock stub with no atPriority() call lose to every stub that has one?
No. A stub with no call sits at `DEFAULT_PRIORITY`, whose value is five, and five is an ordinary value on the same scale as any other. It beats `atPriority(10)` and loses to `atPriority(1)`. The default is a position in the middle of the range, not the bottom of it.
Where does the priority number live when a WireMock stub is written as a JSON mapping file?
It is the mapping's own `priority` field, a sibling of `request` and `response`. Omitting it has exactly the same effect as omitting `atPriority()` in the Java DSL: the mapping is registered at `DEFAULT_PRIORITY`. Because the number sits in the file, a reviewer can see the intended ordering without running anything.

saying these in an interview costs you the question

Says WireMock automatically prefers the most specific matching stub
Thinks a higher atPriority number makes a WireMock stub stronger
Believes a stub without atPriority carries no priority at all
Reaches for withPriority() on a WireMock HTTP stub
Assumes two overlapping WireMock mappings are a configuration error

In WireMock, what does atPriority() set on a stub, and what is the default?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

Two stubs, one request

What atPriority() sets

The default is a named constant, and its value is five

Lower wins, because the number is a rank

What the number does not do

Using it deliberately in a weight-log suite

▾common follow-ups2 questions

▾red flags5 flags

Two stubs, one request

What atPriority() sets

The default is a named constant, and its value is five

Lower wins, because the number is a rank

What the number does not do

Using it deliberately in a weight-log suite

answer

go deeper