From e205ccd802038c24a50a1453765ba8c4c31c41c7 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 27 May 2023 18:29:10 +0200 Subject: [PATCH] Polish contribution See #3311, #3313 --- .../release-notes-5.10.0-RC1.adoc | 6 +++-- .../asciidoc/user-guide/writing-tests.adoc | 22 ++++++++++++------- .../test/java/example/TempDirectoryDemo.java | 9 ++++---- .../org/junit/jupiter/api/io/TempDir.java | 2 +- .../TempDirectoryMetaAnnotationTests.java | 15 ++++++------- 5 files changed, 30 insertions(+), 24 deletions(-) diff --git a/documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-RC1.adoc b/documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-RC1.adoc index 0aba01a6d22..22c369a4de9 100644 --- a/documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-RC1.adoc +++ b/documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-RC1.adoc @@ -24,8 +24,6 @@ JUnit repository on GitHub. ==== New Features and Improvements * New `@SelectMethod` selector support in the `@Suite` test engine. -* Add `@SelectMethod` selector support to `@Suite` test engine -* `@TempDir` can now be used in meta-annotations [[release-notes-5.10.0-RC1-junit-jupiter]] @@ -41,6 +39,10 @@ JUnit repository on GitHub. ==== New Features and Improvements +* `@TempDir` can now be used as a meta-annotation in order to create custom _composed + annotations_. See the `@JimfsTempDir` example in the + <<../user-guide/index.adoc#writing-tests-built-in-extensions-TempDirectory, User Guide>> + for details. * Lifecycle and thread-safety semantics are now documented for the `TempDirFactory` SPI. diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 9c09c61efad..142f752e47c 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -2627,8 +2627,8 @@ they are instantiated, but they can assume that their `createTempDirectory(...)` thread. The default implementation available in Jupiter delegates the directory creation to -`java.nio.file.Files::createTempDirectory`, passing `junit` as the prefix string -to be used in generating the directory's name. +`java.nio.file.Files::createTempDirectory`, passing `junit` as the prefix string to be +used in generating the directory's name. The following example defines a factory that uses the test name as the directory name prefix instead of the `junit` constant value. @@ -2640,7 +2640,7 @@ include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_name_p ---- It's also possible to use an in-memory file system like `{Jimfs}` for the creation of the -temporary directory. The following example shows how to do it. +temporary directory. The following example demonstrates how to achieve that. [source,java,indent=0] .A test class with a temporary directory created with the Jimfs in-memory file system @@ -2648,17 +2648,23 @@ temporary directory. The following example shows how to do it. include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_jimfs] ---- -`@TempDir` can also be used in meta-annotations to reduce repetition. +`@TempDir` can also be used as a <> to +reduce repetition. The following code listing shows how to create a custom `@JimfsTempDir` +annotation that can be used as a drop-in replacement for +`@TempDir(factory = JimfsTempDirFactory.class)`. [source,java,indent=0] -.A definition of a meta-annotation using `@TempDir` +.A custom annotation meta-annotated with `@TempDir` ---- -include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_meta_annotation] +include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_composed_annotation] ---- + +The following example demonstrates how to use the custom `@JimfsTempDir` annotation. + [source,java,indent=0] -.A test class using a meta-annotation +.A test class using the custom annotation ---- -include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_meta_annotation_usage] +include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_composed_annotation_usage] ---- You can use the `junit.jupiter.tempdir.factory.default` diff --git a/documentation/src/test/java/example/TempDirectoryDemo.java b/documentation/src/test/java/example/TempDirectoryDemo.java index d75dccc1cfc..d4596169899 100644 --- a/documentation/src/test/java/example/TempDirectoryDemo.java +++ b/documentation/src/test/java/example/TempDirectoryDemo.java @@ -147,17 +147,16 @@ public void close() throws IOException { } // end::user_guide_factory_jimfs[] - // tag::user_guide_meta_annotation[] + // tag::user_guide_composed_annotation[] @Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.PARAMETER }) @Retention(RetentionPolicy.RUNTIME) @TempDir(factory = JimfsTempDirFactory.class) @interface JimfsTempDir { - } - // end::user_guide_meta_annotation[] + // end::user_guide_composed_annotation[] static - // tag::user_guide_meta_annotation_usage[] + // tag::user_guide_composed_annotation_usage[] class JimfsTempDirAnnotationDemo { @Test @@ -166,6 +165,6 @@ void test(@JimfsTempDir Path tempDir) { } } - // end::user_guide_meta_annotation_usage[] + // end::user_guide_composed_annotation_usage[] } diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/io/TempDir.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/io/TempDir.java index d80c882bbcb..519b14f1e2c 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/io/TempDir.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/io/TempDir.java @@ -90,7 +90,7 @@ * * @since 5.4 */ -@Target({ ElementType.FIELD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE }) +@Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.PARAMETER }) @Retention(RetentionPolicy.RUNTIME) @Documented @API(status = STABLE, since = "5.10") diff --git a/junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/TempDirectoryMetaAnnotationTests.java b/junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/TempDirectoryMetaAnnotationTests.java index c657cec0225..2dad2e09fe5 100644 --- a/junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/TempDirectoryMetaAnnotationTests.java +++ b/junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/TempDirectoryMetaAnnotationTests.java @@ -34,19 +34,19 @@ class TempDirectoryMetaAnnotationTests extends AbstractJupiterTestEngineTests { @Test void annotationOnField() { - executeTestsForClass(AnnotationOnFieldTestCase.class).testEvents().assertStatistics( - stats -> stats.started(1).succeeded(1)); + executeTestsForClass(AnnotationOnFieldTestCase.class).testEvents()// + .assertStatistics(stats -> stats.started(1).succeeded(1)); } @Test void annotationOnParameter() { - executeTestsForClass(AnnotationOnParameterTestCase.class).testEvents().assertStatistics( - stats -> stats.started(1).succeeded(1)); + executeTestsForClass(AnnotationOnParameterTestCase.class).testEvents()// + .assertStatistics(stats -> stats.started(1).succeeded(1)); } static class AnnotationOnFieldTestCase { - @MetaTempDir + @CustomTempDir private Path tempDir; @Test @@ -59,7 +59,7 @@ void test() { static class AnnotationOnParameterTestCase { @Test - void test(@MetaTempDir Path tempDir) { + void test(@CustomTempDir Path tempDir) { assertTrue(Files.exists(tempDir)); } @@ -68,8 +68,7 @@ void test(@MetaTempDir Path tempDir) { @TempDir @Target({ ElementType.FIELD, ElementType.PARAMETER }) @Retention(RetentionPolicy.RUNTIME) - @interface MetaTempDir { - + @interface CustomTempDir { } }