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

  1. Break addsTwoNumbers with a wrong expected value and read the failure line.
  2. Add a test that sum of the empty list is zero and remove the assertTrue.
  3. Run the launcher without --disable-ansi-colors and describe the difference.
  4. 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.

  1. 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.

  2. What does assertThrows take?

    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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. What does @TestMethodOrder change?

    Answer

    The order the methods run in, which is otherwise unspecified

    MethodName is one of the orderers, and it makes a printed report stable.

  10. 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