Add factory SPI for @TempDir (#2958)

This adds a factory SPI to `@TempDir`, allowing to define how the
temporary directory is created.

This can be used for custom file systems, but it may also used for
customizing how and where the directory is created for the default file
system.

The intended usage is to extend `TempDirFactory` and provide the class
to the new `factory` attribute of `@TempDir`.

Resolves #2088.
Resolves #2400.

Author: scordio

documentation/documentation.gradle.kts

@@ -54,6 +54,10 @@ dependencies {
 		because("ApiReportGenerator needs it")
 	}
 
+	testImplementation(libs.jimfs) {
+		because("Jimfs is used in src/test/java")
+	}
+
 	standaloneConsoleLauncher(projects.junitPlatformConsoleStandalone)
 }
 

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

@@ -181,6 +181,7 @@ endif::[]
 :AssertJ:                                    https://assertj.github.io/doc/[AssertJ]
 :Gitter:                                     https://gitter.im/junit-team/junit5[Gitter]
 :Hamcrest:                                   https://hamcrest.org/JavaHamcrest/[Hamcrest]
+:Jimfs:                                      https://google.github.io/jimfs/[Jimfs]
 :Log4j:                                      https://logging.apache.org/log4j/2.x/[Log4j]
 :Log4j_JDK_Logging_Adapter:                  https://logging.apache.org/log4j/2.x/log4j-jul/index.html[Log4j JDK Logging Adapter]
 :Logback:                                    https://logback.qos.ch/[Logback]

documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-M1.adoc

@@ -82,6 +82,10 @@ default.
   parameter to set the maximum pool size factor.
 * New `junit.jupiter.execution.parallel.config.dynamic.saturate` configuration
   parameter to disable pool saturation.
+* New `TempDirFactory` SPI for customizing how the `TempDirectory` extension creates
+  temporary directories. See the
+  <<../user-guide/index.adoc#writing-tests-built-in-extensions-TempDirectory, User Guide>>
+  for details.
 
 
 [[release-notes-5.10.0-M1-junit-vintage]]

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

@@ -2613,5 +2613,33 @@ The default cleanup mode is `ALWAYS`. You can use the
 [source,java,indent=0]
 .A test class with a temporary directory that doesn't get cleaned up
 ----
-include::{testDir}/example/TempDirCleanupModeDemo.java[tags=user_guide]
+include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_cleanup_mode]
+----
+
+`@TempDir` supports custom creation of temporary directories via the optional
+`factory` attribute. This allows to define how the temporary directory is created,
+giving control over characteristics such as the directory name, root folder,
+and underlying file system.
+
+Factories can be created by implementing `TempDirFactory`. 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.
+
+The following example defines a factory that uses the test name as the directory name
+prefix instead of the `junit` constant value.
+
+[source,java,indent=0]
+.A test class with a temporary directory having the test name as the directory name prefix
+----
+include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_name_prefix]
+----
+
+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.
+
+[source,java,indent=0]
+.A test class with a temporary directory created with the Jimfs in-memory file system
+----
+include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_jimfs]
 ----

documentation/src/test/java/example/TempDirCleanupModeDemo.java

@@ -13,15 +13,23 @@
 import static java.util.Collections.singletonList;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.io.CleanupMode.ON_SUCCESS;
 
 import java.io.IOException;
+import java.nio.file.FileSystem;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+import com.google.common.jimfs.Configuration;
+import com.google.common.jimfs.Jimfs;
+
 import example.util.ListWriter;
 
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.api.io.TempDirFactory;
 
 class TempDirectoryDemo {
 
@@ -73,4 +81,65 @@ void anotherTestThatUsesTheSameTempDir() {
 	}
 	// end::user_guide_field_injection[]
 
+	static
+	// tag::user_guide_cleanup_mode[]
+	class CleanupModeDemo {
+
+		@Test
+		void fileTest(@TempDir(cleanup = ON_SUCCESS) Path tempDir) {
+			// perform test
+		}
+
+	}
+	// end::user_guide_cleanup_mode[]
+
+	static
+	// tag::user_guide_factory_name_prefix[]
+	class TempDirFactoryDemo {
+
+		@Test
+		void factoryTest(@TempDir(factory = Factory.class) Path tempDir) {
+			assertTrue(tempDir.getFileName().toString().startsWith("factoryTest"));
+		}
+
+		static class Factory implements TempDirFactory {
+
+			@Override
+			public Path createTempDirectory(ExtensionContext context) throws IOException {
+				return Files.createTempDirectory(context.getRequiredTestMethod().getName());
+			}
+
+		}
+
+	}
+	// end::user_guide_factory_name_prefix[]
+
+	static
+	// tag::user_guide_factory_jimfs[]
+	class InMemoryTempDirDemo {
+
+		@Test
+		void test(@TempDir(factory = JimfsTempDirFactory.class) Path tempDir) {
+			// perform test
+		}
+
+		static class JimfsTempDirFactory implements TempDirFactory {
+
+			private final FileSystem fileSystem = Jimfs.newFileSystem(Configuration.unix());
+
+			@Override
+			public Path createTempDirectory(ExtensionContext context) throws IOException {
+				return Files.createTempDirectory(fileSystem.getPath("/"), "junit");
+			}
+
+			@Override
+			public void close() throws IOException {
+				fileSystem.close();
+			}
+
+		}
+
+	}
+	// end::user_guide_factory_jimfs[]
+
 }

documentation/src/test/java/example/TempDirectoryDemo.java

@@ -31,6 +31,7 @@ groovy4 = { module = "org.apache.groovy:groovy", version = "4.0.11" }
 groovy2-bom = { module = "org.codehaus.groovy:groovy-bom", version = "2.5.21" }
 hamcrest = { module = "org.hamcrest:hamcrest", version = "2.2" }
 jfrunit = { module = "org.moditect.jfrunit:jfrunit-core", version = "1.0.0.Alpha2" }
+jimfs = { module = "com.google.jimfs:jimfs", version = "1.2" }
 jmh-core = { module = "org.openjdk.jmh:jmh-core", version.ref = "jmh" }
 jmh-generator-annprocess = { module = "org.openjdk.jmh:jmh-generator-annprocess", version.ref = "jmh" }
 joox = { module = "org.jooq:joox", version = "2.0.0" }
@@ -39,6 +40,7 @@ kotlinx-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core",
 log4j-core = { module = "org.apache.logging.log4j:log4j-core", version.ref = "log4j" }
 log4j-jul = { module = "org.apache.logging.log4j:log4j-jul", version.ref = "log4j" }
 maven = { module = "org.apache.maven:apache-maven", version = "3.9.1" }
+memoryfilesystem = { module = "com.github.marschall:memoryfilesystem", version = "2.5.1" }
 mockito = { module = "org.mockito:mockito-junit-jupiter", version = "5.3.1" }
 opentest4j = { module = "org.opentest4j:opentest4j", version.ref = "opentest4j" }
 openTestReporting-events = { module = "org.opentest4j.reporting:open-test-reporting-events", version.ref = "openTestReporting" }

gradle/libs.versions.toml

@@ -26,6 +26,7 @@
 import org.apiguardian.api.API;
 import org.junit.jupiter.api.extension.ExtensionConfigurationException;
 import org.junit.jupiter.api.extension.ParameterResolutionException;
+import org.junit.jupiter.api.io.TempDirFactory.Standard;
 
 /**
  * {@code @TempDir} can be used to annotate a field in a test class or a
@@ -96,9 +97,22 @@
 @API(status = STABLE, since = "5.10")
 public @interface TempDir {
 
+	/**
+	 * Factory for the temporary directory.
+	 *
+	 * <p>If {@value #SCOPE_PROPERTY_NAME} is set to {@code per_context}, no
+	 * custom factory is allowed.
+	 *
+	 * @return the class instance of the factory
+	 *
+	 * @since 5.10
+	 */
+	@API(status = EXPERIMENTAL, since = "5.10")
+	Class<? extends TempDirFactory> factory() default Standard.class;
+
 	/**
 	 * Property name used to set the scope of temporary directories created via
-	 * {@link org.junit.jupiter.api.io.TempDir @TempDir} annotation: {@value}
+	 * {@link TempDir @TempDir} annotation: {@value}
 	 *
 	 * <h4>Supported Values</h4>
 	 * <ul>

junit-jupiter-api/src/main/java/org/junit/jupiter/api/io/TempDir.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2015-2023 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.jupiter.api.io;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import java.io.Closeable;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.attribute.FileAttribute;
+
+import org.apiguardian.api.API;
+import org.junit.jupiter.api.extension.ExtensionContext;
+
+/**
+ * {@code TempDirFactory} defines the SPI for creating temporary directories
+ * programmatically.
+ *
+ * <p>A temporary directory factory is typically used to gain more control on
+ * the temporary directory creation, like defining the parent directory or even
+ * the file system that should be used.
+ *
+ * <p>Concrete implementations must have a <em>default constructor</em>.
+ *
+ * <p>A {@link TempDirFactory} can be configured <em>locally</em>
+ * for a test class field or method parameter via the {@link TempDir @TempDir}
+ * annotation.
+ *
+ * @since 5.10
+ * @see TempDir @TempDir
+ */
+@FunctionalInterface
+@API(status = EXPERIMENTAL, since = "5.10")
+public interface TempDirFactory extends Closeable {
+
+	/**
+	 * Create a new temporary directory, using the given prefix to generate its name.
+	 * Depending on the implementation, the resulting {@code Path} may or may not be
+	 * associated with the default {@code FileSystem}.
+	 *
+	 * @param context the current extension context; never {@code null}
+	 * @return the path to the newly created directory that did not exist before this method was invoked; never {@code null}
+	 * @throws Exception in case of failures
+	 */
+	Path createTempDirectory(ExtensionContext context) throws Exception;
+
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	default void close() throws IOException {
+	}
+
+	/**
+	 * Standard temporary directory factory that delegates to
+	 * {@link Files#createTempDirectory}.
+	 *
+	 * @see Files#createTempDirectory(String, FileAttribute[])
+	 */
+	class Standard implements TempDirFactory {
+
+		public static final TempDirFactory INSTANCE = new Standard();
+
+		private static final String TEMP_DIR_PREFIX = "junit";
+
+		public Standard() {
+		}
+
+		@Override
+		public Path createTempDirectory(ExtensionContext context) throws IOException {
+			return Files.createTempDirectory(TEMP_DIR_PREFIX);
+		}
+
+	}
+
+}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/io/TempDirFactory.java

@@ -21,9 +21,11 @@ dependencies {
 	testImplementation(projects.junitPlatformTestkit)
 	testImplementation(testFixtures(projects.junitPlatformCommons))
 	testImplementation(kotlin("stdlib"))
+	testImplementation(libs.jimfs)
 	testImplementation(libs.junit4)
 	testImplementation(libs.kotlinx.coroutines)
 	testImplementation(libs.groovy4)
+	testImplementation(libs.memoryfilesystem)
 	testImplementation(testFixtures(projects.junitJupiterApi))
 
 	osgiVerification(projects.junitPlatformLauncher)