When does @Nested improve a test suite versus harm it, and what design trade-offs guide how deeply you nest?

## The value proposition of @Nested `@Nested` is JUnit 5's mechanism to group tests into inner classes (see the basics topic). Its benefit is **expressing structure**: when the thing you test has clear scenarios — *given an empty cart*, *given a cart with items*, *given a logged-out user* — each becomes a nested class. Combined with **`@DisplayName`** (human-readable labels) the IDE/report renders an indented tree that reads like a specification. The outer class holds **shared arrangement**; each nested class adds only what's specific, removing duplicated setup. This is the Behavior-Driven (given/when/then) style mapped onto JUnit. ## Where it goes wrong The same feature, overused, creates problems: 1. **Setup scattering / hidden preconditions.** Each nesting level may have its own `@BeforeEach`. To understand a single test's starting state you must read the *entire* enclosing chain of `@BeforeEach` methods, top to bottom. Two or three levels deep, the preconditions of one test are spread across the file. A reader can no longer answer "what state is this test in?" locally. That hidden coupling is often *worse* than the small duplication nesting was meant to remove. 2. **Fragile shared mutable state.** Nested groups encourage shared outer fields. Under the default `PER_METHOD` lifecycle each test gets a fresh instance, but teams sometimes switch to `@TestInstance(PER_CLASS)` (e.g., for a non-static `@BeforeAll`), and then mutable outer fields **persist across methods**, introducing order-dependent flakiness. 3. **Artificial taxonomy.** Forcing tests into a nesting hierarchy that doesn't match real behavioral branches produces empty or one-test groups — structure for its own sake, adding indentation without meaning. 4. **Teardown-order subtlety.** As nesting deepens, the inner-to-outer `@AfterEach` unwinding becomes easy to misreason about, risking cleanup that releases a resource an outer level still owns. ## Trade-off framework - **Nest to mirror genuine branches, not to satisfy a pattern.** One nested class per real scenario/state; if a level would hold a single test, inline it. - **Keep depth shallow.** One or two levels is almost always enough; beyond that, readability of preconditions degrades faster than duplication is saved. Treat three-plus levels as a smell to justify. - **Keep each level's setup small and explicit.** The less each `@BeforeEach` does, the easier it is to read the chain. Prefer a couple of obvious lines over clever shared builders buried at the outer level. - **Prefer local arrangement when sharing is weak.** If scenarios share little, a flat layout with small per-test setup (or helper factory methods) is clearer than forcing a hierarchy. - **Reserve `PER_CLASS` for true need** and treat shared mutable fields as a hazard; default `PER_METHOD` isolation is the safe baseline. - **Optimize for the reader of a failing test.** When a nested test fails, the engineer should understand its preconditions quickly. If they must trace four levels of setup, the nesting has cost more than it gave. ## The principle `@Nested` is a *readability and organization* tool, not a goal. Use it to make intent and scenario structure obvious and to remove genuine duplication; stop nesting at the point where understanding any single test starts to require reading the whole file. Shallow, meaningful nesting with small, explicit setup beats deep, clever hierarchies every time.