Introduce @AutoClose mechanism for closing field resources after test execution

[bjmi]

Occasionally I create and use resources in unit tests that should be released after test execution. You usually do this in tear-down methods. But in a lot of cases a simple @AutoClose annotated field would be sufficient for that, something similar to @TempDir for temporary folders.

This would spare boilerplate code like:

Service service = new ClosableService();

@AfterEach
void cleanup() {
    service.close();
}

Allowing it to be replaced by:

@AutoClose
Service service = new ClosableService();

Static fields would be closed after all tests have run and instance fields after each test.

Other annotation names could be @Destroy or @AutoDestroy.

If there is no close() method, it should be possible to specify a custom method name -- for example, destroy, dispose, shutdown, etc.

Deliverables

• A new @AutoClose annotation
• Update User Guide Writing Tests -> Annotations

[feech]

what's about the order several resources close?

[bjmi]

I have no strong opinion about it. Two thoughts:

• To simplify, one could define the order unspecific and refer to Class.getDeclaredFields() behaviour. If a sophisticated order is required than the existing tear-down method approach should be taken.

Javadoc: The elements in the returned array are not sorted and are not in any particular order.

• Add @AutoClose.priority property where the order can be specified by e.g. a number.

[marcphilipp]

Team decision: Introduce attribute-less @AutoClose annotation that only works on fields of types that implement java.lang.AutoCloseable without any ordering guarantees for now.

[bjmi]

Limiting to java.lang.AutoCloseable will lose a lot of usages. Some examples are:

• java.util.concurrent.ExecutorService.shutdown()
• org.eclipse.swt.widgets.Shell.dispose()
• com.icegreen.greenmail.util.GreenMail.stop()

A similar solution are Spring Beans destroy methods (@Bean.destroyMethod). Any public, no-arg method can be specified for a container-managed bean and the container automatically invokes them on application context shutdown to properly release these instances. The method names close() and shutdown() are automatically detected if not explicitely specified.

Therefore I propose following annotation and just search for a public and no-arg method and disregard the type of the field.

@interface AutoClose {
    /** @return method name to execute in order to release resource. */
    String value() default "close";
}

I could provide a solution that uses ExtensionContext.Store where @AutoClose annotated fields are registered as wrapped Store.CloseableResources and are automatically released on test shutdown via NamespacedHierarchicalStore.close().

[sormuras]

Supporting java.lang.AutoCloseable will enable already a lot usages - and wrapping a resource in a Store.CloseableResource holder/helper is always possible (today).

java.util.concurrent.ExecutorService does implement java.lang.AutoCloseable since Java 19: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/ExecutorService.html#close()

[bjmi]

java.util.concurrent.ExecutorService does implement java.lang.AutoCloseable since Java 19: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/ExecutorService.html#close()

Thanks for the tip. Unfortunately, this doesn't help users who are dealing with previous versions.

[sbrannen]

Team decision: Introduce attribute-less @AutoClose annotation that only works on fields of types that implement java.lang.AutoCloseable without any ordering guarantees for now.

We have decided to support a configurable close-method name which defaults to close.

In addition, due to the nature of our reflection utilities, we do in fact provide some guarantees regarding ordering, as I've outlined in the Javadoc for @AutoClose:

Inheritance

@AutoClose fields are inherited from superclasses as long as they are not hidden. Furthermore, @AutoClose fields from subclasses will be closed before @AutoClose fields in superclasses.

Registration Order

When multiple @AutoClose fields exist within a given test class, the order in which the resources are closed depends on an algorithm that is deterministic but intentionally nonobvious. This ensures that subsequent runs of a test suite close resources in the same order, thereby allowing for repeatable builds.

[sbrannen]

Reopening to make use of ThrowableCollector when closing resources to ensure that all fields are given a chance to be closed.

[sbrannen]

RE-Reopening to make sure that the use of ThrowableCollector is properly applied in @Nested test class hierarchies. 👀