@TempDir
can be used to annotate a field in a test class or a parameter
in a test class constructor, lifecycle method, or test method of type
Path
or File
that should be resolved into a temporary directory.
Creation
The temporary directory is only created if a field in a test class or a
parameter in a test class constructor, lifecycle method, or test method is
annotated with @TempDir
. An ExtensionConfigurationException
or
a ParameterResolutionException
will be thrown in one of the following
cases:
- If the field type or parameter type is neither
Path
norFile
. - If a field is declared as
final
. - If the temporary directory cannot be created.
- If the field type or parameter type is
File
and a customfactory
is used, which creates a temporary directory that does not belong to the default file system.
Scope
By default, a separate temporary directory is created for every declaration
of the @TempDir
annotation. For better isolation when using
@TestInstance(Lifecycle.PER_METHOD)
semantics, you can annotate an instance field or a parameter in the test class
constructor with @TempDir
so that each test method uses a separate
temporary directory. Alternatively, 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. Symbolic and other types of links, such as junctions on Windows, are
not followed. A warning is logged when deleting a link that targets a
location outside the temporary directory. 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
-
Optional Element Summary
Optional ElementsModifier and TypeOptional ElementDescriptionHow the temporary directory gets cleaned up after the test completes.Class
<? extends TempDirFactory> Factory for the temporary directory. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
The name of the configuration parameter that is used to configure the defaultCleanupMode
.static final String
Property name used to set the default temporary directory factory class name: "junit.jupiter.tempdir.factory.default"static final String
Deprecated.
-
Field Details
-
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
- See Also:
-
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@TempDir
is first declaredper_declaration
: creates separate temporary directories for each declaration site of the@TempDir
annotation
If not specified, the default is
per_declaration
.- Since:
- 5.8
- See Also:
-
DEFAULT_CLEANUP_MODE_PROPERTY_NAME
The name of the configuration parameter that is used to configure the defaultCleanupMode
.If this configuration parameter is not set,
CleanupMode.ALWAYS
will be used as the default.- Since:
- 5.9
- See Also:
-
-
Element Details
-
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 customfactory
always overrides a globalTempDirFactory
.- Returns:
- the type of
TempDirFactory
to use - Since:
- 5.10
- See Also:
- Default:
org.junit.jupiter.api.io.TempDirFactory.class
-
cleanup
How the temporary directory gets cleaned up after the test completes.- Since:
- 5.9
- Default:
DEFAULT
-