Course – LS – All

Get started with Spring and Spring Boot, through the Learn Spring course:


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 {

Now the assertTimeout method in JUnit 5:

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:

void shouldFailBecauseTheNumbersAreNotEqual_lazyEvaluation() {
      2 == 3, 
      () -> "Numbers " + 2 + " and " + 3 + " are not equal!");

Furthermore, we can group assertions in JUnit 5:

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:

void whenEnvironmentIsWeb_thenUrlsShouldStartWithHttp() {
      () -> 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:

class AnnotationTestExampleUnitTest {

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


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:

  {"/app-config.xml", "/test-data-access-config.xml"})
public class SpringExtensionTest {

In JUnit 5, it’s a simple extension:

  { "/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 {
    public Statement apply(Statement base, Description description) {
        return new Statement() {
            public void evaluate() throws Throwable {
                // Before and after an evaluation tracing here 

And we implement it in a test suite:

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 {

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

    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:

class RuleExampleUnitTest {
    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:


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.

The full implementation of this article can be found on GitHub.

Course – LS – All

Get started with Spring and Spring Boot, through the Learn Spring course:

res – REST with Spring (eBook) (everywhere)
Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.