A step in a Karate mock feature's `Background` fails. Does the mock server still come up, and what does a client see?
answer
- Ask what happens before the port is bound
- Construction, then listening
- Compare against a scenario step failing
- Connection refused versus HTTP 500
basics
~20 sIt does not come up. The Background runs inside the mock handler's construction, before any port is bound, so a failed step throws out of the start call. A client gets a connection refusal, not an HTTP status.
solid answer
~40 sThe server never starts. Karate builds the mock handler first - which runs the `Background` once - and only then binds the socket, so a failing `Background` step throws before there is anything to connect to, and the error names the `Background` line that failed. That is deliberately different from the two per-request failure modes. If a step inside a **matched** `Scenario` fails, only that request fails: the handler answers HTTP **500** carrying the step's error message and keeps serving everyone else. If **no** `Scenario` matches at all, the handler logs that and answers HTTP **404**. So "my mock returns 500" and "my mock will not start" are two different bugs - the first lives in a Scenario, the second in the `Background`.
go deeper
Remember the shape: a bad Background means no server at all, so you get a connection error rather than a response. A bad Scenario step means one bad response.
Explain the ordering that causes it - the handler runs the Background during construction, and only a successfully constructed handler gets a port bound to it.
Use the distinction when triaging: connection refused points at the Background, a 500 at one Scenario's steps, a 404 at the Scenario name expressions.
Decide what a mock's start-up contract should be for your suite, and resist the pressure to make a mock start degraded - a stub that lies is worse than a stub that is absent.
## The order that decides everything Starting a Karate mock is two steps in a fixed order: 1. **Build the handler.** Parse the feature, register the mock helper functions, execute the `Background` once, copy its variables into the globals map. 2. **Bind the port.** Only now does anything listen. A `Background` step failure lands in step 1. The handler's construction throws, the exception propagates out of whatever you called - the `MockServer` builder, or `karate.start(...)` inside a feature - and step 2 is never reached. There is no half-started server answering 500s, because there is no server. The error identifies the `Background` line that failed and carries the underlying step failure as its cause, so the stack trace tells you both which line and why. This is not the same as "the mock is broken". It is the strictest possible reading of a mock's contract: if the fixture the mock is supposed to serve could not be built, standing up a server that lies about it would be worse than not standing up at all. ## The three failure modes, kept separate | Where it fails | When | What the caller sees | |---|---|---| | A `Background` step | once, at start-up | nothing to connect to - the start call throws | | A step in a **matched** `Scenario` | per request | HTTP **500** carrying the step's error message | | Nothing matched any `Scenario` | per request | HTTP **404**, and a log line saying no scenarios matched | Being able to place a symptom in that table is most of the debugging. A connection refusal points you at the `Background`; a 500 points you at one Scenario's steps; a 404 points you at the Scenario **names**, which are match expressions, not at the steps beneath them. ## Reading the failure Because the `Background` executes as ordinary Karate steps, it fails for ordinary Karate reasons, and the usual suspects are all resolution problems: - **`read()` cannot find a file.** A relative path in a mock feature resolves against the feature file, and a mock is frequently started from somewhere other than where the test lives. - **A `call` to another feature fails.** The callee's own failure surfaces here. - **A JavaScript expression throws.** A helper defined with `function(){ ... }` is only *defined* in the `Background`, so this is usually a bad expression rather than a bad function body. - **A `match` step in the `Background` fails.** Asserting in a mock's `Background` is unusual, but people do it to sanity-check a fixture, and a failed assertion stops the server from starting. ## Why the contrast with a Scenario failure matters Once the server is up, Karate goes out of its way to keep it up. A failing step in a matched `Scenario` does not take the process down and does not corrupt the handler; the request that hit it gets a 500 whose body carries the error message, and the next request is served normally. That means a partially broken mock keeps working for the paths that are fine - which is what you want from a stand-in during a long test run, and which is why a mock that answers *some* requests and 500s on others is a Scenario-level bug, never a `Background` one. ## Practical consequences - **Fail fast is the design.** Prefer to seed the store from a literal or a `read()` in the `Background` precisely because a problem there is caught at start-up, before any test has drawn a conclusion from a wrong stub. - **Do not defend the `Background` with `try/catch`.** Swallowing the error gives you a server that starts with a half-built fixture and reports nothing. The loud failure is the feature. - **In CI, look at where the failure is reported.** A start-up failure surfaces in the test that starts the mock, not in the test that would have called it - so the failing test name can point at the wrong place unless you read the message. - **A 404 is not a failure at all.** It is the handler's honest answer that nothing matched, and it means the fault is in a `Scenario` name expression rather than in any step.
- A step inside a matched mock `Scenario` fails instead. What does the caller get?HTTP 500, with the step's error message carried in the reply, and the server keeps running. Only that one request is affected; the next request is matched and served normally. It is a per-request failure, deliberately not a fatal one.
- A client gets HTTP 404 from a Karate mock that is clearly running. Where do you look?At the `Scenario` names, not the steps. A mock Scenario's name is a JavaScript match expression, and 404 is what the handler returns after no expression evaluated true - it logs that no scenarios matched. The steps beneath were never reached.
- Should you wrap a risky mock `Background` step in a `try/catch` so the server starts anyway?No. A server that starts with a half-built fixture serves wrong data silently, and every test that then passes against it has proved nothing. The throw at start-up is the point: it fails in the one place where the cause is unambiguous.
saying these in an interview costs you the question
- Says the server starts and 500s every request
- Expects the failing Background step to be skipped
- Confuses an unmatched request with a broken Background
- Thinks a scenario failure takes the mock server down
- Wraps the Background in try/catch to force a start