In a Karate mock feature - the kind served by `karate.start()` or a `MockServer` - when do the `Background` steps run?

juniormust knowfreq 70%

answer

Count executions, not scenarios
Server lifetime, not request lifetime
The opposite of a normal feature file
Runs during construction, before listening

basics

~20 s

Once, 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 s

Karate 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.

Karate 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 lines

gherkin

Feature: 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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:

Karate parses the mock feature and creates a runtime for it.
It registers the mock helper functions - pathMatches, methodIs, bodyPath and friends - so the Background can already refer to them.
It executes every Background step, in order, once.
It copies the variables the Background left behind into the handler's global map.
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.

## 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

In a Karate mock feature - the kind served by `karate.start()` or a `MockServer` - when do the `Background` steps run?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

Two lifecycles behind one keyword

What "once" means mechanically

Why Karate does it this way

Mock mode versus test mode at a glance

What belongs in a mock Background

The trap this sets

▾common follow-ups3 questions

▾analogy~10 s

▾red flags5 flags

Two lifecycles behind one keyword

What "once" means mechanically

Why Karate does it this way

Mock mode versus test mode at a glance

What belongs in a mock Background

The trap this sets

answer

go deeper