JUnit 5 Temporary Directory Support

1. Overview

When testing, we often need access to a temporary file. However, managing, creating and deleting these files ourselves can be cumbersome.

In this quick tutorial, we’ll look at how JUnit 5 alleviates this by providing the TempDirectory extension.

For an in-depth guide to testing with JUnit, check out our excellent Guide to JUnit 5.

2. The TempDirectory Extension

Starting with version 5.4.2, JUnit 5 provides the TempDirectory Extension. However, it’s important to note that this is still an experimental feature and that we’re encouraged to give feedback to the JUnit team.

As we’ll see later, this extension can create and clean up a temporary directory for an individual test or all tests in a test class.

Usually, when using an extension, we need to register it from within a JUnit 5 test using the @ExtendWith annotation. But this is unnecessary with the TempDirectory extension, which is built-in and registered by default.

3. Maven Dependencies

First, let’s add the project dependencies we will need for our examples.

Apart from the main JUnit 5 library junit-jupiter-engine, we’ll also need the junit-jupiter-api library:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>5.11.0-M2</version>
    <scope>test</scope>
</dependency>

As always, we can get the latest version from Maven Central.

In addition to this, we’ll also need to add the junit-jupiter-params dependency:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-params</artifactId>
    <version>5.11.0-M2</version>
    <scope>test</scope>
</dependency>

Again, we can find the latest version in Maven Central.

4. Using the @TempDir Annotation

To use the TempDirectory extension, we need to use the @TempDir annotation. We can only use this annotation with the following two types:

• java.nio.file.Path
• java.io.File

If we try to use it with a different type, then an org.junit.jupiter.api.extension.ParameterResolutionException will be thrown.

Next, let’s explore several different ways of using this annotation.

4.1. @TempDir as a Method Parameter

Let’s begin by seeing how to inject a parameter annotated with @TempDir into a single test method:

@Test
void givenTestMethodWithTempDirectory_whenWriteToFile_thenContentIsCorrect(@TempDir Path tempDir) 
  throws IOException {
    Path numbers = tempDir.resolve("numbers.txt");

    List<String> lines = Arrays.asList("1", "2", "3");
    Files.write(numbers, lines);

    assertAll(
      () -> assertTrue("File should exist", Files.exists(numbers)),
      () -> assertLinesMatch(lines, Files.readAllLines(numbers)));
}

As we can see, our test method creates and writes a file called numbers.txt in the temporary directory tempDir.

We then check that the file exists and the content matches what was originally written. Nice and simple!

4.2. @TempDir on an Instance Field

In the following example, we’ll annotate a field in our test class using the @TempDir annotation:

@TempDir
File anotherTempDir;

@Test
void givenFieldWithTempDirectoryFile_whenWriteToFile_thenContentIsCorrect() throws IOException {
    assertTrue("Should be a directory ", this.anotherTempDir.isDirectory());

    File letters = new File(anotherTempDir, "letters.txt");
    List<String> lines = Arrays.asList("x", "y", "z");

    Files.write(letters.toPath(), lines);

    assertAll(
      () -> assertTrue("File should exist", Files.exists(letters.toPath())),
      () -> assertLinesMatch(lines, Files.readAllLines(letters.toPath())));
}

This time, we use a java.io.File for our temporary directory. Again, we write some lines and check they were written successfully.

If we were to use this single reference again in other test methods, each test would use its temporary directory.

4.3. A Shared Temporary Directory

Sometimes, we might want to share a temporary directory between test methods.

We can do this by declaring our field static:

@TempDir
static Path sharedTempDir;

@Test
@Order(1)
void givenFieldWithSharedTempDirectoryPath_whenWriteToFile_thenContentIsCorrect() throws IOException {
    Path numbers = sharedTempDir.resolve("numbers.txt");

    List<String> lines = Arrays.asList("1", "2", "3");
    Files.write(numbers, lines);

    assertAll(
        () -> assertTrue("File should exist", Files.exists(numbers)),
        () -> assertLinesMatch(lines, Files.readAllLines(numbers)));
}

@Test
@Order(2)
void givenAlreadyWrittenToSharedFile_whenCheckContents_thenContentIsCorrect() throws IOException {
    Path numbers = sharedTempDir.resolve("numbers.txt");

    assertLinesMatch(Arrays.asList("1", "2", "3"), Files.readAllLines(numbers));
  }

The key point is that we use a static field, sharedTempDir, which we share between the two test methods.

In the first test, we again wrote some lines to a file called numbers.txt. Then, in the next test, we checked that the file and its content exist.

We also enforce the order of the tests via the @Order annotation to ensure the behavior is always consistent.

4.4. The cleanup Option

Usually, the temporary directory created by @TempDir will be automatically deleted after the test execution. However, in some cases, we may want to preserve the temporary directory for debugging purposes.

For example, if a test fails, we may want to examine the contents of the temporary directory to see if there are any clues about the cause of the failure. In such cases, Junit5’s automatic deletion of the temporary directory may not be desirable.

To address this issue, Junit5 provides a cleanup option for the @TempDir annotation. The cleanup option can specify whether the temporary directory should be deleted automatically at the end of the test method.

The cleanup option can be set to one of the following CleanupMode values:

• ALWAYS – This option specifies that the temporary directory should always be deleted automatically at the end of the test method, regardless of whether the test succeeds or fails. This is the default mode.
• ON_SUCCESS – The temporary directory will be deleted after the test method execution only if the test succeeds.
• NEVER – The temporary directory won’t be deleted automatically after executing the test method.

Next, let’s create a test class to verify if we set NEVER as the cleanup option’s value, the temporary directory won’t be removed after the test execution:

@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class TemporaryDirectoryWithCleanupUnitTest {

    private Path theTempDirToBeChecked = null;

    @Test
    @Order(1)
    void whenTestMethodWithTempDirNeverCleanup_thenSetInstanceVariable(@TempDir(cleanup = NEVER) Path tempDir) {
        theTempDirToBeChecked = tempDir;
        System.out.println(tempDir.toFile().getAbsolutePath());
    }

    @Test
    @Order(2)
    void whenTestMethodWithTempDirNeverCleanup_thenTempDirShouldNotBeRemoved() {
        assertNotNull(theTempDirToBeChecked);
        assertTrue(theTempDirToBeChecked.toFile().isDirectory());
    }

}

As the class above shows, we added the @TestInstance(TestInstance.Lifecycle.PER_CLASS) annotation to the test class so that JUnit creates only one instance of the test class and uses it for all tests. This is because we’ll set the theTempDirToBeChecked instance variable in the first test and verify if the temporary directory is still there in the second test.

If we run the test, it passes. So, it indicates during the second test’s run, the temporary directory created in the first test isn’t removed.

Further, we can see the output from the first test:

/tmp/junit16624071649911791120

The INFO log from Junit5 reminds us that the temporary directory won’t be removed after the first test:

INFO: Skipping cleanup of temp dir /tmp/junit16624071649911791120 due to cleanup mode configuration.

After all test executions, if we check the temporary directory on the filesystem, the directory still exists:

$ ls -ld /tmp/junit16624071649911791120
drwx------ 2 kent kent 40 Apr  1 18:23 /tmp/junit16624071649911791120/

5. Gotchas

Let’s review some subtleties we should know when working with the TempDirectory extension.

5.1. Creation

The curious reader will probably wonder where these temporary files are created?

Well, internally, the JUnit TemporaryDirectory class makes use of the Files.createTempDirectory(String prefix) method. Likewise, this method then uses the default system temporary file directory.

This is usually specified in the environment variable TMPDIR:

TMPDIR=/var/folders/3b/rp7016xn6fz9g0yf5_nj71m00000gn/T/

For instance, resulting in a temporary file location:

/var/folders/3b/rp7016xn6fz9g0yf5_nj71m00000gn/T/junit5416670701666180307/numbers.txt

Meanwhile, if the temporary directory cannot be created, an ExtensionConfigurationException will be thrown as appropriate. Or, as previously mentioned, a ParameterResolutionException.

5.2. Deletion

The cleanup attribute’s default value is ALWAYS. That is to say, when the test method or class has finished execution and the temporary directory goes out of scope, the JUnit framework will attempt to delete all files and directories in that directory recursively and, finally, the temporary directory itself.

If there’s a problem during this deletion phase, an IOException will be thrown, and the test or test class will fail.

6. Customizing Temporary Directories Creation Using TempDirFactory

To customize the creation of temporary directories, we need to implement the TempDirFactory interface. This interface is in the org.junit.jupiter.api.io package and is part of the JUnit Jupiter API module. It’s also used with the @TempDir annotation to specify a temporary directory for a test method or class.

Also, the TempDirFactory interface has a single method called createTempDir(), which creates the temporary directory. We must implement this method with your logic when creating the temporary directory. Here’s an example implementation of the TempDirFactory interface:

class TempDirFactoryUnitTest {

    @Test
    void factoryTest(@TempDir(factory = Factory.class) Path tempDir) {
        assertTrue(tempDir.getFileName().toString().startsWith("factoryTest"));
    }

    static class Factory implements TempDirFactory {

        @Override
        public Path createTempDirectory(AnnotatedElementContext elementContext, ExtensionContext extensionContext)
                throws IOException {
            return Files.createTempDirectory(extensionContext.getRequiredTestMethod().getName());
        }

    }
}

In this example, the createTempDir() method creates a temporary directory using the Files.createTempDirectory() method from the Java NIO package. We can customize this method according to our requirements.

7. Conclusion

In this article, we’ve explored the TempDirectory Extension provided by JUnit 5.

First, we introduced the extension and learned what Maven dependencies we need to use it. Next, we looked at several examples of how to use the extension from within our unit tests.

Finally, we looked at several gotchas, including where the temporary files are created and what happens during deletion.