A unit test is a small program that checks one behaviour of your code and it reports the pass or the fail. JUnit 5 gives you the structure to write those tests. You have a method that is marked as a test, the assertions that fail loudly, and a runner that executes them all. The goal is not the coverage for its own sake. It is the confidence to change the code without breaking it.
This is the first lesson in the Java Projects and Build Tools module, and the next lesson in this module is about "How Do Professional Debugging and Logging Differ From print Statements?".
What is a unit test, really?
A unit test exercises one piece of the behaviour in isolation, with no database, no network and no timing dependency. It should run in the milliseconds and it should give the same answer every time. That isolation is what makes it useful. When a test fails, the failure points at a specific piece of the logic rather than at a whole system.
Before JUnit, the people wrote the checks by hand.
public class ManualHarness {
static int addDiscount(int price, int percent) {
return price - price * percent / 100;
}
public static void main(String[] args) {
check("full price", addDiscount(100, 0), 100);
check("ten percent", addDiscount(100, 10), 90);
check("twenty five percent", addDiscount(200, 25), 150);
System.out.println("all manual checks passed");
}
static void check(String label, int actual, int expected) {
if (actual == expected) {
System.out.println("PASS " + label + " -> " + actual);
} else {
System.out.println("FAIL " + label + " -> expected " + expected + " but got " + actual);
throw new AssertionError(label);
}
}
}The output is this.
PASS full price -> 100
PASS ten percent -> 90
PASS twenty five percent -> 150
all manual checks passedThat works for three checks. It does not work for three hundred, and it does not integrate with a build, it does not produce a report, and it does not tell you which test failed without reading the output line by line. JUnit replaces the hand-rolled harness with a convention that a build tool can run automatically.
What does a JUnit test look like?
Three things make a test a test. The class name usually ends in Test. A method carries the @Test annotation. And inside it, you call the assertions that compare the actual result with what you expected.
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class DiscountTest {
private PricingService pricing;
@BeforeEach
void setUp() {
pricing = new PricingService();
}
@Test
@DisplayName("applies no discount when the percentage is zero")
void appliesNoDiscount() {
assertEquals(100, pricing.discounted(100, 0));
}
@Test
@DisplayName("applies ten percent of the price")
void appliesTenPercent() {
assertEquals(90, pricing.discounted(100, 10));
}
@Test
@DisplayName("rejects a negative percentage")
void rejectsNegativePercentage() {
assertThrows(IllegalArgumentException.class, () -> pricing.discounted(100, -5));
}
}The output is this.
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS
All tests passed.Read the three test methods. Each one states a single behaviour in its own words, and the @DisplayName annotation says the same thing in the test report, which is what you read when something fails at three in the morning. The third test asserts that an exception is thrown, using assertThrows, and that is a real assertion and not a comment.
That file is not executed here, because a JUnit test needs the JUnit library on the classpath. The output block shows what the test runner prints once the library is available, and the next section shows how to add it.
How do you add JUnit to a project?
You use a build tool. The dependency block below is all a Maven project needs to compile and to run the tests. The scope of test keeps the library out of your shipped artefact.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>com.tutorsbot</groupId>
<artifactId>pricing</artifactId>
<version>1.0.0</version>
<properties>
<maven.compiler.release>21</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<junit.version>5.10.2</junit.version>
</properties>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
</plugin>
</plugins>
</build>
</project>With that in place, the command mvn test compiles the main sources, it compiles the test sources, and it runs every method that is annotated with @Test. The summary that it prints looks like the block above. There is a count of the tests run, a count of the failures, and a build result.
Which assertions should you use?
The ones that you reach for the most are assertEquals, assertTrue, assertFalse, assertNull, assertNotNull, assertSame and assertThrows. Each one takes an optional message as the last argument, and that message is what the failure report shows you. So write it.
There are two distinctions that trip the people up. The assertion assertEquals compares the values, so two different objects with the same contents are equal. The assertion assertSame compares the identity, so it passes only for the very same instance. And a test that asserts a long chain of the conditions tells you little when it fails. One assertion per behaviour gives you a precise failure message.
import java.util.List;
public class AssertionStyles {
record Order(String id, double amount, boolean paid) { }
static boolean isValid(Order order) {
return order.id() != null && !order.id().isBlank() && order.amount() >= 0;
}
public static void main(String[] args) {
Order good = new Order("A-1", 42.0, true);
Order bad = new Order(" ", -1, false);
System.out.println("good is valid : " + isValid(good));
System.out.println("bad is valid : " + isValid(bad));
System.out.println("equals style : " + good.equals(new Order("A-1", 42.0, true)));
System.out.println("message style : expected a non blank id but got "
+ (bad.id() == null || bad.id().isBlank() ? "blank" : "present"));
List<Order> orders = List.of(good);
System.out.println("contains : " + orders.contains(good));
System.out.println("all match : " + orders.stream().allMatch(Order::paid));
}
}The output is this.
good is valid : true
bad is valid : false
equals style : true
message style : expected a non blank id but got blank
contains : true
all match : trueThe third line of that output is the pattern to copy. Instead of asserting isValid and losing the reason, the code computes the reason and it includes it in the message. When the test fails at three in the morning, that message is the whole difference between a two-minute fix and an afternoon.
How should you structure a test class?
- One test class per production class, named after it.
- One test method per behaviour, named as a sentence about what should happen.
- Use
@BeforeEachfor the setup that every test needs, so each test starts from a known state. - Use
@Nestedinner classes to group the related cases without a long flat list. - Use
@DisplayNamewhen the method name cannot carry the meaning on its own. - Keep the production code free of the test-only branches. If a flag exists only for the tests, then the design is wrong.
That last point is the one that the experienced teams argue about. A production class that checks an isTest flag is carrying the test knowledge into the production code, and the test then verifies the flag rather than the behaviour.
What should you not unit test?
You do not test the language or your framework. A test that asserts that list.add works is testing the collection library, and it will break when the library changes. You do not test the getters that return a field and nothing else. You do not write a test that asserts that a method throws because the implementation happens to throw it today. Test the behaviour that you care about.
And you do not confuse a unit test with an integration test. A unit test runs in the milliseconds with no external systems. A test that opens a database connection belongs in a different suite that runs at a different point in the pipeline.
The habits to keep
- One behaviour per test, with a name that says what it checks.
- Always write the failure message. It is the part that you will read.
- Set up the state in
@BeforeEachand reset it for every test. - Assert on the values, and not on the implementation details.
- Keep the tests fast and deterministic, so that the suite is worth running.
- Run the suite before every commit and before every release.
Try it yourself: take a small class with two or three methods, such as a discount calculator or a string formatter, and write a test class for it with one test per behaviour. Include one test that expects an exception, and one that checks a boundary value such as zero. Run the suite and deliberately break one line of the production code to confirm that the right test fails with a message that tells you what broke.