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.