Cleaning up multiple test resources - @AutoClose with collections?

[manhole]

First off, congrats on the 6.0 release! I've been using JUnit for over 20 years and it keeps getting better. Thanks for all the great work.

I've been looking for a good way to clean up multiple test resources, and thought @AutoClose might be a good fit. Here's an idea that might be useful for others too.

Motivation

@AutoClose currently works well for test fixtures declared as fields, but doesn't seem designed for multiple resources created dynamically within test methods. Tests often need to create multiple resources and ensure they're all cleaned up. Since these resources typically have dependencies, cleanup needs to happen in reverse order of creation (LIFO).

Current workaround:

@Test
void test() {
    Group group = createGroup();
    User user1 = createUser();
    User user2 = createUser();
    
    group.addMembers(user1, user2);
    
    // Test with group and users...
    assertThat(group.getMembers()).hasSize(2);
    
    // Need manual cleanup (e.g., @AfterEach or try-finally) in order: user2, user1, group...
}

Proposal

Allow @AutoClose to work with List:

@AutoClose
private List<AutoCloseable> resources = new ArrayList<>();

@Test
void test() {
    Group group = createGroup();
    resources.add(() -> deleteGroup(group));
    
    User user1 = createUser();
    resources.add(() -> deleteUser(user1));
    
    User user2 = createUser();
    resources.add(() -> deleteUser(user2));
    
    group.addMembers(user1, user2);
    
    // Test with group and users...
    assertThat(group.getMembers()).hasSize(2);
    
    // Automatically closed in LIFO order: user2, user1, group
}

Resources are closed in LIFO order (reverse of addition). Even if closing fails, all resources are still closed (exceptions are added as suppressed).

Why This Helps

1. Simpler tests: No need for boilerplate code to manually clean up individual resources per test, making tests more readable and maintainable
2. Familiar API: Uses standard Java collections, consistent with @TempDir using Path

---

Would this be useful for your use cases?

I've shown List in the proposal, but would other collection interfaces like Deque be better suited for this? (With Java 21, SequencedCollection would be ideal, but JUnit currently targets Java 17.)

This proposal relates to #3367 where ordering was deferred "for now".

This idea is inspired by the Automated Teardown pattern from Gerard Meszaros's xUnit Test Patterns.

Happy to contribute a PR if there's interest!

[mpkorstanje]

At first review, this proposal seems useful but also non-trivial to with respect to the order in which dependencies are closed and the collections that are supported. As such it would be prudent to incubate this first. Have you considered writing a JUnit Jupiter extension? Similar to the current AutoCloseExtension it could operate on a @AutoCloseCollection annotation instead.

If this seems feasible, you could then propose it to the JUnit Pioneer project and incubate it there.

I imagine that for the end user it might look something like this:

@AutoCloseCollection(order = REVERSE)
private List<AutoCloseable> resources = new ArrayList<>();

@Test
void test() {
    Group group = createGroup();
    resources.add(() -> deleteGroup(group));
    
...
    
    // Automatically closed in LIFO order: user2, user1, group
}