A temporary directory is a directory on the machine’s on-disk filesystem that is created for one or more tests and deleted when it is no longer needed. Temporary directories are created via annotations on parameters and configure whether a directory is created anew for a test or shared with others. Either way, they’re deleted once they’re no longer needed. You can also configure the prefix of a temporary directory’s name, which might be useful for test reporting or debugging reasons.

Note

This article describes the specifics of how to inject temporary directories into your tests. Most of the extension’s features are shared with other resources, though, and are described in the article covering resources in general. This includes important aspects like thread-safety, sharing resources, and cleaning up behind them (in this case, deleting the temporary directory), so make sure to read that one as well.

This temporary directory extension was introduced in JUnit Pioneer 1.9.0. JUnit Pioneer versions before 1.0 contain a then-removed temp dir extension, which was superseded by the very similar but more powerful official @TempDir extension shipped with JUnit Jupiter 5.4.

Creating a New Temporary Directory

To create a new temporary directory for a given test:

@Test
void dirTest1(@Dir Path tempDir) {
    // Test code goes here, e.g.,
    assertThat(tempDir).exists();
}

@Test
void dirTest2(@Dir Path tempDir) {
    // This temporary directory is different to the first one.
}

@Dir is the shorthand annotation for @New, meaning it achieves the same result more succinctly than the long form:

@Test
void test1(@New(TemporaryDirectory.class) Path tempDir) {
    // Test code goes here, e.g.,
    assertThat(tempDir).exists();
}

@Test
void test2(@New(TemporaryDirectory.class) Path tempDir) {
    // This temporary directory is different to the first one.
}

Creating with Arguments

To specify the prefix of a new temporary directory’s name, pass the prefix as an argument to the @New annotation:

@Test
void testWithArg(
        @New(value = TemporaryDirectory.class, arguments = "customPrefix")
        Path tempDir) {
    // Test code goes here, e.g.,
    Path rootTempDir = Paths.get(System.getProperty("java.io.tmpdir"));
    assertThat(rootTempDir.relativize(tempDir)).asString().startsWith("customPrefix");
}
Note

The @Dir annotation does not yet support arguments. Follow this issue for updates on this feature.

Sharing a Temporary Directory

To create a temporary directory that is shared by multiple tests:

@Test
void sharedResourceTest1(
        @Shared(factory = TemporaryDirectory.class, name = "sharedTempDir")
        Path sharedTempDir) {
    // Test code goes here, e.g.,
    assertThat(sharedTempDir).exists();
}

@Test
void sharedResourceTest2(
        @Shared(factory = TemporaryDirectory.class, name = "sharedTempDir")
        Path sharedTempDir) {
    // "sharedTempDir" is shared with the temporary directory of
    // the same name in test "sharedResourceTest1", so any created
    // subdirectories and files will be shared.
}

See the Resources documentation for more information.

Note

There’s no shorthand form of @Shared. Follow this issue for updates on this feature.

Thread-Safety

This extension is safe to use during parallel test execution.

Tests with @New temporary directories will continue to run in parallel. Tests with @Shared temporary directories will be forced to run sequentially, even if parallel execution has been enabled.