How do you decide whether a large JUnit 5 test class should be organized with @Nested groupings or split into several separate top-level test classes?

## The core criterion: shared fixture `@Nested` exists to let a child container reuse and extend the enclosing instance's setup. That is the entire mechanism, so it is also the entire justification. Ask of each proposed group: *would its `@BeforeEach` build on what the outer one produced?* - **Yes** — nest. The outer class constructs the subject; the nested class puts it in a state (`when the cart is empty`, `when the item is out of stock`, `when the token has expired`); the methods assert outcomes. Each level states only its delta, and the reported tree reads as a specification. - **No** — split. A group that ignores the outer fixture gains nothing from nesting and pays for it: readers must still scan the outer setup to be sure it is irrelevant. A useful smell: if a nested class starts by *undoing* something the outer `@BeforeEach` did, the nesting is wrong. ## Depth discipline Nesting depth is unbounded in JUnit, but comprehension is not. At depth three, the state a test operates on is defined across four `@BeforeEach` methods spread over hundreds of lines. Reviewers stop verifying the setup and start trusting it, which is exactly when a stale fixture slips through. Practical rule: **two levels by default, three only when the third is genuinely a sub-state of the second.** If you want depth four, you have found a second subject — extract it. ## File size, ownership and churn Structure is not the only cost of a large file. A test class that every feature touches becomes a merge-conflict hotspot, a slow file to open, and a place where unrelated changes review together. Even a beautifully nested 900-line class is usually better as three files of 300 lines split by subject — the nesting quality is unchanged, the collaboration cost drops. Also weigh ownership: if two nested groups are maintained by different teams or move at different speeds, separate files give independent history, independent blame and independent review. ## Tooling consequences - **Selection and filtering.** A `@Nested` container is a child node addressed by the platform's unique ID. Selecting one from a build tool by class name means naming the binary form with `$`, which needs escaping in some shells. Selecting a top-level class is trivial. If your team routinely runs sub-groups from the command line, that friction is real. - **Sharding.** CI sharding usually distributes *classes*. One enormous nested class is one indivisible unit of work; splitting it lets the shards balance. - **Reporting.** Some CI dashboards flatten the tree and show only the method display name, losing the scenario context — which is when `@DisplayNameGeneration` with indicative sentences becomes worth turning on. - **Parallel execution.** Execution-mode configuration declared on the enclosing class is inherited by nested classes, so the whole file shares one concurrency policy. If one group needs `SAME_THREAD` because it touches a static or an external resource while the rest can run concurrently, separate classes express that more honestly. ## Shared mutable state Under the default per-method lifecycle, isolation is free: fresh outer and nested instances per test. That safety disappears the moment someone adds `@TestInstance(PER_CLASS)` (inherited by all nested classes) or a `static` field to speed something up. Large nested files are where those shortcuts accumulate, because the expensive fixture is visible and tempting to hoist. Guard that boundary in review: expensive shared setup belongs in an extension with explicit lifecycle, not in a static field inside a deep nest. ## A decision procedure 1. Group the tests by the **state** they need. If the groups form a hierarchy over one subject → `@Nested`, one level per state distinction. 2. If the groups differ by **subject**, collaborator, or transport → separate top-level classes. 3. Cap depth at two (three exceptionally). 4. Cap file size by judgement (a few hundred lines); when exceeded, split by subject before flattening structure. 5. Give the outer class the subject name, each nested class a `when…`/`given…` name, each method an outcome name. 6. Keep isolation defaults; treat `PER_CLASS` and static fixtures as decisions requiring justification. ## What a strong answer sounds like Name the shared-fixture criterion first, then depth, then the collaboration and tooling costs, and finish with the isolation risk. Weak answers argue purely from aesthetics ("nesting is cleaner") or from a blanket rule ("never nest") without connecting to fixture reuse, which is the only thing the mechanism actually provides.