State Sharing & Dependency Injection

## What the World is cucumber-js builds **one object per scenario** and calls it the *World*. Before the first step of a scenario runs, Cucumber constructs a World; it then invokes every step definition function and every hook function belonging to that scenario with that object bound to `this`. When the scenario ends — passed, failed or skipped — the object is dropped, and the next scenario gets a brand new one. That is the whole design: **the World is one scenario's private scratch space.** It exists so that step definitions living in separate files can hand data to each other without a module-level variable. In a courtroom-scheduling suite, a `Given` writes the case number it just put on the docket onto `this`, and a `Then` three files away reads it back. If you register nothing, Cucumber instantiates its built-in World class, which already carries three useful members: - `this.attach(data, mediaType)` — attaches a screenshot, a response body or a log line to the scenario's result so formatters can render it. - `this.log(text)` — a shortcut for attaching plain text. - `this.parameters` — *world parameters*, supplied by the `--world-parameters` command-line option or the `worldParameters` configuration key. This is how a base URL or a scheduling-API token reaches steps without being hardcoded in a step definition file. ## Registering a custom World Custom Worlds are registered once, from support code, with `setWorldConstructor`. It takes the class itself, not an instance — Cucumber calls `new` on it for you, per scenario. ```javascript const { setWorldConstructor, World } = require('@cucumber/cucumber') class CourtroomWorld extends World { constructor(options) { super(options) this.scheduledCase = null this.conflicts = [] } } setWorldConstructor(CourtroomWorld) ``` Two things matter here. First, the constructor receives an **options object** which carries `attach`, `log` and `parameters`; pass it to `super(options)` when you extend the exported `World`, or those helpers stop working. Second, `setWorldConstructor` is a *registration*, not a per-file declaration — calling it in one support file applies it to the whole run, and calling it twice with different classes means the last registration wins. ## Lifetime, precisely | Moment | What happens to the World | | --- | --- | | Support code is loaded | Nothing — only the constructor is registered | | Just before a scenario's first hook | A new instance is constructed | | Every step and hook of that scenario | The same instance, bound as `this` | | Each row of an `Examples` table | A separate scenario, therefore a separate instance | | Scenario ends (pass, fail or skip) | The instance is discarded | | A retried attempt of the same scenario | A fresh instance for each attempt | Three consequences follow from that table: 1. **Anything expensive in the constructor is paid once per scenario.** A World that opens a database connection makes a 300-scenario suite open 300 connections. Long-lived resources belong outside the World; the World holds a *reference* to them. 2. **You cannot use the World as a cache across scenarios.** That is deliberate — the isolation is the feature. If two scenarios must see the same value, that value is configuration, not scenario state. 3. **A `Scenario Outline` with nine rows produces nine Worlds**, so a row cannot observe what an earlier row did. ## `this`, and the arrow-function trap `this` inside a step definition is bound **at call time** by Cucumber. An arrow function does not accept a `this` binding; it captures the `this` of the surrounding scope, which in a module is not the World. So this fails: ```javascript Given('case {string} is on the docket', (caseNumber) => { this.scheduledCase = caseNumber // not the World }) ``` and the classical `function` form works: ```javascript Given('case {string} is on the docket', function (caseNumber) { this.scheduledCase = caseNumber }) ``` The symptom is usually a `TypeError` on a property of `undefined`, or a value that silently reads back as `undefined` in a later step. The same rule applies to hook callbacks. TypeScript users often reach for a typed World class precisely so the compiler catches the mistake. ## What belongs on it - **Yes:** identifiers created by a `Given` (the hearing id, the courtroom, the case number), the last HTTP response, handles to resources scoped to this scenario. - **No:** constants and configuration — those come in through world parameters; and caches meant to survive scenarios, which reintroduce the coupling the World removes. - **Careful:** the World turns into a god object on a large suite. Group state into small domain objects held as fields (`this.docket`, `this.session`) rather than a flat list of forty properties, and add behaviour to those objects instead of writing helper functions that take the World as an argument.