In Mountebank, how does one stub answer the same dive-log request differently each call?

## How one Mountebank stub answers more than once In Mountebank an **imposter** listens on a port and holds a list of stubs. A stub has `predicates`, which decide whether it matches a request at all, and a `responses` array, which decides what it gives back. The array is the part that carries a conversation. Each matching dive-log request consumes the next entry in order, and once the last entry has been used the sequence wraps round to the first, so a two-entry array alternates for as long as the test keeps calling. Nothing about the request chooses the entry: once the Mountebank stub has matched, position alone decides. Most entries are an `is` response, which carries the status code, headers and body to return literally. A sign-off stub might therefore hold an `is` response reporting `signoffStatus` `PENDING`, followed by one reporting `SIGNED`, and a polling client walks from the first to the second simply by calling twice. ## repeat is a field on a response - In Mountebank, `repeat` lives on an individual entry of a stub's `responses` array, alongside `is`. - In Mountebank, `repeat` takes an integer greater than zero, and the imposter's validation rejects anything that is not one. - In Mountebank, `repeat` holds the stub on that entry for that many matching requests before the cycle advances to the next entry. - In Mountebank, `repeat` is **not** one of the five behaviors, and calling it one is the commonest mistake made about the product. That last point is worth dwelling on, because the two things sit at genuinely different layers. `repeat` decides **which** entry answers; a behavior decides what happens to an entry that has already been chosen. ## The five behaviors sit at a different layer In Mountebank a response may carry a `behaviors` array, and it holds any of exactly five entries, none of which chooses an entry from `responses`. | behavior | product | what it does to a chosen response | |---|---|---| | `wait` | Mountebank | holds the response back before it is returned | | `copy` | Mountebank | copies values out of the request into the response | | `lookup` | Mountebank | pulls values from an external data source into it | | `shellTransform` | Mountebank | pipes the response through an external command | | `decorate` | Mountebank | runs a JavaScript function over the response | Mixing the two layers is why `repeat` is so often miscatalogued as a sixth behavior, and it is a claim an interviewer will notice. ## A dive-log sign-off sequence, step by step 1. A Mountebank imposter is created with one stub whose `predicates` match `GET /dive-log/v1/dives/D-4417/signoff`. 2. Its `responses` array holds two entries: an `is` response with `signoffStatus` `PENDING` carrying `repeat` set to two, then an `is` response with `signoffStatus` `SIGNED`. 3. The client's first poll matches the stub and takes the first entry, which reports `PENDING`. 4. The second poll matches again and takes the first entry once more, because in Mountebank `repeat` has held the cycle there. 5. The third poll advances to the second entry and reports `SIGNED`, and the client's waiting loop exits. 6. A fourth poll wraps the cycle back to the first entry and reports `PENDING` again — the sequence is circular, not terminal. Step six is the one that surprises people. A Mountebank cycle has no natural end state; if a test must keep seeing `SIGNED`, the last entry has to be given a large `repeat` or the client must stop calling. ## Where positional cycling is fragile - Any extra dive-log call consumes an entry, so a retry inside the client silently shifts the whole Mountebank sequence by one. - The mapping from call number to answer is implicit; nothing in the imposter says *why* the second entry is the second, so the fixture is hard to read months later. - Two tests hitting the same Mountebank imposter interleave their consumption of one array, so the sequence depends on execution order. - Because the array is circular, an over-long test loops back to the beginning rather than failing, which hides the drift instead of reporting it. - Counting calls precisely becomes part of the contract, and that is a brittle thing to depend on when the client owns the retry policy. ## Named states are the other shape WireMock expresses the same conversation with named states instead of positions: `inScenario(...)` joins a stub to a machine, `whenScenarioStateIs(...)` limits it to one state, and `willSetStateTo(...)` moves the machine on when the stub serves. The trade is explicitness against brevity — Mountebank's array is shorter to write, while named states say out loud which moment of the exchange each answer belongs to and survive an unexpected retry unchanged.