org.junit.jupiter.api.io

Annotation Type TempDir

@Target(value={ANNOTATION_TYPE,FIELD,PARAMETER})
 @Retention(value=RUNTIME)
 @Documented
 @API(status=STABLE,
     since="5.10")
public @interface TempDir

@TempDir can be used to annotate a field in a test class or a parameter in a lifecycle method or test method of type Path or File that should be resolved into a temporary directory.

Please note that @TempDir is not supported on constructor parameters. Please use field injection instead by annotating an instance field with @TempDir.

Creation

The temporary directory is only created if a field in a test class or a parameter in a lifecycle method or test method is annotated with @TempDir. If the field type or parameter type is neither Path nor File, if a field is declared as final, or if the temporary directory cannot be created, an ExtensionConfigurationException or a ParameterResolutionException will be thrown as appropriate. In addition, a ParameterResolutionException will be thrown for a constructor parameter annotated with @TempDir.

Scope

By default, a separate temporary directory is created for every declaration of the @TempDir annotation. If you want to share a temporary directory across all tests in a test class, you should declare the annotation on a static field or on a parameter of a @BeforeAll method.

Old behavior

You can revert to the old behavior of using a single temporary directory by setting the "junit.jupiter.tempdir.scope" configuration parameter to per_context. In that case, the scope of the temporary directory depends on where the first @TempDir annotation is encountered when executing a test class. The temporary directory will be shared by all tests in a class when the annotation is present on a static field or on a parameter of a @BeforeAll method. Otherwise — for example, when @TempDir is only used on instance fields or on parameters in test, @BeforeEach, or @AfterEach methods — each test will use its own temporary directory.

Clean Up

By default, when the end of the scope of a temporary directory is reached, — when the test method or class has finished execution — JUnit will attempt to clean up the temporary directory by recursively deleting all files and directories in the temporary directory and, finally, the temporary directory itself. In case deletion of a file or directory fails, an IOException will be thrown that will cause the test or test class to fail.

The cleanup() attribute allows you to configure the CleanupMode. If the cleanup mode is set to NEVER, the temporary directory will not be cleaned up after the test completes. If the cleanup mode is set to ON_SUCCESS, the temporary directory will only be cleaned up if the test completes successfully. By default, the ALWAYS clean up mode will be used, but this can be configured globally by setting the "junit.jupiter.tempdir.cleanup.mode.default" configuration parameter.

Since:

5.4

Field Summary

Fields

Modifier and Type	Fields and Description
static java.lang.String	DEFAULT_CLEANUP_MODE_PROPERTY_NAME The name of the configuration parameter that is used to configure the default CleanupMode.
static java.lang.String	DEFAULT_FACTORY_PROPERTY_NAME Property name used to set the default temporary directory factory class name: "junit.jupiter.tempdir.factory.default"
static java.lang.String	SCOPE_PROPERTY_NAME Deprecated.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
CleanupMode	cleanup How the temporary directory gets cleaned up after the test completes.
java.lang.Class<? extends TempDirFactory>	factory Factory for the temporary directory.

Field Detail

DEFAULT_FACTORY_PROPERTY_NAME

@API(status=EXPERIMENTAL,
     since="5.10")
public static final java.lang.String DEFAULT_FACTORY_PROPERTY_NAME

Property name used to set the default temporary directory factory class name: "junit.jupiter.tempdir.factory.default"

Supported Values

Supported values include fully qualified class names for types that implement TempDirFactory.

If not specified, the default is TempDirFactory.Standard.

Since:

5.10

SCOPE_PROPERTY_NAME

@Deprecated
 @API(status=DEPRECATED,
     since="5.9")
public static final java.lang.String SCOPE_PROPERTY_NAME

Deprecated.

Property name used to set the scope of temporary directories created via the @TempDir annotation: "junit.jupiter.tempdir.scope"

Supported Values

• per_context: creates a single temporary directory for the entire test class or method, depending on where it's first declared
• per_declaration: creates separate temporary directories for each declaration site of the @TempDir annotation.

If not specified, the default is per_declaration.

Since:

5.8

DEFAULT_CLEANUP_MODE_PROPERTY_NAME

@API(status=EXPERIMENTAL,
     since="5.9")
public static final java.lang.String DEFAULT_CLEANUP_MODE_PROPERTY_NAME

The name of the configuration parameter that is used to configure the default CleanupMode.

If this configuration parameter is not set, CleanupMode.ALWAYS will be used as the default.

Since:

5.9

Element Detail

factory

@API(status=EXPERIMENTAL,
     since="5.10")
public abstract java.lang.Class<? extends TempDirFactory> factory

Factory for the temporary directory.

If the "junit.jupiter.tempdir.scope" configuration parameter is set to per_context, no custom factory is allowed.

Defaults to TempDirFactory.Standard.

As an alternative to setting this attribute, a global TempDirFactory can be configured for the entire test suite via the "junit.jupiter.tempdir.factory.default" configuration parameter. See the User Guide for details. Note, however, that a @TempDir declaration with a custom factory always overrides a global TempDirFactory.

Returns:

the type of TempDirFactory to use

Since:

5.10

See Also:

TempDirFactory

Default:

org.junit.jupiter.api.io.TempDirFactory.class

cleanup

@API(status=EXPERIMENTAL,
     since="5.9")
public abstract CleanupMode cleanup

How the temporary directory gets cleaned up after the test completes.

Since:

5.9

Default:

org.junit.jupiter.api.io.CleanupMode.DEFAULT