Cucumber reruns Background before every Examples row - when does that setup belong in a hook instead?

`Background` is Gherkin's shared-context block, and the design question is not what it does but what it should hold. Two properties of how Cucumber executes it decide almost every case. ## The multiplication nobody sees in the file Cucumber re-runs the Background steps before **each** scenario in the file, and a `Scenario Outline` is not one scenario - each `Examples` row expands into its own runnable scenario. So the cost is `Background steps x scenarios`, where the scenario count includes every row of every table. A seed-catalogue ordering service had a 4-step Background above one outline with 23 `Examples` rows: **92** Background step executions from a block that reads like four lines. At roughly 0.4 s per step that is 37 seconds added to a feature the file makes look trivial. Split over a 3-way parallel fork it is still a third of that on the critical path, and behind a merge queue that serialises everything it lands on every merge, not once a day. The file gives you no hint of this. That is why Background cost is a senior-level reading skill: you have to multiply by the row count in your head. ## Specification or machinery The second test is about the reader, not the clock. Background text is printed with every scenario in reports, so it is part of the document. Ask: **if I deleted this line, would the scenarios below become harder to understand?** | Line | Verdict | Where it goes | |---|---|---| | the catalogue lists 'Cherokee Trail of Tears' beans | Context a reader needs | `Background` | | "the database is reset" | Machinery | Hook | | "an authentication token has been minted" | Machinery | Hook | | "the buyer has a confirmed account" | Context, if the rules depend on it | `Background` | | "the screenshot directory is cleaned" | Machinery | Hook | Machinery in `Background` has a second cost beyond time: it teaches readers that the feature file is a script, and every subsequent scenario is written in that register. ## The three levers when most scenarios do not need it `Background` cannot be tagged and cannot be applied to a subset - it covers every scenario beneath it. So when only some scenarios need the setup: 1. **Split the feature file.** If two groups of scenarios need genuinely different context, they are two features. This is the move people skip because the file has a tidy name, and it is usually the right one. 2. **Move the work into a hook selected by a tag.** Every implementation offers this: Cucumber-JVM's `@Before` takes a tag expression, cucumber-js accepts tags when registering a `Before` hook, Behave inspects the scenario's tags in `environment.py`, SpecFlow/Reqnroll filters a `[BeforeScenario]` binding by tag. The scenarios that need the fixture carry the tag; the rest pay nothing and their reports stay clean. 3. **Make it cheap instead of moving it.** Sometimes the setup genuinely is context every scenario needs. Then the answer is not relocation but cost: seed through a service call rather than the interface, reuse a prepared fixture, keep the Background to the two or three facts that matter. ## What stays Keep `Background` short - a handful of Given lines, no `When`, no `Then`. Keep it to facts the scenarios below actually depend on. Resist the "shared setup" reflex that grows it one line at a time until it is the longest block in the file and half the scenarios are unaffected by two thirds of it. A practical review habit: for each Background line, count how many scenarios in the file would fail if it were removed. A line that only two of eleven scenarios need is in the wrong place, whatever the file's name suggests. ## Ordering, briefly Hook code registered to run before a scenario executes before the Background steps do, which is what makes the split workable: the hook establishes the machinery, the Background states the facts, and the scenario reads as specification with no fixture noise in it. The precise hook levels and their ordering rules are a topic of their own; for scenario design, what matters is that the hook path exists and is selectable by tag while `Background` is neither. ## The failure mode this prevents The suite where every feature opens with eleven Background lines, most scenarios need three of them, and the run takes minutes longer than the work it does. Nobody deletes a Background line because nobody can tell which scenarios depend on it - so it grows forever. Deciding placement at write time, on the two tests above, is what stops that accumulation.