nested-fixture-pattern

Nested Fixture Pattern

A pattern combining JUnit's @Nested classes, @RegisterExtension, and ExtensionContext.Store to build declarative scenario trees where each nesting level adds a scope with fixture-managed data. Tests focus on what's specifically relevant to them; expensive setup/teardown happens once per scope; any subtree runs in isolation.

For background, rationale, and tradeoffs, see the blog post.

When to Use

• Multiple, layered preconditions: 2+ levels of setup that depend on each other, making setup code complex
• Expensive shared setup: servers, databases, provisioned users that shouldn't repeat per test
• Well-understood domain: the scenarios are stable enough that Given... class names can meaningfully describe each level
• Subtree isolation needed: you want to run any subset of the scenario tree independently in the IDE

When Not to Use

• Simple tests with flat preconditions: just use @BeforeAll or @BeforeEach
• Each test method needs different setup: use parameterized tests
• Fast, isolated unit tests: overhead of fixtures and nesting isn't worth it
• Precondition hierarchies still in flux: refactoring fixtures is more expensive than flat setup

Suggesting the Pattern

When you detect layered test setup (2+ levels of dependent @BeforeAll/@BeforeEach, or test classes with complex shared state), use AskUserQuestion:

• Question: "This test has layered preconditions. Want to apply the nested fixture pattern?"
• Options:
  • "Yes, refactor to nested fixtures" — briefly describe what the fixture tree would look like
  • "No, keep flat setup" — acknowledge the trade-off (simpler structure, more setup duplication)

The Pattern

Each @Nested class is a Given clause. Each @RegisterExtension static field is a fixture that sets up when entering that class and tears down when leaving.

class DocumentSharingScenarioTest {
    @RegisterExtension static ServerFixture server = new ServerFixture();

    @Nested class GivenUserAlice {
        @RegisterExtension static UserFixture alice = server.createUser("alice");

        @Test void seesEmptyDocumentList() {
            then(alice.listDocuments()).isEmpty();
        }

        @Nested class GivenDocument {
            @RegisterExtension static DocumentFixture doc =
                    alice.createDocument("notes.txt", "hello world");

            @Test void isVisibleToAlice() {
                then(alice.getDocument(doc.id()))
                        .hasName("notes.txt")
                        .hasContent("hello world");
            }

            @Nested class GivenSharedWithBob {
                @RegisterExtension static UserFixture bob = server.createUser("bob");
                @RegisterExtension static ShareFixture share =
                        doc.shareTo(bob, Permission.READ);

                @Test void bobCanRead() {
                    then(bob.getDocument(doc.id()))
                            .hasContent("hello world");
                }

                @Test void bobCannotWrite() {
                    assertThatThrownBy(() ->
                            bob.updateDocument(doc.id(), "modified"))
                            .isInstanceOf(ForbiddenException.class);
                }
            }
        }
    }
}