JUnit 4 Assertions with Examples

1. Overview

In this post, we will learn all the Assert statements available in JUnit 4.
The assertions are available for all primitive types, Objects, and arrays (either of primitives or Objects).
The parameters order, within the assertion, is the expected value followed by the actual value; optionally the first parameter can be a String message that represents the message output of the evaluated condition.

2. JUnit 4 Assertions with Examples

List of Assert statements available in JUnit 4.
Let's discuss each asserts with an example.
Let’s start with the assertEquals one.

2.1 assertEquals

The assertEquals assertion verifies that the expected and the actual values are equal:
public void whenAssertingEquality_thenEqual() {
    String expected = "Ramesh";
    String actual = "Ramesh"; 
    assertEquals(expected, actual);
It’s also possible to specify a message to display when the assertion fails:
assertEquals("failure - strings are not equal", expected, actual);

2.2 assertArrayEquals

If we want to assert that two arrays are equals, we can use the assertArrayEquals:
public void whenAssertingArraysEquality_thenEqual() {
    char[] expected = {'J','u','n','i','t'};
    char[] actual = "Junit".toCharArray();
    assertArrayEquals(expected, actual);
If both arrays are null, the assertion will consider them equal:
public void givenNullArrays_whenAssertingArraysEquality_thenEqual() {
    int[] expected = null;
    int[] actual = null;
    assertArrayEquals(expected, actual);

2.3 assertNotNull and assertNull

When we want to test if an object is null we can use the assertNull assertion:
public void whenAssertingNull_thenTrue() {
    Object car = null;
    assertNull("The car should be null", car);
In the opposite way, if we want to assert that an object should not be null we can use the assertNotNull assertion.

2.4 assertNotSame and assertSame

With assertNotSame, it’s possible to verify if two variables don’t refer to the same object:
public void whenAssertingNotSameObject_thenDifferent() {
    Object cat = new Object();
    Object dog = new Object();
    assertNotSame(cat, dog);
Otherwise, when we want to verify that two variables refer to the same object, we can use the assertSame assertion.

2.5 assertTrue and assertFalse

In case we want to verify that a certain condition is true or false, we can respectively use the assertTrue assertion or the assertFalse one:
public void whenAssertingConditions_thenVerified() {
    assertTrue("5 is greater then 4", 5 > 4);
    assertFalse("5 is not greater then 6", 5 > 6);

2.6 fail

The fail assertion fails a test throwing an AssertionFailedError. It can be used to verify that an actual exception is thrown or when we want to make a test failing during its development.
Let’s see how we can use it in the first scenario:
public void whenCheckingExceptionMessage_thenEqual() {
    try {
        fail("Exception not thrown");
    } catch (UnsupportedOperationException e) {
        assertEquals("Operation Not Supported", e.getMessage());

2.7 assertThat

The assertThat assertion is the only one in JUnit 4 that has a reverse order of the parameters compared to the other assertions.
In this case, the assertion has an optional failure message, the actual value, and a Matcher object.
Let’s see how we can use this assertion to check if an array contains particular values:
public void testAssertThatHasItems() {
      Arrays.asList("Java", "Kotlin", "Scala"), 
      hasItems("Java", "Kotlin"));
Additional information, on the powerful use of the assertThat assertion with Matcher object, is available at Testing with Hamcrest.

3. Conclusion

In this post, we have learned JUnit 4 assertions with examples. The assertions are available for all primitive types, Objects, and arrays (either of primitives or Objects).
Read more on JUnit 4 Developers Guide.