Annotation Interface TempDir

@Target({ANNOTATION_TYPE,FIELD,PARAMETER}) @Retention(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 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 nor File.
  • 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 custom factory 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.

Cleanup/Deletion

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.

Two attributes allow customizing when (see cleanup()) and how (see deletionStrategy()) to clean up.

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.

The deletionStrategy() attribute defines the strategy for performing the cleanup and dealing with errors such as undeletable files. By default, the Standard strategy is used which will cause a test or test class to fail in case deletion of a file or directory fails. This can be configured globally by setting the "junit.jupiter.tempdir.deletion.strategy.default" configuration parameter.

Since:
5.4

  • Field Details

    • DEFAULT_FACTORY_PROPERTY_NAME

      @API(status=MAINTAINED, since="5.13.3") static final 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
      See Also:

    • DEFAULT_CLEANUP_MODE_PROPERTY_NAME

      @API(status=MAINTAINED, since="5.13.3") static final String DEFAULT_CLEANUP_MODE_PROPERTY_NAME
      Property name used to configure the default CleanupMode: "junit.jupiter.tempdir.cleanup.mode.default"

      Supported values include names of enum constants defined in CleanupMode, ignoring case.

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

      Since:
      5.9
      See Also:

    • DEFAULT_DELETION_STRATEGY_PROPERTY_NAME

      @API(status=EXPERIMENTAL, since="6.1") static final String DEFAULT_DELETION_STRATEGY_PROPERTY_NAME
      Property name used to set the default deletion strategy class name: "junit.jupiter.tempdir.deletion.strategy.default"

      Supported Values

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

      If not specified, the default is TempDirDeletionStrategy.Standard.

      Since:
      6.1
      See Also:

  • Element Details

    • factory

      @API(status=MAINTAINED, since="5.13.3") Class<? extends TempDirFactory> factory
      Factory for the temporary directory.

      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:
      Default:
      org.junit.jupiter.api.io.TempDirFactory.class

    • cleanup

      @API(status=STABLE, since="5.11") CleanupMode cleanup
      In which cases the temporary directory gets cleaned up after the test completes.
      Since:
      5.9
      Default:
      DEFAULT

    • deletionStrategy

      @API(status=EXPERIMENTAL, since="6.1") Class<? extends TempDirDeletionStrategy> deletionStrategy
      Deletion strategy for the temporary directory.

      Defaults to TempDirDeletionStrategy.Standard.

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

      Returns:
      the type of TempDirDeletionStrategy to use
      Since:
      6.1
      See Also:
      Default:
      org.junit.jupiter.api.io.TempDirDeletionStrategy.class