Using Fail Assertion in JUnit

1. Overview

In this tutorial, we'll explore how to use JUnit fail assertion for common testing scenarios.

We'll also see fail() method differences between JUnit 4 and JUnit 5.

2. Using fail Assertion

The fail assertion fails a test throwing an AssertionError unconditionally.

When writing unit tests, we can use fail to explicitly create a failure under desired testing conditions.  Let's see some cases where this can be helpful.

2.1. Incomplete test

We can fail a test when it is incomplete or not yet implemented:

@Test
public void incompleteTest() {
    fail("Not yet implemented");
}

2.2. Expected Exception

We can also do it when we think an exception will happen:

@Test
public void expectedException() {
    try {
        methodThrowsException();
        fail("Expected exception was not thrown");
    } catch (Exception e) {
        assertNotNull(e);
    }
}

2.3. Unexpected Exception

Failing the test when an exception is not expected to be thrown is another option:

@Test
public void unexpectedException() {
    try {
        safeMethod();
        // more testing code
    } catch (Exception e) {
        fail("Unexpected exception was thrown");
    }
}

2.4. Testing Condition

We can call fail() when a result doesn't meet some desired condition:

@Test
public void testingCondition() {
    int result = randomInteger();
    if(result > Integer.MAX_VALUE) {
        fail("Result cannot exceed integer max value");
    }
    // more testing code
}

2.5. Returning Before

Finally, we can fail a test when the code doesn't return/break when expected:

@Test
public void returnBefore() {
    int value = randomInteger();
    for (int i = 0; i < 5; i++) {
        // returns when (value + i) is an even number
        if ((i + value) % 2 == 0) {
            return;
        }
    }
    fail("Should have returned before");
}

3. JUnit 5 vs JUnit 4

All assertions in JUnit 4 are part of org.junit.Assert class. For JUnit 5 these were moved to org.junit.jupiter.api.Assertions.

When we call fail in JUnit 5 and get an exception, we receive an AssertionFailedError instead of AssertionError found in JUnit 4.

Along with fail() and fail(String message), JUnit 5 includes some useful overloads:

• fail(Throwable cause)
• fail(String message, Throwable cause)
• fail(Supplier<String> messageSupplier)

In addition, all forms of fail are declared as public static <V> V fail() in JUnit 5. The generic return type V, allows these methods to be used as single-statement in lambda expressions:

Stream.of().map(entry -> fail("should not be called"));

4. Conclusion

In this article, we covered some practical use cases for the fail assertion in JUnit. See JUnit Assertions for all available assertions in JUnit 4 and JUnit 5.

We also highlighted the main differences between JUnit 4 and JUnit 5, and some useful enhancements of the fail method.

As always, the full source code of the article is available over on GitHub.