Take Unit Testing to the Next Level With JUnit 5
JUnit 5 is a huge improvement over previous versions. Check out this post where we explore this version and its new testing features.
Join the DZone community and get the full member experience.
Join For FreeJUnit 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@ExtendWith
instead. -
@Rule
and@ClassRule
were also removed, use@ExtendWith
instead.
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.
Published at DZone with permission of Sergio Martin. See the original article here.
Opinions expressed by DZone contributors are their own.
Comments