What JUnit 5 is and the launcher jar

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 prints a report. The JDK does not contain it, so a project adds it as a library. JUnit 5 is the current generation, and this course uses one jar that holds the whole framework and a command line program that runs tests.

What JUnit 5 is

The name covers three layers that a beginner can meet separately. JUnit Platform is the part that discovers tests and starts them; it knows nothing about annotations or assertions. JUnit Jupiter is the engine that understands @Test and the rest of the JUnit 5 annotations, and runs those methods. JUnit Vintage is a second engine that runs tests written for JUnit 4, so an old test suite keeps working next to a new one.

A launcher connects the platform to a command: an editor, a build tool, or the command line program of this course. The report in the next sections is what the command line launcher prints.

The version in this image

The image carries the standalone console launcher and a wrapper named junit on the path. Ask it for its version:

junit --version

JUnit Platform Console Launcher 1.14.3
JVM: 21.0.13.1 (Alpine OpenJDK 64-Bit Server VM 21.0.13.1+2-alpine-r0)
OS: Linux 6.8.0-149-generic amd64

The first line is the only version the course names: 1.14.3. The second and the third line describe the machine that ran it, a JDK 21 and a Linux kernel, and they change from one machine to another. The launcher needs Java 17 or newer, and this image has Java 21.

The launcher jar

The whole distribution is one file, /opt/java-tools/junit-platform-console-standalone.jar. The compiler needs it on the class path because the test imports org.junit.jupiter, and the launcher is started from the same file. The wrapper is a short script that runs it with java -jar; this course writes junit execute ... and the two forms mean the same program with the same arguments.

A project that uses Maven or Gradle names the same jar as a dependency and does not put it on a command line. This image has no network, so Maven cannot download it, and the course uses the jar directly. That also makes the two commands visible: a compiler call and a launcher call, with nothing hidden.

A first test

The smallest working example has two classes. Calc.java is the code under test: one static method that adds two numbers. CalcTest.java is the test: one method marked @Test that calls the method and asserts the result.

public class Calc { static int add(int a, int b) { return a + b; } }

import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.Test; public class CalcTest { @Test void addsOneAndThree() { assertEquals(4, Calc.add(1, 3)); } }

Compile both files with the jar on the class path, then ask the launcher to look through the output folder for tests:

javac -Xlint:all -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

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

╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│  └─ CalcTest ✔
│     └─ addsOneAndThree() ✔
└─ JUnit Vintage ✔

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

The tree says what was discovered and what each piece did, and the table counts containers and tests separately. Four containers are the platform, the Jupiter engine, the suite the launcher built and the class; one test was found, started and successful. The command returned status 0 because nothing failed. The next lesson on the report reads every line of it.

The test class line by line

import org.junit.jupiter.api.Test brings the annotation into the file, and the static import of Assertions.assertEquals lets the method call it by its short name. The class is public only because the file is named after it; JUnit can run a package-private test class as well.

The test method returns void and takes no parameters. That is the shape Jupiter requires: a test that returns a value or takes an argument without one of the parameter annotations is rejected at run time. The body is ordinary Java, and a test passes when the method returns without throwing. assertEquals throws AssertionFailedError when the two values differ, and that throw is what the launcher reports as a failure.

The order of the arguments is expected first, actual second. The next lesson writes a test for each part and then breaks one on purpose, so that the failure report is familiar before a real project produces it.

What comes next

Lesson 002 explains what the compiler needs and why the two commands name the files they do. Testing Java code with the JUnit launcher is the short article version of this setup, and Testing Java code collects the articles on assertions, parameterised tests and the lifecycle.

Exercises

  1. Add a second method to Calc, subtract, and a test for it. How many tests does the table count after the change?
  2. Change the expected value in the test to 5, run the launcher, and read the status the shell sees. Do not fix it yet.
  3. Run junit execute --class-path out --scan-classpath without --disable-ansi-colors. What appears around the tree?
  4. Compile without the jar on the class path and read the first error line. Which package does the compiler say is missing?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which part of JUnit 5 understands the @Test annotation?

    Answer

    JUnit Jupiter

    Jupiter is the engine for the JUnit 5 annotations; the platform discovers and starts tests, and Vintage runs JUnit 4 tests.

  2. What does junit --version name as the version of the launcher in this image?

    Answer

    1.14.3

    The first line of the output is JUnit Platform Console Launcher 1.14.3.

  3. Why is the launcher jar on the javac class path?

    Answer

    The test imports org.junit.jupiter classes, so the compiler must find them

    A test class imports JUnit types, and javac resolves every import on the class path.

  4. What does this program print? public class Q1 { public static void main(String[] args) { org.junit.jupiter.api.Assertions.assertEquals(4, 2 + 2); System.out.println("checked"); } }

    Answer

    checked

    The assertion is true, so it returns without throwing, and the next statement prints checked.

  5. What does this program print? public class Q2 { public static void main(String[] args) { System.out.println(2 + 2); org.junit.jupiter.api.Assertions.assertEquals(5, 2 + 2); System.out.println("after"); } }

    Answer

    4

    The first line prints 4; the assertion fails and throws, so the last println never runs.

  6. What does this program print? public class Q3 { public static void main(String[] args) { int total = 0; for (int n = 1; n <= 3; n++) { total += n; } System.out.println(total); } }

    Answer

    6

    The loop adds 1, 2 and 3, so the total is 6.

  7. What does this program print? public class Q4 { public static void main(String[] args) { String name = "JUnit"; System.out.println(name.length()); } }

    Answer

    5

    The string has five characters, so length returns 5.

  8. A test method returns void and takes no arguments. What happens when the method body ends without an exception?

    Answer

    The test passes

    Jupiter counts a test as successful when its method returns normally; a test without assertions still passes.

  9. Which line belongs in the class under test, not in the test class?

    Answer

    static int add(int a, int b) { return a + b; }

    The method under test is ordinary Java; the annotation, the assertion and the import belong to the test.

  10. What does this command print when the only test passes? junit execute --class-path out --scan-classpath --disable-ansi-colors

    Answer

    A tree of containers and the counts table, with tests failed at 0

    The launcher prints its report: the suite tree, the run time and the counts table.

The code on this page was built with OpenJDK 21.0.13 (javac) and run with JUnit Platform Console Launcher 1.14.3 on Alpine Linux in a Docker container.

Article author: Arthur Isaev