The @ClearEnvironmentVariable and @SetEnvironmentVariable annotations can be used to clear, respectively, set the values of environment variables for a test execution. Both annotations work on the test method and class level, are repeatable as well as combinable. After the annotated method has been executed, the variables mentioned in the annotation will be restored to their original value or will be cleared if they didn’t have one before. Other environment variables that are changed during the test, are not restored.

Warning
Java considers environment variables to be immutable, so this extension uses reflection to change them. This requires that the SecurityManager allows modifications and can potentially break on different operating systems and Java versions. Be aware that this is a fragile solution and consider finding a better one for your specific situation. For more details, see Warnings for Reflective Access.

For example, clearing a environment variable for a test execution can be done as follows:

@Test
@ClearEnvironmentVariable(key = "some variable")
void test() {
    assertThat(System.getenv("some variable")).isNull();
}

And setting a environment variable for a test execution:

@Test
@SetEnvironmentVariable(
    key = "some variable",
    value = "new value")
void test() {
    assertThat(System.getenv("some variable")).
        isEqualTo("new value");
}

As mentioned before, both annotations are repeatable and they can also be combined:

@Test
@ClearEnvironmentVariable(key = "1st variable")
@ClearEnvironmentVariable(key = "2nd variable")
@SetEnvironmentVariable(
    key = "3rd variable",
    value = "new value")
void test() {
    assertThat(System.getenv("1st variable")).isNull();
    assertThat(System.getenv("2nd variable")).isNull();
    assertThat(System.getenv("3rd variable"))
        .isEqualTo("new value");
}

Note that class level configurations are overwritten by method level configurations:

@ClearEnvironmentVariable(key = "some variable")
class MyEnvironmentVariableTest {

    @Test
    @SetEnvironmentVariable(key = "some variable",
            value = "new value")
    void test() {
        assertThat(System.getenv("some variable"))
            .isEqualTo("new value");
    }

}

Warnings for Reflective Access

As explained above, this extension uses reflective access to change the otherwise immutable environment variables. On Java 9 to 16, this leads to a warning like the following:

[ERROR] WARNING: An illegal reflective access operation has occurred
[ERROR] WARNING: Illegal reflective access by org.junitpioneer.jupiter.EnvironmentVariableUtils [...] to field [...]
[ERROR] WARNING: Please consider reporting this to the maintainers of org.junitpioneer.jupiter.EnvironmentVariableUtils
[ERROR] WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
[ERROR] WARNING: All illegal access operations will be denied in a future release

On Java 17 and later, you get this error instead:

java.lang.reflect.InaccessibleObjectException: Unable to make field [...] accessible:
module java.base does not "opens java.lang" to unnamed module [...]

The best way to prevent these warnings/errors, is to change the code under test, so this extension is no longer needed. The next best thing is to allow access to that specific package with --add-opens=java.base/java.util=ALL-UNNAMED (if you place JUnit Pioneer on the class path) or --add-opens=java.base/java.util=org.junitpioneer (if you place it on the module path).

These command line options need to be added to the JVM that executes the tests:

Thread-Safety

Since environment variables are global state, reading and writing them during parallel test execution can lead to unpredictable results and flaky tests. The environment variable extension is prepared for that and tests annotated with @ClearEnvironmentVariable or @SetEnvironmentVariable will never execute in parallel (thanks to resource locks) to guarantee correct test results.

However, this does not cover all possible cases. Tested code that reads or writes environment variables independently of the extension can still run in parallel to it and may thus behave erratically when, for example, it unexpectedly reads a variable set by the extension in another thread. Tests that cover code that reads or writes environment variables need to be annotated with the respective annotation:

  • @ReadsEnvironmentVariable

  • @WritesEnvironmentVariable

Tests annotated in this way will never execute in parallel with tests annotated with @ClearEnvironmentVariable or @SetEnvironmentVariable.