JUnit Assertion


The assertArrayEquals assertion verifies that the expected and the actual arrays are equals:


public void whenAssertingArraysEquality_thenEqual() {

char[] expected = { ‘J’, ‘u’, ‘p’, ‘i’, ‘t’, ‘e’, ‘r’ };

char[] actual = “Jupiter”.toCharArray();

assertArrayEquals(expected, actual, “Arrays should be equal”);


If the arrays aren’t equal, the message “Arrays should be equal” will be displayed as output.



In case we want to assert that two floats are equals, we can use the simple assertEquals assertion:


public void whenAssertingEquality_thenEqual() {

float square = 2 * 2;

float rectangle = 2 * 2;

assertEquals(square, rectangle);


However, if we want to assert that the actual value differs by a predefined delta from the expected value, we can still use the assertEquals but we have to pass the delta value as the third parameter:


public void whenAssertingEqualityWithDelta_thenEqual() {

float square = 2 * 2;

float rectangle = 3 * 2;

float delta = 2;

assertEquals(square, rectangle, delta);



assertTrue and assertFalse:

With the assertTrue assertion, it’s possible to verify the supplied conditions are true:


public void whenAssertingConditions_thenVerified() {

assertTrue(5 > 4, “5 is greater the 4”);

assertTrue(null == null, “null is equal to null”);

assertTrue(null == null, “null is equal to null”);


Thanks to the support of the lambda expression, it’s possible to supply a BooleanSupplier to the assertion instead of a boolean condition.

Let’s see how we can assert the correctness of a BooleanSupplier using the assertFalse assertion:


public void givenBooleanSupplier_whenAssertingCondition_thenVerified() {

BooleanSupplier condition = () -> 5 > 6;

assertFalse(condition, “5 is not greater then 6”);



assertNull and assertNotNull :

When we want to assert that an object is not null we can use the assertNotNull assertion:


public void whenAssertingNotNull_thenTrue() {

Object dog = new Object();

assertNotNull(dog, () -> “The dog should not be null”);



In the opposite way, we can use the assertNull assertion to check if the actual is null:


public void whenAssertingNull_thenTrue() {

Object cat = null;

assertNull(cat, () -> “The cat should be null”);


In both cases, the failure message will be retrieved in a lazy way since it’s a Supplier.


assertSame and assertNotSame :

When we want to assert that the expected and the actual refer to the same Object, we must use the assertSame assertion:


public void whenAssertingSameObject_thenSuccessfull() {

String language = “Java”;

Optional<String> optional = Optional.of(language);

assertSame(language, optional.get());


In the opposite way, we can use the assertNotSame one.


4.6. fail

The fail assertion fails a test with the provided failure message as well as the underlying cause. This can be useful to mark a test when it’s development it’s not completed:


public void whenFailingATest_thenFailed() {

// Test not completed

fail(“FAIL – test not completed”);



 AssertAll :

One of the new assertion introduced in JUnit 5 is assertAll.

This assertion allows the creation of grouped assertions, where all the assertions are executed and their failures are reported together. In details, this assertion accepts a heading, that will be included in the message string for the MultipleFailureError, and a Stream of Executable.

Let’s define a grouped assertion:


public void givenMultipleAssertion_whenAssertingAll_thenOK() {



() -> assertEquals(4, 2 * 2, “4 is 2 times 2”),

() -> assertEquals(“java”, “JAVA”.toLowerCase()),

() -> assertEquals(null, null, “null is equal to null”)



The execution of a grouped assertion is interrupted only when one of the executables throws a blacklisted exception (OutOfMemoryError for example).


AssertIterableEquals :

The assertIterableEquals asserts that the expected and the actual iterables are deeply equal.

In order to be equal, both iterable must return equal elements in the same order and it isn’t required that the two iterables are of the same type in order to be equal.

With this consideration, let’s see how we can assert that two lists of different types (LinkedList and ArrayList for example) are equal:


public void givenTwoLists_whenAssertingIterables_thenEquals() {

Iterable<String> al = new ArrayList<>(asList(“Java”, “Junit”, “Test”));

Iterable<String> ll = new LinkedList<>(asList(“Java”, “Junit”, “Test”));

assertIterableEquals(al, ll);



 AssertNotEquals :

Complementary to the assertEquals, the assertNotEquals assertion asserts that the expected and the actual values aren’t equal:


public void whenAssertingEquality_thenNotEqual() {

Integer value = 5; // result of an algorithm

assertNotEquals(0, value, “The result cannot be 0”);



If both are null, the assertion fails.



In order to increase simplicity and readability, the new assertThrows assertion allows us a clear and a simple way to assert if an executable throws the specified exception type.

Let’s see how we can assert a thrown exception:


void whenAssertingException_thenThrown() {

Throwable exception = assertThrows(


() -> {

throw new IllegalArgumentException(“Exception message”);



assertEquals(“Exception message”, exception.getMessage());

assertEquals(“Exception message”, exception.getMessage());


The assertion will fail if no exception is thrown, or if an exception of a different type is thrown.


assertTimeout and assertTimeoutPreemptively :

In case we want to assert that the execution of a supplied Executable ends before a given Timeout, we can use the assertTimeout assertion:


public void whenAssertingTimeout_thenNotExceeded() {



() -> {

// code that requires less then 2 minutes to execute





However, with the assertTimeout assertion, the supplied executable will be executed in the same thread of the calling code. Consequently, execution of the supplier won’t be preemptively aborted if the timeout is exceeded.

In case we want to be sure that execution of the executable will be aborted once it exceeds the timeout, we can use the assertTimeoutPreemptively assertion.

Both assertions can accept, instead of an Executable, a ThrowingSupplier, representing any generic block of code that returns an object and that can potentially throw a Throwable.