Using Java Assertions

1. Introduction

The Java assert keyword allows developers to quickly verify certain assumptions or state of a program.

In this article, we’ll take a look at how to use the Java assert keyword.

2. History of Java Assertions

The Java assert keyword was introduced in Java 1.4, so it’s been around for quite a while. However, it remains a little-known keyword that can drastically reduce boilerplate and make our code more readable.

For example, often times in our code we need to verify certain conditions that might prevent our application from working properly. Typically we’d write something like this:

Connection conn = getConnection();
if(conn == null) {
    throw new RuntimeException("Connection is null");
}

Using assertions we can remove the if and throw statement with a single assert statement.

3. Enabling Java Assertions

Because Java assertions use the assert keyword, there are no libraries needed or packages to import.

Note that prior to Java 1.4 it was perfectly legal to use the word “assert” for naming variables, methods, etc. This potentially creates a naming clash when using an older code with newer JVM versions.

Therefore, for backward compatibility, the JVM disables assertion validation by default. They must be explicitly enabled using either the -enableassertions command line argument, or its shorthand -ea:

java -ea com.baeldung.assertion.Assertion

In this example, we’ve enabled assertions for all classes.

We can also enable assertions for specific packages and classes:

java -ea:com.baeldung.assertion... com.baeldung.assertion.Assertion

Here, we’ve enabled assertions for all the classes in the com.baeldung.assertion package.

Likewise, they can be disabled for specific packages and classes using the -disableassertions command line argument, or its shorthand -da. We can also use all four of these arguments together.

4. Using Java Assertions

To add assertions, simply use the assert keyword and give it a boolean condition:

public void setup() {
    Connection conn = getConnection();
    assert conn != null;
}

Java also provides a second syntax for assertions that takes a string, which will be used to construct the AssertionError if one is thrown:

public void setup() {
    Connection conn = getConnection();
    assert conn != null : "Connection is null";
}

In both cases, the code is checking that a connection to an external resource returns a non-null value. If that value is null, the JVM will automatically throw an AssertionError.

In the second case, the exception will have the additional detail that will show up in the stack trace and can aid in debugging the problem.

Let’s have a look at the result of running our class with assertions enabled:

Exception in thread "main" java.lang.AssertionError: Connection is null
        at com.baeldung.assertion.Assertion.setup(Assertion.java:15)
        at com.baeldung.assertion.Assertion.main(Assertion.java:10)

5. Handling an AssertionError

The class AssertionError extends Error, which itself extends Throwable. This means that AssertionError is an unchecked exception.

Therefore methods that use assertions are not required to declare them, and further calling code should not try and catch them.

AssertionErrors are meant to indicate unrecoverable conditions in an application, so never try to handle them or attempt recovery.

6. Best Practices

The most important thing to remember about assertions is that they can be disabled, so never assume they’ll be executed.

Therefore keep the followings things in mind when using assertions:

• Always check for null values and empty Optionals where appropriate
• Avoid using assertions to check inputs into a public method and instead use a checked exception such as IllegalArgumentException or NullPointerException
• Don’t call methods in assertion conditions and instead assign the result of the method to a local variable and use that variable with assert
• Assertions are great for places in the code that will never be executed, such as the default case of a switch statement or after a loop that never finishes

7. Conclusion

The Java assert keyword has been available for many years but remains a little-known feature of the language. It can help remove lots of boilerplate code, make the code more readable, and help identify bugs early in program development.

Just remember that assertions aren’t enabled by default, so never assume they will be executed when used in the code.

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