Testing Java code with the JUnit 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. This page sets up the smallest project that has a test: one class, one test class, and the console launcher that connects them.

The launcher jar

The launcher is a single jar with the JUnit 5 platform, the Jupiter engine and a command line program that runs tests. This image carries version 1.14.3 at /opt/java-tools/junit-platform-console-standalone.jar, and a wrapper named junit on the path runs it, so these pages write junit execute where another machine writes java -jar junit-platform-console-standalone-1.14.3.jar execute. The two forms are the same program with the same arguments.

Every command of this group was run with that jar on OpenJDK 21.0.13. The launcher needs a JDK 17 or newer and nothing else: no Maven, no Gradle and no plugin. A project without a build tool is two commands, which is exactly what makes the framework easy to see.

The class under test

The class is a program of its own, so it builds and runs without the test. It has a greeting that trims the name and refuses a blank one, and a shout that upper-cases the greeting; the main prints three lines that show the three cases:

public class Greeter { static String greet(String name) { if (name.isBlank()) { return "Hello, stranger"; } return "Hello, " + name.trim(); } static String shout(String name) { return greet(name).toUpperCase(); } public static void main(String[] args) { System.out.println(greet("Ada")); System.out.println(shout(" Grace ")); System.out.println(greet(" ")); } }

Code that is easy to test has this shape: small methods, no input from a terminal, and a return value instead of a print. The main is the demonstration and the tests call the methods directly, so neither depends on the other.

The test class

Four methods, each with @Test and one assertion. The class has no main and no constructor with arguments; the framework makes an object of it and calls one method per test. The order annotation is not required, but it makes the report read in the same order on every run, which this page needs:

import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.MethodOrderer; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.TestMethodOrder; @TestMethodOrder(MethodOrderer.MethodName.class) public class GreeterTest { @Test void greetsByName() { assertEquals("Hello, Ada", Greeter.greet("Ada")); } @Test void trimsTheName() { assertEquals("Hello, Grace", Greeter.greet(" Grace ")); } @Test void greetsAStranger() { assertEquals("Hello, stranger", Greeter.greet(" ")); } @Test void shoutsInCapitals() { assertEquals("HELLO, ADA", Greeter.shout("Ada")); } }

The methods are package-private and return nothing: JUnit calls them by reflection and ignores a return value. A method that takes a parameter is not a plain test, which is why the parameterised tests of another page have their own annotation. A test class in the unnamed package needs no import of the class it tests; a class in a package imports it, and the next pages show both.

Two commands

The test class imports the framework, so the launcher jar is on the compiler's class path as well as on the runner's. The first command compiles both files into out and then runs the program, which proves that the class under test is a program in its own right:

javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out Greeter.java GreeterTest.java
java -cp out Greeter

Hello, Ada
HELLO, GRACE
Hello, stranger

The second command is the launcher. --class-path out is where the compiled classes are, --scan-classpath asks it to look through that path for tests, and --disable-ansi-colors keeps the escape codes out of the output so it can be quoted on a page:

junit execute --class-path out --scan-classpath --disable-ansi-colors

Thanks for using JUnit! Support its development at https://junit.org/sponsoring

╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ GreeterTest ✔
│ ├─ greetsAStranger() ✔
│ ├─ greetsByName() ✔
│ ├─ shoutsInCapitals() ✔
│ └─ trimsTheName() ✔
└─ JUnit Vintage ✔

Test run finished after 183 ms
[ 4 containers found ]
[ 0 containers skipped ]
[ 4 containers started ]
[ 0 containers aborted ]
[ 4 containers successful ]
[ 0 containers failed ]
[ 4 tests found ]
[ 0 tests skipped ]
[ 4 tests started ]
[ 0 tests aborted ]
[ 4 tests successful ]
[ 0 tests failed ]

The report

The report is a tree and a table. The tree names what was discovered: the platform, the Jupiter engine, the class and its four methods, each with a mark. The table counts containers and tests separately, found, skipped, started, aborted, successful and failed. Four containers are the platform itself, the Jupiter engine, the suite and the class; four tests are the four methods.

The time on the Test run finished line is the whole run, JVM startup included, and it changes with the machine; the counts do not. Every method shows ✔ because every assertion held. A failed assertion prints ✘ on its method, the expected and the actual value under it, and a line of the stack trace that names the test method; the last count becomes one and the launcher exits with a non-zero status, which is what a build server reads.

JUnit Vintage is the engine for JUnit 4 tests. It is in the jar and it found nothing, because a Jupiter test is not a Vintage test. JUnit 4 itself is not a separate library in this image, and the workflow page says what that means for a project that still has JUnit 4 tests.

Why a test is not a program

A test class has no main, and adding one would not make the launcher run it: the launcher is the program, and it finds tests by the annotation. That is the whole design. A JVM starts once, the framework makes one object per test class and calls each method on it, and the report is the framework's account of what happened.

The method has to be non-static for a plain test, because the framework calls it on an object, and it must not take parameters, because the framework has nothing to pass. It returns void, and a failure is an exception thrown by an assertion rather than a returned value. The rules are small, and every one of them is a thing the framework could not guess.

What comes next

This page used one assertion, assertEquals. The next page goes through the assertions of the framework, the message a failure prints, and the report of a run that fails on purpose. After that come parameterised tests, the lifecycle, exceptions and temporary folders, and the last two pages put the files of a project in the layout a build tool expects and run the loop by hand.

The Java course has the same subject from the other side: lesson 127 puts a calculator under test and reads the same report, and lesson 128 shows the linters and the Maven build that this image cannot run.

The code on this page was compiled with OpenJDK 21.0.13 (javac) and run with the JUnit Platform Console Launcher 1.14.3 on Alpine Linux in a Docker container. The time in the report is that machine's and changes between runs.

Article author: Arthur Isaev