JUnit 5 with the launcher
A test is a method that calls the code and compares what came back with what should have. JUnit is the framework that finds those methods, runs them and reports, and the JDK does not contain it: the image carries the standalone launcher jar, which is a single file with the framework and the program that runs it. The testing article group after the lessons goes through it in full; this lesson is the shape.
The class under test
Three methods and a main that prints, so the class is a program as well as a subject of tests. The division refuses zero with an ArithmeticException and a message of its own:
import java.util.List;
public class Calc {
static int add(int a, int b) {
return a + b;
}
static int divide(int a, int b) {
if (b == 0) {
throw new ArithmeticException("division by zero");
}
return a / b;
}
static int sum(List<Integer> values) {
int total = 0;
for (int value : values) {
total += value;
}
return total;
}
public static void main(String[] args) {
System.out.println("2 + 3 = " + add(2, 3));
System.out.println("10 / 4 = " + divide(10, 4));
System.out.println("sum = " + sum(List.of(1, 2, 3)));
}
}
The test class
A test method carries @Test, has no parameters and returns nothing, and calls one of the static assertion methods. The five below cover a result, a negative case with a message, a truncation, an expected exception with its message, and an empty list:
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import java.util.List;
import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestMethodOrder;
@TestMethodOrder(MethodOrderer.MethodName.class)
public class CalcTest {
@Test
void addsTwoNumbers() {
assertEquals(5, Calc.add(2, 3));
}
@Test
void addsNegatives() {
assertEquals(-1, Calc.add(2, -3), "2 + (-3)");
}
@Test
void dividesWithoutRemainder() {
assertEquals(2, Calc.divide(10, 4));
}
@Test
void refusesDivisionByZero() {
ArithmeticException error = assertThrows(ArithmeticException.class, () -> Calc.divide(1, 0));
assertEquals("division by zero", error.getMessage());
}
@Test
void sumsAList() {
assertEquals(6, Calc.sum(List.of(1, 2, 3)));
assertTrue(Calc.sum(List.of()) == 0);
}
}
The test classes are not compiled into the program, and the test class is not a program: it has no main, and the launcher finds it by its annotations. The third argument of assertEquals is the message a failure prints, and the lambda of assertThrows is the call that should fail, which is the only way to test an exception in a language where a throw leaves the method.
The launcher
The compile needs the launcher jar on the class path, and the run gives the launcher the compiled folder and asks it to scan that path for tests:
javac -cp /opt/java-tools/junit-platform-console-standalone.jar -d out Calc.java CalcTest.java
junit execute --class-path out --scan-classpath --disable-ansi-colors
The report
The launcher prints a tree of what it ran and a summary of the counts. The colours are switched off for the page, because the escape codes are not text a reader can compare:
Thanks for using JUnit! Support its development at https://junit.org/sponsoring
╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ CalcTest ✔
│ ├─ addsNegatives() ✔
│ ├─ addsTwoNumbers() ✔
│ ├─ dividesWithoutRemainder() ✔
│ ├─ refusesDivisionByZero() ✔
│ └─ sumsAList() ✔
└─ JUnit Vintage ✔
Test run finished after 240 ms
[ 4 containers found ]
[ 0 containers skipped ]
[ 4 containers started ]
[ 0 containers aborted ]
[ 4 containers successful ]
[ 0 containers failed ]
[ 5 tests found ]
[ 0 tests skipped ]
[ 5 tests started ]
[ 0 tests aborted ]
[ 5 tests successful ]
[ 0 tests failed ]
The time of 240 milliseconds is the framework starting up and the five methods running, and it changes with the machine. The four containers are the platform, Jupiter, the class and the suite; the five tests are the methods. A failure would print ✘ on the method and a stack trace under it, and the last count would be one.
JUnit Vintage is the engine for JUnit 4 tests, which is in the jar and found no test of its own. JUnit 4 and Mockito are not in the image as separate libraries, which the testing articles say in their own lesson.
The order of the tests
By default the order of the methods is the order the framework decides, which is not the source order and not alphabetical, so the tree above would change between runs of the same class. @TestMethodOrder(MethodOrderer.MethodName.class) fixes it to the name of the method, which is what this page needs and what a test that prints needs; a test that depends on the order of another test is a test that should be one test.
The annotations of the article group are the rest of the framework: @BeforeEach for a fixture, @ParameterizedTest for one test with many cases, @TempDir for a folder that is thrown away. None of them changes the command: the launcher scans, finds and runs.
Exercises
- Break addsTwoNumbers with a wrong expected value and read the failure line.
- Add a test that sum of the empty list is zero and remove the assertTrue.
- Run the launcher without --disable-ansi-colors and describe the difference.
- Move CalcTest into a package and run the launcher again.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What marks a method as a test in JUnit 5?
Answer
The @Test annotation
The framework finds the annotated methods, and the name does not matter.
-
What does
assertThrowstake?Answer
The expected class and a lambda with the call that should throw
The lambda is run inside the assertion, which catches and checks the exception.
-
What does the launcher need on its class path?
Answer
The compiled test classes and the classes they test
The scan finds the classes, and the tests call the code under test from the same path.
-
What does this program print?
public class Q1 { static int add(int a, int b) { return a + b; } public static void main(String[] args) { System.out.println(add(2, 3)); System.out.println(add(-2, -3)); } }Answer
5 / -5
The two calls add two integers, and the sum of two negatives is negative.
-
Why is a test method not a program?
Answer
It has no main, and the framework calls it by its annotation
The launcher is the program, and the tests are methods it discovers and calls.
-
What is the third argument of
assertEquals?Answer
A message the failure prints
The message is shown with the two values, which is what identifies the case in a report.
-
What does the summary of the report count?
Answer
Containers and tests, found, started, successful and failed
The launcher reports both the containers it discovered and the tests inside them.
-
What happens when an assertion fails in
addsTwoNumbers?public class Q2 { public static void main(String[] args) { System.out.println(5 == 4); System.out.println(5 == 5); } }Answer
false / true
The two comparisons are false and true, and the program is not a test at all.
-
What does
@TestMethodOrderchange?Answer
The order the methods run in, which is otherwise unspecified
MethodName is one of the orderers, and it makes a printed report stable.
-
Why does the compile command repeat the launcher jar?
Answer
The test class imports the framework, so javac needs it on the class path
The annotations and assertions are classes of the jar, and the compiler must find them.
The code on this page was built with OpenJDK 21.0.13 (javac and java) and run on Alpine Linux in a Docker container.
Article author: Arthur Isaev