Improving Code Readability with Better Assertions in Java

1. Understand the Difference between Assertions and Exceptions
Assertions and exceptions are two completely different things, and using assertions in place of exceptions is not recommended.

Exceptions:

Handle unexpected runtime events.
Disrupt the normal flow of a program.
Meant to help the program recover from unexpected situations

Assertions:

Used to test and verify code assumptions.
Help improve code readability, documentation, testing, and debugging.
Represent invariants or properties that must be true or false at specific code points

2. Use assertTrue and assertFalse for Boolean Checks
Bad Code

// Redundant comparison

assertTrue(user.isLoggedIn() == true);

// Complex, hard-to-read conditional assertion
assertTrue(user.hasPermission("read") != false);

The improved version is:

// Clean, direct boolean assertions, Clearly checks login status
assertTrue(user.isLoggedIn());

// Multiple boolean checks with clear intent
assertAll(
() -> assertTrue(user.isAuthenticated(), "User should be authenticated"),
() -> assertTrue(user.hasPermission("read"), "User should have read permission")
);

3. Use assertNull and assertNotNull for Null Checks
This directly conveys the intention of the test, making the code more readable and easier to understand.

Bad Code
Using == null or != null can be less readable.

Assert.assertTrue(jsonPath.get("timestamp") != null, "Timestamp is miss");

The improved version is:

Although above code works, it can be made clearer and more expressive
by using assertNotNull

Assert.assertNotNull(jsonPath.get("timestamp"), "Timestamp is missing");

4. Use assertions to check preconditions and postconditions
Use assertions to check preconditions at the beginning of functions or methods to ensure that inputs are valid before executing the main logic.

In this example, the assertion checks a precondition (that x is positive) before proceeding with the rest of the method. If the assertion fails, it provides a clear error message.

public void testMethod(int x) {
    assert x > 0 : "x must be positive";
    System.out.println("x is positive");
}

5. Use Descriptive Assertion Messages
Always include a message in your assertions to explain what is being tested and why it might fail.

Avoid complex assertions that are hard to read and understand. Instead, break them down into smaller, simpler assertions.