Migrating from JUnit 4 to JUnit 5

1. Overview

In this tutorial, we’ll learn how to migrate from JUnit 4 to the latest JUnit 5 release, with an overview of the differences between the two versions of the library.

For the general guidelines on using JUnit 5, see our article here.

2. JUnit 5 Advantages

Let’s start with the previous version, JUnit 4 , which has some clear limitations:

• A single jar library contains the entire framework. We need to import the whole library, even when we only require a particular feature. In JUnit 5, we get more granularity and can import only what’s necessary.
• Only one test runner can execute tests at a time in JUnit 4 (e.g. SpringJUnit4ClassRunner or Parameterized ). JUnit 5 allows multiple runners to work simultaneously.
• JUnit 4 never advanced beyond Java 7, missing out on a lot of features from Java 8. JUnit 5 makes good use of the Java 8 features.

The idea behind JUnit 5 was to completely rewrite JUnit 4 in order to negate most of these drawbacks.

3. Differences

JUnit 4 was divided into the modules that comprise JUnit 5:

• JUnit Platform – this module scopes all the extension frameworks we might have an interest in: test execution, discovery, and reporting.
• JUnit Vintage – this module allows backward compatibility with JUnit 4 or even JUnit 3.

3.1. Annotations

JUnit 5 comes with important changes to its annotations. Instead of @org.junit.Test we now need to use @org.junit.jupiter.api.Test.

The most important one is that we can no longer use the @Test annotation for specifying expectations.

The expected parameter in JUnit 4:

@Test(expected = Exception.class)
public void shouldRaiseAnException() throws Exception {
    // ...
}

Now we can use the method assertThrows:

void shouldRaiseAnException() throws Exception {
    Assertions.assertThrows(Exception.class, () -> {
        //...
    });
}

The timeout attribute in JUnit 4:

@Test(timeout = 1)
public void shouldFailBecauseTimeout() throws InterruptedException {
    Thread.sleep(10);
}

Now the assertTimeout method in JUnit 5:

@Test
void shouldFailBecauseTimeout() throws InterruptedException {
    Assertions.assertTimeout(Duration.ofMillis(1), () -> Thread.sleep(10));
}

Here are some other annotations that were changed within JUnit 5:

• @Before annotation is now @BeforeEach
• @After annotation is now @AfterEach
• @BeforeClass annotation is now @BeforeAll
• @AfterClass annotation is now @AfterAll
• @Ignore annotation is now @Disabled

3.2. Assertions

We can also write assertion messages in a lambda in JUnit 5, allowing the lazy evaluation to skip complex message construction until needed:

@Test
void shouldFailBecauseTheNumbersAreNotEqual_lazyEvaluation() {
    Assertions.assertTrue(
      2 == 3, 
      () -> "Numbers " + 2 + " and " + 3 + " are not equal!");
}

Furthermore, we can group assertions in JUnit 5:

@Test
void shouldAssertAllTheGroup() {
    List<Integer> list = Arrays.asList(1, 2, 4);
    Assertions.assertAll("List is not incremental",
        () -> Assertions.assertEquals(list.get(0).intValue(), 1),
        () -> Assertions.assertEquals(list.get(1).intValue(), 2),
        () -> Assertions.assertEquals(list.get(2).intValue(), 3));
}

3.3. Assumptions

The new Assumptions class is now in org.junit.jupiter.api.Assumptions. JUnit 5 fully supports the existing assumptions methods in JUnit 4, and also adds a new set of methods allowing us to run some assertions under specific scenarios only:

@Test
void whenEnvironmentIsWeb_thenUrlsShouldStartWithHttp() {
    assumingThat("WEB".equals(System.getenv("ENV")),
      () -> assertTrue("http".startsWith(address)));
}

3.4. Tagging and Filtering

In JUnit 4, we could group tests by using the @Category annotation. In JUnit 5, the @Category annotation is replaced by the @Tag annotation:

@Tag("annotations")
@Tag("junit5")
class AnnotationTestExampleUnitTest {
    /*...*/
}

We can include/exclude particular tags using the maven-surefire-plugin:

<build>
    <plugins>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <properties>
                    <includeTags>junit5</includeTags>
                </properties>
            </configuration>
        </plugin>
    </plugins>
</build>

3.5. New Annotations for Running Tests

In JUnit 4, we used the @RunWith annotation to integrate the test context with other frameworks or to change the overall execution flow in the test cases.

With JUnit 5, we can now use the @ExtendWith annotation to provide similar functionality.

As an example, to use the Spring features in JUnit 4:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(
  {"/app-config.xml", "/test-data-access-config.xml"})
public class SpringExtensionTest {
    /*...*/
}

In JUnit 5, it’s a simple extension:

@ExtendWith(SpringExtension.class)
@ContextConfiguration(
  { "/app-config.xml", "/test-data-access-config.xml" })
class SpringExtensionTest {
    /*...*/
}

3.6. New Test Rules Annotations

In JUnit 4, we used the @Rule and @ClassRule annotations to add special functionality to tests.

In JUnit 5. we can reproduce the same logic using the @ExtendWith annotation.

For example, say we have a custom rule in JUnit 4 to write log traces before and after a test:

public class TraceUnitTestRule implements TestRule {
 
    @Override
    public Statement apply(Statement base, Description description) {
        return new Statement() {
            @Override
            public void evaluate() throws Throwable {
                // Before and after an evaluation tracing here 
                ...
            }
        };
    }
}

And we implement it in a test suite:

@Rule
public TraceUnitTestRule traceRuleTests = new TraceUnitTestRule();

In JUnit 5, we can write the same in a much more intuitive manner:

public class TraceUnitExtension implements AfterEachCallback, BeforeEachCallback {

    @Override
    public void beforeEach(TestExtensionContext context) throws Exception {
        // ...
    }

    @Override
    public void afterEach(TestExtensionContext context) throws Exception {
        // ...
    }
}

Using JUnit 5’s AfterEachCallback and BeforeEachCallback interfaces, available in the org.junit.jupiter.api.extension package, we can easily implement this rule in the test suite:

@ExtendWith(TraceUnitExtension.class)
class RuleExampleUnitTest {
 
    @Test
    void whenTracingTests() {
        /*...*/
    }
}

3.7. JUnit 5 Vintage

JUnit Vintage aids in the migration of JUnit tests by running JUnit 3 or JUnit 4 tests within the JUnit 5 context.

We can use it by importing the JUnit Vintage Engine:

<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <version>${junit5.vintage.version}</version>
    <scope>test</scope>
</dependency>

4. Conclusion

JUnit 5 is a modular and modern take on the JUnit 4 framework. In this article, we introduced the major differences between these two versions and hinted at how to migrate from one to another.