In a Karate mock feature - the kind served by `karate.start()` or a `MockServer` - when do the `Background` steps run?
answer
- Count executions, not scenarios
- Server lifetime, not request lifetime
- The opposite of a normal feature file
- Runs during construction, before listening
basics
~20 sOnce, when the mock server starts. Karate executes a mock feature's Background while the handler is being built, before the first request arrives; every request afterwards runs only the steps of the one Scenario whose name matched.
solid answer
~50 sKarate runs a mock feature's `Background` **exactly once**, while the mock handler is being constructed and before the server is listening. Whatever it defines is copied into the handler's global variable map, and every later request starts from that map. A request then executes only the steps of the `Scenario` whose name expression matched - the `Background` steps are **not** prepended to it. That is the opposite of a normal Karate test feature, where `Background` re-runs ahead of every scenario, and the asymmetry is exactly why a Karate mock is stateful by default: `* def cats = {}` in the `Background` is **one** map that lives as long as the server, not a fresh empty map per call. Anything that must happen per request belongs in the matched `Scenario`, or in a `configure afterScenario` hook.
code
gherkin · 16 linesFeature: stateful cats mock
Background:
# runs ONCE, when the mock server starts
* def uuid = function(){ return java.util.UUID.randomUUID() + '' }
* def cats = {}
Scenario: pathMatches('/cats') && methodIs('post')
* def cat = request
* def id = uuid()
* cat.id = id
* cats[id] = cat
* def response = cat
Scenario: pathMatches('/cats')
* def response = $cats.*go deeper
Hold on to the one sentence: in mock mode the Background runs once at start-up, not before each request. That single fact explains why a Karate mock can hold data at all.
Be able to say where those Background variables go - into the handler's global map - and that a request executes only the matched Scenario's own steps, never the Background's.
Know what it means operationally: the mock's data is server-lifetime state shared by every client, so a test that mutates it changes what the next test sees.
Weigh the convenience of a long-lived stateful mock against the coupling it creates between the tests that share it, and decide who owns that state and who is allowed to reset it.
## Two lifecycles behind one keyword `Background` means two different things in Karate, depending on which mode the feature is running in. In an ordinary test feature it is **per-scenario setup**. Karate builds each scenario's step list by prepending the feature's `Background` steps to the scenario's own, so a feature with five scenarios executes its `Background` five times, and each scenario begins from an identically fresh evaluation of it. In **mock mode** - a feature served by `karate.start(...)` or by a `MockServer` - the same keyword is the **server's start-up block**. The mock handler reads the `Background` once while it is being constructed, executes its steps, and never looks at them again. A request handled later executes only the steps that belong to the matched `Scenario`; the `Background` steps are not part of that step list at all. ## What "once" means mechanically The order is worth holding in your head, because several of mock mode's other surprises fall straight out of it: 1. Karate parses the mock feature and creates a runtime for it. 2. It registers the mock helper functions - `pathMatches`, `methodIs`, `bodyPath` and friends - so the `Background` can already refer to them. 3. It executes every `Background` step, in order, **once**. 4. It copies the variables the `Background` left behind into the handler's global map. 5. Only then does the server bind a port and start accepting connections. Because step 3 happens before step 5, a `Background` step that fails takes the whole server down at start-up rather than producing a failing response. Because step 4 copies into a map that outlives a request, `* def cats = {}` really is a single map for the life of the server. ## Why Karate does it this way A mock feature is not a test. Its `Scenario` blocks are not cases to be run top to bottom; each one is a **request matcher** whose name is a JavaScript expression, and exactly one of them handles any given request. Re-running `Background` before each of them would be meaningless - there is no "next scenario" being prepared - and actively harmful, because it would wipe the in-memory store on every call and make a stateful mock impossible to write. Karate leans on that deliberately: the recommended way to model an API that remembers things is a plain object created in the `Background` and mutated by the Scenarios. ## Mock mode versus test mode at a glance | | Test feature | Mock feature | |---|---|---| | `Background` runs | before every `Scenario` | once, at server start | | A `Scenario` is | a test case | a request matcher | | The `Scenario` name is | a free-text label | a JavaScript match expression | | Variables after a `Scenario` | discarded with the scenario | written back to the server's globals | | Nothing matches | not applicable | the request gets HTTP 404 | ## What belongs in a mock Background Good candidates, all of them start-up shaped: - **Seed state** - `* def cats = {}`, or a fixture loaded with `read()`. - **Helper functions** the Scenarios will call: a key generator, a formatter, a clock. - **`configure` steps** that set behaviour for every response the server will ever send. - **A per-request hook declared once** - `* configure afterScenario = function(){ ... }`, where the declaration runs once but the function is invoked per request. Bad candidates, because they will happen exactly once and then never again: - Reading anything off the current request. There is no request yet when `Background` runs. - Resetting a counter or clearing a store "between calls". - Anything you expect to see in the log once per client. ## The trap this sets The failure is quiet, which is why interviewers ask. Someone writes a mock whose `Background` loads a fixture and whose Scenario mutates it; the first test passes and the second fails on data the first one left behind. Nothing errored - the mock simply remembered. The fix is to decide deliberately where a reset lives, rather than assuming the `Background` provides one. The mirror-image trap is expecting freshness and getting staleness: `* def now = ...` in the `Background` freezes one timestamp at start-up, and every response for the rest of the run carries it. One last scope note: those `Background` variables become the handler's **globals**, and globals are shared by every client of that server. There is no per-connection or per-client copy. Whatever one caller writes, the next caller reads.
- In a normal, non-mock Karate feature, how often does `Background` run?Before every `Scenario`. Karate builds each scenario's step list by prepending the feature's `Background` steps to it, so each scenario starts from a fresh evaluation. Mock mode is the exception: the handler reads the `Background` once at construction, and a matched scenario runs only its own steps.
- You need something to happen on every request to a Karate mock. Where do you put it?In the matched `Scenario`'s own steps, or in a `configure afterScenario = function(){ ... }` declared in the `Background`. The `configure` step itself still runs only once - it just stores the function - but the handler invokes that function after the matched scenario on every request.
- Does a mock feature's `Background` see variables from `karate-config.js`?No. A mock feature is initialised without the suite that loads the config chain, so none of it applies. If you genuinely need those values, load the file explicitly from the `Background` with a `call read(...)` step, which is the documented workaround.
Read a mock feature as a small class: the Background is its constructor and each Scenario is a request-handling method. The constructor runs when the object is created; the handlers run once per call.
saying these in an interview costs you the question
- Says Background re-runs before every mock request
- Expects a fresh empty store on each call
- Thinks each request gets its own isolated variable scope
- Puts per-request setup steps in the mock Background
- Assumes karate-config.js seeds a mock feature