Take Unit Testing to the Next Level With JUnit 5

JUnit is the most popular testing framework in Java, and with JUnit 5 testing in Java 8 and beyond, it takes another step forward. This version was released in September 2017 and has been actively updated to fix bugs and add new features. Moreover, JUnit 5 is also compatible with version 3 and 4 by adding junit-vintage-engine to your classpath path.

Migrating From JUnit 4

When migrating from JUnit 4, there are a few considerations to bear in mind:

• To have JUnit 5 annotations, you need to add the junit-jupiter-api to your classpath.
• Replace  @BeforeClass, @Before , @AfterClass, and @After annotations with  @BeforeAll, @BeforeEach, @AfterAll, and @AfterEach alternatively.

@BeforeAll
static void initAll(){
    LOGGER.info("@BeforeAll runs once before all tests");
}

@BeforeEach
void init(){
LOGGER.info("@BeforeEach runs before each test");
}

@AfterAll
static void tearDownAll(){
    LOGGER.info("@AfterAll runs once after all tests");
}

@AfterEach
void tearDown(){
    LOGGER.info("@AfterEach runs after each test");
}

• Replace @Ignore with  @Disabled. JUnit 5 also provides a more powerful filter in order to ignore or disable tests by JavaScript expressions, OS, Java version, or system properties

@Test
@Disabled("Disabled test (it used to be @Ignore in jUnit4)")
void skippedTest(){
// not executed
}

@Test
@EnabledIf(value = "true", reason = "test runs because it is true")
void isExecuted(){
}

@DisabledIf("Math.random() )
@RepeatedTest(10)
void sometimesIsExecuted(){
    System.out.println("Running " + counter++);
}

•  @Category needs to be replaced with  @Tag.

@Tag("myTestSuite")
class TagsTests{

  @Test
  @Tag("myTest")
  void tagExample(){

  }
}

•  @RunWith does not exist anymore, use @ExtendWithinstead.
•  @Rule and @ClassRule were also removed, use @ExtendWithinstead.

New JUnit 5 Features

@DisplayName

 @DisplayName allows you to override a test class or method with a custom message, special characters, or even emojis. 

@DisplayName("Display name test suite")
class DisplayNamesTests{

  @Test
  @DisplayName("My Custom Test Name")
  void displayNameTest(){

  }

  @Test
  @DisplayName("\uD83D\uDE03")// Happy Emoji
  void displayEmojiTest(){

  }
}

Assertions

Assertions include five new improvements:

• Compatibility with a lambda expression.

assertEquals(Stream.of(1,4,5).mapToInt(Integer::intValue).sum(), 10, "Sum should be 10");

• Group assertions
  •  assertAll() 
    

ListString> names = Arrays.asList("Sergio","Juan","Peter");
assertAll("names",
  ()-> assertEquals("Sergio", names.get(0)),
  ()-> assertEquals("Juan", names.get(1)),
  ()-> assertEquals("Adolfo", names.get(2)));

• More control over exceptions — now, you can even inspect the returning exception to verify the message, cause, stacktrace using:
  •  assertThrows() 
    

Throwable runtimeException = assertThrows(RuntimeException.class,()->{
throw newRuntimeException("exception");
});


assertEquals("exception", runtimeException.getMessage());

• Timeout assertions:
  •  assertTimeout()  
    

@Test
void timeoutNotExceeded(){
    assertTimeout(Duration.ofMinutes(2),()-> System.out.println("Hello"));
}

@Test
void timeoutNotExceededWithResult(){
    String result  = assertTimeout(Duration.ofMinutes(2),()->"hello");

    assertEquals("hello", result);
}

@Test
@Disabled("Assertion fails with exceeded timeout of 2ms by 8ms")
void timeoutExceeded(){
    assertTimeout(Duration.ofMillis(2),()->{
        sleep(10);
});
}

Assumptions

•  assumeTrue() 
  
•  assumeFalse() 
  
•  assumingThat() 
  

Assumptions are preconditions that need to be satisfied to run subsequent assertions. If the assumption fails, TestAbortedException is thrown and the complete test is skipped.

@Test
void trueAssumption(){
    assumeTrue(25);
    assertEquals(7,3 + 4);
}

@Test
void falseAssumption(){
    assumeFalse(32);
    assertEquals(7,4 + 3);
}

@Test
void assumptionThat(){
    String word ="word";
    assumingThat("word".equals(word), ()-> assertEquals(3, 2 + 1));
}

@Nested

 @Nested gives you more freedom to create groups of a related test in the same test suite. 

class NestedTests{

  private ListString> strings;

  @Nested
  class listIsInstantiated{

    @BeforeEach
    void init(){
        strings = new ArrayList();
    }

    @Test
    void listIsEmpty(){
        assertTrue(strings.isEmpty());
    }

    @Nested
    class afterAddingString{

      @BeforeEach
      void init(){
           strings.add("hello");
      }

      @Test
      void listIsNotEmpty(){
           assertFalse(strings.isEmpty());
      }
    }
  }
}

 @BeforeAll and  @AfterAll are only allowed if the test class is annotated with  @TestInstance(Lifecycle.PER_CLASS).

Dependency Injection

JUnit 5 allows adding parameters in constructors and test methods. Therefore, now constructors and methods annotated with  @Test,  @TestFactory,  @BeforeEach,  @AfterEach, @BeforeAll, @AfterAll accept parameters. There are three kinds of allowed parameters:

•  TestInfo: allows you to get information related to a test suite or test method, such as display name, tags, test class:

DependencyInjectionTests(TestInfo testInfo){
    assertEquals("Dependency Injection Test Suite", testInfo.getDisplayName());
}

@Nested
class testInfoExamples{
    @BeforeEach
    void init(TestInfo testInfo){
            String displayName = testInfo.getDisplayName();
            assertTrue(displayName.equals("Test Example") || displayName.equals("myTest()"));
    }

    @Test
    @DisplayName("Test Example")
    @Tag("my-tag")
    void test(TestInfo testInfo){
            assertTrue(testInfo.getTags().contains("my-tag"));
    }

    @Test
    void myTest(){

    }
}

•  TestReporter: is used to print test information to stout or stderr.

@Test
void testReporterString(TestReporter testReporter){
// Use test reporter to print information to stout or stderr
    testReporter.publishEntry("my message");
}

@Test
void testReporterKeyValue(TestReporter testReporter){
    testReporter.publishEntry("myKey","myValue");
}

@Test
void testReporterMap(TestReporter testReporter){
    MapString, String> myMap = new HashMap();
    myMap.put("myKey","myValue");
    testReporter.publishEntry(myMap);
}

•  RepetitionInfo: can be used only on tests annotated with @RepeatedTest and provides information regarding the current repetition number or total of repetitions.

private static int repetition = 1;

@RepeatedTest(10)
@DisplayName("repetition")
void repetitionTest(RepetitionInfo repetitionInfo){
    assertEquals(repetition++, repetitionInfo.getCurrentRepetition());
    assertEquals(10, repetitionInfo.getTotalRepetitions());
}

Interfaces and Default Methods

Interfaces create contracts to implement in your test suites. Methods declared as default in an interface will always run in a test suite.

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
interface Interfaces{

    @BeforeAll
    default void initAll(){
            System.out.println("@BeforeAll runs once before all tests");
    }

    @BeforeEach
    default void init(){
            System.out.println("@BeforeEach runs before each test");
    }

    @AfterAll
    default void tearDownAll(){
            System.out.println("@AfterAll runs once after all tests");
    }

    @AfterEach
    default void tearDown(){
            System.out.println("@AfterEach runs after each test");
    }
}

    class ClassImplementingInterfaceTests implements Interfaces {

    @Test
    void myTest(){

    }
}

 @TestInstance(TestInstance.Lifecycle.PER_CLASS) is required to make @BeforeAll and @AfterAll work.

@RepeatedTest

 @RepeatedTest allows you to repeat a test as many times as you want by passing the number of desired repetitions to the annotation. 

@RepeatedTest(value = 10, name = "{displayName} {currentRepetition}/{totalRepetitions}")
void repetitionTest(){
}

@ParameterizedTest

When using the @ParameterizedTest annotation in combination with...

•  @ValueSource 
  
•  @EnumSource 
  
•  @MethodSource 
  
•  @CsvSource 
  
•  @CsvFileSource 
  
•  @ArgumentsSource 
  

You can run a test multiple times with different inputs each time, as shown below:

classParameterizedTests{

enum MyEnum {RED, GREEN, BLACK}

@ParameterizedTest
@ValueSource(ints ={2,4,8})
void integerParameters(int value){
        assertEquals(0, value % 2);
}


@ParameterizedTest
@EnumSource(value = MyEnum.class, names = {"RED","GREEN"})
void integerParameters(MyEnum myEnum){
        assertTrue(EnumSet.of(MyEnum.RED, MyEnum.GREEN).contains(myEnum));
}

@ParameterizedTest
@MethodSource("myStrings")
voidmethodSourceProvider(String string){
        assertTrue(Arrays.asList("hello","world").contains(string));
}

static ListString>myStrings(){
return Arrays.asList("hello","world");
}
}

 For  @MethodSource, if the method has the same name as a test, the parameter name is not required.

IMPORTANT: to make use of this feature, junit-jupiter-params needs to be added to the classpath.

Conclusion

As you can see, JUnit 5 is a huge improvement over previous versions and introduces many new testing features. It also allows you to write more expressive units test when using in combination with lambda expressions from Java 8.

For more examples, check out this repository in GitHub.