skip to content

In a Karate feature file, how far does a `configure headers` step reach when it sits in the `Background` versus inside one `Scenario`, and what does `* configure headers = null` do?

level: middleimportance: must knowfreq 62%

answer

  1. background is per scenario, not per feature
  2. the next scenario starts over
  3. one key at a time
  4. replace, never merge

basics

~20 s

A Background configure re-runs before every scenario, so each one starts from the same state. A configure inside a scenario reaches only that scenario. Assigning null clears that one key for the rest of it.

solid answer

~40 s

`Background` steps re-run before **every** scenario in the feature, so a `configure` there is re-executed per scenario rather than once per feature — every scenario begins with the same ambient settings. A `configure` written inside a scenario applies from that step to the end of **that** scenario, and it cannot leak into the next one, because the next scenario re-runs the `Background` over its own config. `* configure headers = null` clears the header map for the remainder of the current scenario; it does not disable `configure` generally and it does not touch `ssl`, the timeouts or any other key. Assigning a **new map** replaces the configured set outright rather than merging with the `Background` map — the previously configured names are gone.

code

gherkin · 19 lines
gherkin
Feature: configure scope

Background:
  * configure headers = { 'X-Custom-Auth': 'Bearer token123' }
  * url 'http://test'

Scenario: keeps the Background headers
  * method get
  * status 200

Scenario: clears them for this scenario only
  * configure headers = null
  * method get
  * status 401

Scenario: replaces them outright - X-Custom-Auth is gone
  * configure headers = { 'X-Different-Header': 'new-value' }
  * method get
  * status 401

go deeper

for a junior

Learn the two placements first: in the Background it applies to every scenario in the file, inside a scenario it applies only there. Assigning null clears that one setting.

for a middle

Be able to say why nothing leaks: the Background re-runs before each scenario, so each one re-derives its config rather than inheriting the previous scenario's.

for a senior

Watch for the replace-not-merge rule. A scenario that configures a fresh header map silently drops everything the Background set, and the failure shows up as a 401 rather than as a config error.

for a principal

Set a convention for how far ambient settings may travel. Config that reaches a call from several files away is cheap to write and expensive to debug, so decide deliberately what belongs in the config file versus a Background.

## Three placements, three reaches A `configure` step changes the HTTP client rather than a variable, so the only interesting question about it is scope. There are three places to put one, and each reaches a different distance: 1. **Inside a `Scenario`** — from that step to the end of that scenario. 2. **In the feature's `Background`** — re-executed before every scenario in the feature. 3. **In `karate-config.js`**, using the JavaScript form `karate.configure(key, value)` — the widest reach, because the config file is not tied to one feature. The leaf-level interview question is almost always about the first two, because that is where people are surprised. ## Background is per scenario, not per feature The usual surprise is that `Background` is not a feature-level setup block. Karate re-runs it before each scenario, exactly as it re-runs a Gherkin background, and that includes any `configure` step in it. Two consequences follow: - Every scenario in the feature starts from the same configured state, even if the scenario before it changed the config. - If the `Background` also makes an HTTP call to obtain something the configure needs — a token, a session id — that call runs once per scenario too. When you want it once for the whole feature, that is what `callonce` is for; the `configure` line itself still re-applies per scenario, which is what you want. ## Nothing leaks forward Because the `Background` re-runs, a change made inside one scenario cannot survive into the next. Karate's own test suite pins this with a three-scenario feature whose `Background` configures one header: | scenario | what it does | what reaches the wire | |---|---|---| | 1 | nothing extra | the Background header | | 2 | `configure headers = null` | no headers at all | | 3 | `configure headers = { other }` | only `other`, not the Background header | Scenario 3 is the important row twice over. It shows that scenario 2's `null` did not carry forward — scenario 3 got the `Background` state back before it ran — and it shows the second point below. ## A new map replaces, it does not merge Assigning a fresh map to `configure headers` **owns** the header set from then on. The `Background` map is not merged underneath it. If you want both the ambient header and a new one, build the combined map yourself and configure that; there is no additive form of the step. The same applies key by key across the whole `configure` surface. Each key is stored independently, so setting `headers` never disturbs `ssl` or `readTimeout`, but setting `headers` a second time completely replaces the first value. ## What `= null` actually does `* configure headers = null` is not special syntax. The right-hand side is an ordinary expression that evaluates to null, the key is stored as null, and when Karate goes to apply configured headers before a request it finds a value that is not a map and adds nothing. The effect is a clean "forget the ambient headers for the rest of this scenario": - it is scoped like any other `configure` — it clears for the remainder of the current scenario, not the feature; - it clears exactly one key, so `configure cookies = null` and `configure headers = null` are separate decisions; - it is the documented way to drop ambient state deliberately, and Karate's own demo suite uses it to make a call that should be rejected actually get rejected. That last usage is the most honest reason to reach for it: a scenario that asserts "an unauthenticated request is refused" cannot do so while the `Background` keeps stamping credentials onto every call. ## Reviewing for this - If a scenario changes the config, read the `Background` first — that is the state the change starts from. - If a feature is order-dependent, the config is not the cause; each scenario re-derives it. - If a scenario needs "the ambient set plus one", make that explicit in the map rather than assuming a merge. - Keep the negative scenario — the one using `= null` — next to the positive one, so a reader can see that the difference is intentional.

  • If a `Background` sets `configure headers` and scenario two clears it with null, what does scenario three send?
    The `Background` header again. Karate re-runs the `Background` before every scenario, so scenario three is configured from scratch and never sees scenario two's null. This is what makes a feature's scenarios independent of their order, and it is why a `configure` change inside a scenario is a safe, local edit rather than something that quietly reshapes the rest of the file.
  • How do you add one header to the set a `Background` configured, without losing the Background ones?
    Build the combined map and configure that — there is no additive form. Assigning a new map to `configure headers` replaces the configured set entirely, so the usual pattern is to keep the ambient map in a variable in the `Background`, copy it in the scenario, add the extra key, and configure the copy. Alternatively add the extra header with a per-call `header` step, remembering that a configured header of the same name would overwrite it.

saying these in an interview costs you the question

  • Thinks Background runs once per feature, not once per scenario
  • Expects a scenario's configure change to persist into the next scenario
  • Assumes a new configured map merges with the Background map
  • Reads a null assignment as disabling every configure key at once
  • Believes null must be cleared again before the next scenario