Introduce `@AutoClose` #3592

bjmi · 2023-12-05T11:00:06Z

Overview

Closes #3367

I hereby agree to the terms of the JUnit Contributor License Agreement.

Definition of Done

There are no TODOs left in the code
Method preconditions are checked and documented in the method's Javadoc
Coding conventions (e.g. for logging) have been followed
Change is covered by automated tests including corner cases, errors, and exception handling
Public API has Javadoc and @API annotations
Change is documented in the User Guide and Release Notes

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/AutoCloseExtension.java

sbrannen

Thanks for the PR! 👍

I've requested several minor changes.

In addition, please introduce at least one example in the User Guide in the "Writing Tests" chapter.

Thanks

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AutoClose.java

junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/AutoCloseTests.java

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/AutoCloseExtension.java

junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/AutoCloseTests.java

documentation/src/test/java/example/AutoCloseDemo.java

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AutoCloseExtension.java

documentation/src/docs/asciidoc/link-attributes.adoc

sbrannen

Thanks for making all of the requested changes! 👍

I think this PR looks good now.

All that's left are the changes to the link attributes and the demo.

Though we can take care of those for you if you don't have time.

Note, however, that there is no rush. I don't plan to merge this until 2024. 😉

Enjoy your end-of-year celebrations!

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

Signed-off-by: Björn Michael <[email protected]>

* Test AutoCloseExtension * Register extension as stateless Signed-off-by: Björn Michael <[email protected]>

Signed-off-by: Björn Michael <[email protected]>

Implement TestInstancePreDestroyCallback instead Signed-off-by: Björn Michael <[email protected]>

Signed-off-by: Björn Michael <[email protected]>

junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/AutoCloseTests.java

Signed-off-by: Björn Michael <[email protected]> Closes 3367 Closes junit-team#3592

See junit-team#3367 See junit-team#3592

sbrannen · 2023-12-30T14:37:36Z

Hey @bjmi,

Since I started investigating the support for @Nested test classes, I ended up putting in a fair amount of work locally on my machine.

Consequently, I have decided to mark this PR as a "draft", and I will continue the rest of the work on my branch, which you can see here: main...sbrannen:junit5:issues/3592-AutoClose.

In light of that, there's no need to make further modifications to this PR. All of your hard work is contained in the first commit on the above branch! 👍

See junit-team#3367 See junit-team#3592

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AutoCloseExtension.java

Signed-off-by: Björn Michael <[email protected]> See junit-team#3367 See junit-team#3592

Closes junit-team#3367 Closes junit-team#3592

Outdated

Closes junit-team#3367 Closes junit-team#3592

See junit-team#3367 See junit-team#3592

Signed-off-by: Björn Michael <[email protected]> See junit-team#3367 See junit-team#3592

Closes junit-team#3367 Closes junit-team#3592

See junit-team#3367 See junit-team#3592

Closes junit-team#3367 Closes junit-team#3592

Signed-off-by: Björn Michael <[email protected]> See junit-team#3367 See junit-team#3592

Closes junit-team#3367 Closes junit-team#3592

This commit introduces an @⁠AutoClose annotation that can be applied to fields within JUnit Jupiter tests to automatically close the annotated resource after test execution. Signed-off-by: Björn Michael <[email protected]> See junit-team#3367 See junit-team#3592

This commit revises the @⁠AutoClose support that was introduced in the previous commit as follows. - Javadoc and User Guide documentation for @⁠AutoClose, now explicitly explain ordering, inheritance, evaluation order, scope, and lifecycle for @⁠AutoClose fields. - Overhauled and simplified the implementation of the AutoCloseExtension by closing fields immediately instead of wrapping each field in a CloseableResource and storing it in the ExtensionContext.Store, and revised the implementation of preDestroyTestInstance() so that it makes use of TestInstancePreDestroyCallback.preDestroyTestInstances() to ensure proper semantics within @⁠Nested test class hierarchies. Combined, these changes ensure that fields are closed in the proper order and that any resulting exceptions are thrown directly instead of nested as a cause of an exception that occurs when the ExtensionContext.Store is closed. - Improved diagnostics by failing eagerly if an @⁠AutoClose annotation is declared with a blank close-method name or if the annotated field is a primitive type or array. - Since having the AutoCloseExtension in the org.junit.jupiter.api package introduced a cycle between the api and api.extension packages, the AutoCloseExtension now resides in the org.junit.jupiter.engine.extension package in junit-jupiter-engine and is loaded as a built-in extension. - The AutoCloseDemo now uses a WebClient that needs to be closed instead of a JDBC Connection, thereby avoiding the need to throw an SQLException and simplifying the example. - Overhauled AutoCloseTests to test all known use cases (including test class hierarchies and @⁠Nested test class hierarchies) and error cases. Closes junit-team#3367 Closes junit-team#3592

This commit introduces an @⁠AutoClose annotation that can be applied to fields within JUnit Jupiter tests to automatically close the annotated resource after test execution. Signed-off-by: Björn Michael <[email protected]> See #3367 See #3592

sbrannen · 2024-01-04T11:19:34Z

This has been merged into main in e32c2e3 and revised in 89a0201.

Thanks again for the contribution! 👍

This comment was marked as outdated.

Sign in to view

bjmi force-pushed the Introduce_@AutoClose branch from 965af1b to c137a93 Compare December 5, 2023 11:04

marcphilipp previously requested changes Dec 15, 2023

View reviewed changes

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/AutoCloseExtension.java Outdated Show resolved Hide resolved

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/AutoCloseExtension.java Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

sbrannen requested changes Dec 21, 2023

View reviewed changes

sbrannen added theme: programming model component: Jupiter type: new feature labels Dec 21, 2023

sbrannen changed the title ~~Introduce @AutoClose~~ Introduce @AutoClose Dec 21, 2023