nested-fixture-pattern

name	nested-fixture-pattern
description	This skill should be used when working on Java projects with JUnit tests that have layered preconditions, expensive shared setup (servers, databases, provisioned users), or complex scenario trees. Trigger phrases include "nested fixture", "fixture pattern", "scenario tree", "layered test setup", or when the user is writing integration tests with multiple levels of dependent setup/teardown. Complements the Java and TDD skills.
version	0.1.0

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);
                }
            }
        }
    }
}

Writing Fixtures

Each fixture implements BeforeAllCallback and guards setup with computeIfAbsent:

class UserFixture implements BeforeAllCallback {
    private final ApiClient apiClient;
    private final String name;
    private String id;

    UserFixture(ApiClient apiClient, String name) {
        this.apiClient = apiClient;
        this.name = name;
    }

    @Override public void beforeAll(ExtensionContext context) {
        context.getStore(GLOBAL).computeIfAbsent(this, k -> {
            id = apiClient.createUser(name);
            return (AutoCloseable) () -> apiClient.deleteUser(id);
        });
    }

    String userId() {return id;}
}

Teardown

The computeIfAbsent lambda returns an AutoCloseable that fires when the declaring context ends. The fixture holds state; the store holds the cleanup handle.

JUnit 5 vs 6: JUnit 5 uses getOrComputeIfAbsent and CloseableResource. JUnit 6 uses computeIfAbsent and AutoCloseable.

Optional: Fixtures as Access Points

Fixtures naturally become the access point for everything they set up. Tests and nested classes call methods on the fixture directly rather than reaching into its fields:

class ServerFixture implements BeforeAllCallback {
    private String baseUrl;
    private ApiClient client;

    @Override public void beforeAll(ExtensionContext context) {
        context.getStore(GLOBAL).computeIfAbsent(this, k -> {
            // ... start server ...
            baseUrl = "http://localhost:" + port;
            client = new ApiClient(baseUrl);
            return (AutoCloseable) () -> server.stop();
        });
    }

    ApiClient client() { return client; }
    String baseUrl() { return baseUrl; }
    UserFixture createUser(String name) { return new UserFixture(this, name); }
}

This applies to any state accumulated during setup: injected clients, auth tokens, base URLs, created resource IDs. Expose them as methods; don't make callers reach into fields.

Fixtures as Factories

Parent fixtures can create child fixtures via factory methods. The parent wires context (API clients, auth tokens, resource IDs) so the child declaration stays clean:

static ServerFixture server = new ServerFixture();
static UserFixture alice = server.createUser("alice");
static DocumentFixture doc = alice.createDocument("notes.txt", "hello world");

When not to create a child fixture class

Only write a fixture class when there is teardown to manage, or when the same setup is shared across multiple sibling @Nested classes. If neither applies, a @BeforeAll method in the nested class is simpler and equally correct.

In that case, the parent fixture can expose plain action methods that return domain values directly, rather than fixture objects. The @Nested class calls them from @BeforeAll:

class TaskFixture implements BeforeAllCallback {
    Task task;

    // lifecycle-managed: needs teardown -> fixture class
    // (createTask registered in computeIfAbsent, deleteTask in AutoCloseable)

    // no teardown, not shared across siblings -> plain method
    Task complete() { return client().completeTask(task.id); }
    boolean delete() { return client().deleteTask(task.id); }
}

@Nested class GivenTaskIsCompleted {
    static Task completed;

    @BeforeAll static void completeTask() {
        completed = task.complete();  // no fixture class needed
    }
    ...
}

Critical Rules

1. Keep factories pure: factory methods must only store parameters, never read fixture state. Field initializers run at class-load time, before beforeAll. Actual work happens inside computeIfAbsent.
2. Declaration order matters: JUnit processes @RegisterExtension fields in source order. A fixture that references another must be declared after it.
3. Always use GLOBAL namespace and this as the store key: this is identity-based, so each fixture instance is independent. Domain values (e.g. a user name) would alias independent fixtures with the same value; types (e.g. UserFixture.class) would alias all fixtures of that type. GLOBAL is sufficient because this is already unique. Never override equals/hashCode on fixtures — the store relies on identity.
4. Give destructive scenarios their own fixture instance: if a @Nested class destroys the shared resource (e.g. deletes a task), it must declare its own fixture rather than sharing the parent's. Otherwise, sibling nested classes that depend on the same resource will fail non-deterministically depending on test execution order.
5. Defer framework-injected dependencies to beforeAll: field initializers run at class-load time, before any injection framework (CDI, Spring, etc.) has populated beans. Never pass an injected object as a constructor argument to a fixture. Instead, look it up lazily inside computeIfAbsent. With Quarkus/CDI:

   @Override public void beforeAll(ExtensionContext context) {
       context.getStore(GLOBAL).computeIfAbsent(this, k -> {
           var client = Arc.container().instance(MyClient.class).get();
           // use client ...
       });
   }