Testing your code with JUnit

Until now you have checked every class the same way: run main, read what it prints, and decide in your head whether the numbers look right. That works on the day you write the code. This lesson moves the checking into code. You will write small tests that know the right answers, run all of them in a second, and run them again after every change, so a mistake shows up minutes after you make it instead of months later.

Checking by eye does not last#

Here is the BankAccount from the encapsulation lesson, cut down to whole amounts so the sums stay easy. The usual way to check a class like this is a main that calls a few methods and prints the results.

It prints After deposit: 150 and After withdraw: 120. To decide whether that is right, you work the sums out yourself: 100 plus 50 is 150, and 150 minus 30 is 120. The program printed numbers, and you did the checking.

That is fine today. Next month you add a fee to withdraw, or someone tidies up deposit. Is the class still right? To find out you would run main again, read every line and redo every sum, for every method you ever checked. Nobody does that after every change, so a mistake can sit in the code for weeks before anyone notices a wrong number.

Write the right answer into the code

The fix is to write the answer you expect into the program, next to the call, and let the computer compare the two. Then the program can say for itself whether it passed.

This prints PASS: deposit and PASS: withdraw. The fact that the balance should be 150 now lives in the code, so the check can run again tomorrow, or next year, without you. Code like this, which runs a piece of a program and checks the result itself, is a test. A test of one small piece, usually one method of one class, is a unit test.

Hand-made checks soon grow tedious, though. Each one needs its own if, else and message. Both checks share one account, so if the deposit went wrong, the withdraw check would start from a wrong balance and fail too, even with nothing wrong in withdraw. And you still have to read the output to spot the word FAIL. A testing library takes care of all of that.

Key idea

A unit test runs one small piece of your code and checks the answer itself. The expected answer is written down, so every check can run again in seconds after any change.

Your first JUnit test#

JUnit is the testing library most Java projects use. A library is code that someone else wrote and you add to your project. JUnit does not come with the JDK, and the last section of this page shows how a real project adds it. In this course the engine has JUnit built in, so a test class runs with the Run button like any other program.

Here is the same BankAccount with a test class under it. There is no main. Press Run, then step through and watch the engine make a new BankAccountTest object for each test.

The console shows a report: the name of the test class, one line per test with a tick (✔) when it passed, and a count at the end, 2 tests: 2 passed, 0 failed.

Reading the test class

• import org.junit.jupiter.api.Test; brings in JUnit's @Test, the way import java.util.ArrayList; brought in ArrayList. org.junit.jupiter.api is the package JUnit keeps it in.
• import static org.junit.jupiter.api.Assertions.assertEquals; is a static import. It lets you write assertEquals(...) where you would otherwise need Assertions.assertEquals(...). The word static gets a full explanation in static and final; here it only means “let me use this method by its short name”.
• class BankAccountTest is an ordinary class. By convention a test class is named after the class it tests, with Test on the end.
• @Test marks a method as a test. Like @Override, it is an annotation, a label on the code. JUnit looks for methods with this label and runs each one.
• Each test method is void and takes no parameters, because JUnit calls it with nothing to pass in and nothing to take back. Later on this page you will meet tests that do take a parameter.
• assertEquals(150, account.getBalance()) is the check. The first argument is the value you expect, and the second is the value the code actually produced. If they are equal, the line does nothing and the test carries on. If they differ, the test stops on that line and counts as failed.

When a test fails

A test earns its keep on the day it fails. Break the class on purpose: in withdraw, change the minus into a plus. It is an easy slip to make when you copy deposit to write withdraw.

The second line of the report now has a cross (✘) and a message: withdrawTakesFromTheBalance(): expected: <70> but was: <130>. Read it in three parts. First comes the name of the test, which tells you which behaviour broke. Then expected: <70>, the first argument you gave assertEquals. Then but was: <130>, what getBalance() really returned. 130 is 100 plus 30, which points straight at the plus sign in withdraw.

depositAddsToTheBalance still passes. Each test reports on its own, so one broken method does not hide the results of the others.

The shape of a test#

Look at depositAddsToTheBalance again. It does three things in order, and almost every good test does the same three.

1. 1Arrange what the test needs. Here, an account with 100 in it.
2. 2Act by calling the one method the test is about. Here, deposit 50.
3. 3Assert that the result is right. Here, the balance should now be 150.

The pattern is called arrange, act, assert. It gives every test the same layout, so a reader always knows where to look. Some people mark the three parts with comments, and others leave a blank line between them. The two tests below use one style each, and they bring in one more annotation.

The report now shows sentences in place of method names. @DisplayName, imported from org.junit.jupiter.api like @Test, gives a test any name you like for the report, spaces included. JUnit still calls the method by its real name.

One behaviour per test

You could write one long test that deposits, withdraws and checks the balance after each step. It would work until something broke. Then its name could not tell you which step went wrong, and because a failed assertion ends the test on that line, the checks after it would never run. You would fix one bug, run again, and only then meet the next one. Two small tests give two separate answers at once.

One behaviour does not have to mean one assertEquals. A test that a refused deposit leaves the balance alone needs two checks, one for the refusal and one for the balance, and you will meet it in the next section. Both checks describe a single behaviour, so they belong in one test.

Names that say what should happen

A test's name is the first thing you read when it fails, so make it a sentence about the behaviour. withdrawTakesFromTheBalance tells you what broke, and test2 tells you nothing. Method names cannot contain spaces, so the words run together, each new word starting with a capital letter. When you want a real sentence in the report, add @DisplayName.

Key idea

Every test has the same shape: arrange what it needs, act once, assert the result. Test one behaviour at a time, and name each test after what should happen.

The assertions you will use most#

assertEquals is one of many checks in JUnit's Assertions class. These are the ones you will reach for most often.

True, false and null

A small phone book uses three of them. numberFor returns a person's number, or null when the name is not listed, and has answers yes or no.

All four pass. assertEquals compared the two strings with equals, so it checked the text itself, which is what you want after the == trap from the references lesson. When one of these assertions fails, its message follows the pattern you already know. A failing assertTrue says expected: <true> but was: <false>, and a failing assertNull shows what it found instead, such as expected: <null> but was: <555-0102>.

Comparing doubles: the delta

Numbers with a decimal point need more care. Before you run this, decide what it prints.

Java prints 0.30000000000000004 and then false. A double stores numbers in binary, and most decimal fractions, 0.1 among them, have no exact binary form, just as 1/3 has no exact decimal form (0.333, with threes forever). Java stores the nearest value it can, and after some arithmetic the tiny gaps show.

So a test that compares doubles exactly can fail even when the code is right. This running log adds up distances in kilometres:

The first test fails with expected: <0.3> but was: <0.30000000000000004>. The second passes, because its assertEquals has a third argument, the delta: the largest difference you are willing to accept. assertEquals(0.3, total, 0.000001) passes when the two numbers are within 0.000001 of each other. Pick a delta far smaller than any difference that matters in your program, and give one every time you compare doubles.

Testing that bad input is refused

In the encapsulation lesson, deposit refused a negative amount by printing a message and carrying on, and the code that called it never found out. The usual way for a Java method to refuse is to throw an exception: a signal that something went wrong, the same kind of signal that stopped your programs with an ArrayIndexOutOfBoundsException or a NullPointerException. The new deposit below starts with a check that ends in this line: throw new IllegalArgumentException("Deposit must be positive");

IllegalArgumentExceptionis the exception the JDK provides for “you passed a value I cannot accept”, and the text in quotes is its message. throw stops the method on the spot, so the balance never changes. If nothing deals with the exception, the whole program stops, as this one does. Step through it.

The first deposit works and the program prints Balance: 150. The second call throws, and the program stops with Exception in thread "main" java.lang.IllegalArgumentException: Deposit must be positive before it reaches the last line.

Refusing bad input is behaviour, so it deserves a test. assertThrows checks that a piece of code throws a given type of exception.

Both tests pass. assertThrows takes two arguments. The first, IllegalArgumentException.class, names the type of exception you expect: .class after a class name refers to the class itself. The second, () -> account.deposit(-50), is the code to run.

That second argument is new syntax. Java normally runs a method call the moment it reaches it, and a call that throws would end the test before assertThrows could watch for anything. Writing () -> in front of the call packs the call up without running it and hands the package to assertThrows, which runs it inside its own safety net, catches what it throws and checks the type. For now, copy the shape: () -> followed by the call you want to test. The syntax is called a lambda, and it gets a full explanation in enums, lambdas and functional interfaces.

The second test checks two things about one behaviour, as promised: the deposit is refused, and the balance is still 100 afterwards.

One more case. A test that calls account.deposit(-50) without assertThrows fails too. The exception escapes the test method, and the report gives it as the reason: java.lang.IllegalArgumentException: Deposit must be positive. Any exception you did not expect fails the test.

A fresh start for every test#

Every BankAccount test so far begins with the same line, BankAccount account = new BankAccount(100);. When several tests share a starting point, you can move it into a field and a method marked @BeforeEach. JUnit runs that method before each test.

Step through it and watch setUp run twice, once before each test, building a new account with 100 in it each time. The deposit test leaves 150 in its account, and the withdraw test never sees it: it starts from 100 and ends at 70.

Every test gets a new object

@BeforeEach is only half the story. In this test class, each test adds one to the field count, prints it and checks it. Predict the report.

Both tests print count is 1 and both pass. JUnit makes a new object of the test class for every test method, so each test starts with its fields freshly set: count is 0 again, and in BankAccountTest the field account holds a brand-new account. That is also why a field such as WordCounter counter = new WordCounter();, which you will meet in the next section, is safe in a test class. Every test gets its own.

This protects a rule that good tests follow: no test may depend on another. If the withdraw test only passed after the deposit test had run, its result would depend on the order, and JUnit does not promise to run tests in the order you wrote them. Its documentation says the order stays the same from run to run but is deliberately not obvious. A test that passes on its own and fails next to the others, or the other way round, can take hours to untangle.

Key idea

Each test builds its own starting point and leaves nothing behind for the next. JUnit makes a new test object for every test, and @BeforeEach rebuilds the shared setup each time.

Edge cases: where bugs hide#

The tests so far use ordinary inputs, like 100 in the account and a sensible deposit. Code usually works for ordinary inputs, because those are the ones you pictured while writing it. Bugs gather where you did not look: at the ends of the allowed range, and at inputs so small or odd that they never came to mind. Inputs like that are called edge cases, and they tend to turn up in the same places:

• Empty input, such as the empty string "", an empty array or an account holding 0.
• Zero and negative numbers, anywhere a number comes in.
• Values right on a boundary. If 90 and above earns an A, test 90 and 89, the last value on each side.
• Exactly one of something, such as a one-letter word or an array with one element.
• Text with odd spacing, such as spaces at the start or the end, or two spaces in a row.

A test that finds a real bug

In string practice you planned a word counter: count the spaces and add one. For "hello there friend" that gives 3, which is right. Here is that plan as a class, with one ordinary test and three edge-case tests. Run it.

Only the ordinary test passes. Each failure tells you something different.

• findsNoWordsInEmptyText(): expected: <0> but was: <1>. Empty text has no spaces, so the method returns 0 plus 1.
• ignoresSpacesAtTheEnds(): expected: <2> but was: <4>. The spaces before hello and after world count as gaps between words.
• treatsTwoSpacesInARowAsOneGap(): expected: <2> but was: <3>. Two spaces side by side count as two gaps.

“Spaces plus one” was only ever right for text with single spaces between words and none at the ends. Running it on a normal sentence would never show that, and three short tests showed it at once. Step through the empty-text test to see the cause: the loop never runs, spaces stays 0, and the method returns 1.

1import org.junit.jupiter.api.Test;
2 
3import static org.junit.jupiter.api.Assertions.assertEquals;
4 
5class WordCounter {
6    int countWords(String text) {
7        int spaces = 0;
8        for (int i = 0; i < text.length(); i++) {
9            if (text.charAt(i) == ' ') {
10                spaces++;
11            }
12        }
13        return spaces + 1;
14    }
15}
16 
17class WordCounterTest {
18    WordCounter counter = new WordCounter();
19 
20    @Test
21    void countsTheWordsInASentence() {
22        assertEquals(3, counter.countWords("hello there friend"));
23    }
24 
25    @Test
26    void findsNoWordsInEmptyText() {
27        assertEquals(0, counter.countWords(""));
28    }
29 
30    @Test
31    void ignoresSpacesAtTheEnds() {
32        assertEquals(2, counter.countWords(" hello world "));
33    }
34 
35    @Test
36    void treatsTwoSpacesInARowAsOneGap() {
37        assertEquals(2, counter.countWords("hello  world"));
38    }
39}

Key idea

Bugs gather at the edges: empty input, zero, negative numbers and the values right at a limit. Test them on purpose, because ordinary inputs rarely find them.

One test, many inputs

Edge-case tests often look alike: the same call with a different input and a different expected answer. A parameterized test is written once and runs once per input. You mark the method @ParameterizedTest in place of @Test, give it a parameter, and add a source of values. @ValueSource lists values of one type. Here it feeds words to the palindrome checker from string practice.

The report has one line per value, numbered from 1, with the value at the end, such as acceptsWordsThatReadTheSameBothWays(String) [1] racecar. Two short methods made seven checks. The word "a" is in the first list on purpose: a one-letter word is an edge case, and it does read the same both ways.

When each input has its own expected answer, use @CsvSource. Each string in it is one row, and the values in a row are separated by commas, like a line of a spreadsheet saved as CSV (comma-separated values). JUnit converts each value to the type of the matching parameter, so the row "90, A" becomes the int 90 and the String "A". This grader's table tests both sides of every boundary: 90 and 89, 80 and 79, 70 and 69.

One row fails: [2] 90, A: expected: <A> but was: <B>. The method says score > 90, so a score of exactly 90 falls through to B. The fix is score >= 90. A test with 95 would never have caught this. The row on the boundary did.

Test first: red, green, refactor#

So far you wrote the code first and the tests afterwards. Test-driven development, or TDD, turns that around: you write a test for behaviour that does not exist yet, watch it fail, and only then write the code. Kent Beck, one of JUnit's two authors, made the practice popular. It runs in a short loop.

1. 1Write one small test for the next piece of behaviour and run it. It fails, and most tools show a failure in red, so this is the red step. Seeing the test fail proves that it can catch the missing behaviour.
2. 2Write the least code that makes every test pass, and nothing more. The tests go green.
3. 3Tidy the code, with clearer names, less repetition or a simpler loop, and run the tests after each change to make sure they are still green.

Changing how code is written without changing what it does is called refactoring, and it names the third step. After it you go round the loop again with the next test. The example below builds a method that turns a full name into initials, so that Ada Lovelace becomes AL. Step through it, and read the report under the code at every step.

Three moves in that example are worth a second look.

• Step 1 starts from a stub, a method with a placeholder body that compiles but does nothing useful. In a real project the very first run often fails even earlier, with a compile error, because initials does not exist yet. Adding the stub is the quickest way from that error to a real red test.
• Step 2 returns "AL" for every name. That looks like cheating, and it is on purpose: it is the least code that passes, and it forces the next test to demand a real answer. Each step stays tiny, so when a test goes red you know which change caused it.
• Step 7 rewrites the whole loop. Without tests that would be a gamble. With three tests that still pass after the change, you know the new code does everything the old code did.

Key idea

Red, green, refactor: write a failing test, make it pass with the simplest code, then tidy the code while the tests stay green. Then start again with the next test.

Writing the test first has a second benefit. It makes you decide what the method should do, its name, its inputs and its answer for each case, before you think about how. Some developers work this way for every change, and others save it for fiddly logic. Either way, the loop is worth practising until it feels normal.

1import org.junit.jupiter.api.Test;
2import org.junit.jupiter.params.ParameterizedTest;
3import org.junit.jupiter.params.provider.CsvSource;
4 
5import static org.junit.jupiter.api.Assertions.assertEquals;
6import static org.junit.jupiter.api.Assertions.assertThrows;
7 
8class SongLength {
9    String format(int seconds) {
10        // TODO: make every test below pass
11        return "";
12    }
13}
14 
15class SongLengthTest {
16    SongLength songLength = new SongLength();
17 
18    @ParameterizedTest
19    @CsvSource({"187, 3:07", "60, 1:00", "59, 0:59", "5, 0:05", "0, 0:00", "3600, 60:00"})
20    void writesMinutesAndSeconds(int seconds, String expected) {
21        assertEquals(expected, songLength.format(seconds));
22    }
23 
24    @Test
25    void refusesANegativeLength() {
26        assertThrows(IllegalArgumentException.class, () -> songLength.format(-1));
27    }
28}

Running tests in a real project#

The snippets on this page put a class and its tests in one file, so that the Run button can show both. A real project keeps them apart. The class goes under src/main/java and its tests under src/test/java, in a test class named after it:

The test code can use every class in src/main/java, but it stays out of the finished program. Maven and Gradle, the two build tools most Java projects use, both expect this layout. The project also lists JUnit as a dependency, a library the build tool downloads for you. In Maven's build file, pom.xml, that is one entry:

<scope>test</scope>means JUnit is only used to compile and run the tests, and is never shipped with the program. Gradle declares the same library in its own format, together with JUnit's launcher, and adds useJUnitPlatform() to switch JUnit on. Setting up either tool from scratch is the job of Maven and Gradle. For now, read the output below as a preview.

In your editor

IntelliJ IDEA and VS Code show a small run button in the margin beside each test class and each test method. In Eclipse you right-click the class and choose Run As, then JUnit Test. The results appear in a panel that lists every test and marks which passed and which failed. Click a failed test to see the expected and actual values and to jump to the line that failed. Most editors can also create an empty test class for you, in the right folder.

From the terminal: mvn test

mvn testcompiles the project and runs every test class. Maven's test runner, a plug-in called Surefire, finds test classes by their names: by default, names that end in Test, Tests or TestCase, or start with Test. Here is the real output for the broken withdraw from earlier, with the compiling steps cut from the top: