In Cucumber-JVM with Spring, what does @CucumberContextConfiguration mark and why may only one class carry it?

## What the annotation marks `cucumber-spring` is the object factory that hands Cucumber-JVM's glue classes to Spring instead of instantiating them directly. For that to work, Spring's TestContext framework needs to know **which configuration describes the application context** — the same question `@SpringBootTest` or `@ContextConfiguration` answers on an ordinary Spring test class. But Cucumber has no test class: it has a glue path full of step definition classes, none of them privileged. `@CucumberContextConfiguration` is how you privilege exactly one of them. You put it on a class in the glue path, together with the Spring annotation that describes the context: ```java import io.cucumber.spring.CucumberContextConfiguration; import org.springframework.boot.test.context.SpringBootTest; @CucumberContextConfiguration @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) public class CucumberSpringConfiguration { } ``` The class is usually empty. Its whole job is to carry annotations. It must nonetheless sit **inside the glue path**, because that is where Cucumber looks; a configuration class in a package the runner never scans is the most common reason a suite reports that no context configuration was found. ## Why exactly one Cucumber builds one Spring `TestContextManager` for the run from the annotated class. Two annotated classes would describe two different contexts, and nothing in the model says which one the step definitions belong to — a scenario whose steps span both would be incoherent. Rather than guess, Cucumber **fails at startup** and reports that more than one glue class carries the annotation, naming them. That is worth knowing as a diagnosis, because the failure has a mundane cause: a suite grows a second configuration class when a team adds a "web" configuration next to an existing "service" one. The fix is not a second annotation but a single configuration class whose Spring annotations cover both needs, or profiles selected through the Spring annotations on that one class. ## What the step definition classes get Once cucumber-spring is in charge, glue classes stop being plain objects: - They are **created as Spring beans**, so a constructor parameter of any application type is injected, and `@Autowired` works on fields. - They can inject **the real collaborators of the application under test** — a repository, a scheduling service, a `TestRestTemplate` bound to the random port. - They share those beans with each other, which is the state-sharing answer: two step definition classes injecting the same singleton bean see the same object, and two classes injecting the same scenario-scoped bean see the same per-scenario object. - They can use Spring test facilities the same way an ordinary test class would, including transactional behaviour and property overrides declared on the configuration class. ## Context caching versus scenario scope This is the part that separates a candidate who has run a Spring suite from one who has read about it. | Thing | Lifetime | | --- | --- | | The Spring application context | Cached and reused across scenarios by Spring's TestContext framework | | Singleton beans inside that context | As long as the context — the whole run, in practice | | Glue (step definition) instances | Recreated for every scenario | | Beans in cucumber-spring's `cucumber-glue` scope | Recreated for every scenario, discarded afterwards | Context caching is a performance decision and a good one — starting a Spring Boot context per scenario would make a courtroom-scheduling suite unrunnable inside an eleven-minute pipeline budget. But it has a consequence people miss: **a mutable singleton bean is shared by every scenario in the run.** If a step definition writes the current case number onto an application-scoped bean, the isolation you thought DI gave you is gone, and the symptom is exactly the same order-dependent flakiness a static field produces. The rule that follows: 1. Mutable per-scenario state goes in a scenario-scoped bean or in a plain object created per scenario — not in a singleton. 2. Singletons in the test configuration are for **immutable** things: clients, configuration, fixtures that never change. 3. If you must mutate application state (a seeded database, a stubbed clock), reset it explicitly at a scenario boundary rather than hoping the context restart will do it, because there is no restart. ## Failure modes to recognise - **"No context configuration"** — the annotated class is not in the glue path. - **Two annotated classes** — the run refuses to start; consolidate into one. - **Fields null in a step definition** — cucumber-spring is not on the test classpath, so Cucumber is still instantiating glue classes itself and Spring never sees them. - **A scenario passing alone and failing in the suite** — almost always mutable state on a cached singleton. One more practical constraint: cucumber-spring is an object factory, and only one object factory may be active. Leaving `cucumber-picocontainer` on the classpath beside it gives Cucumber two candidates and it will not choose for you.