Using Fail Assertion in JUnit

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

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.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.