A suite of test classes

A filter chooses from the classes the launcher finds. A suite names them, so a run can be one file in the repository: the classes of a module, a package, or a hand-picked set. JUnit Platform has a suite engine for this, and the standalone jar carries it.

@Suite

@Suite marks a class as a suite; @SelectClasses lists the test classes. The class has no tests of its own and no body. The launcher discovers it like a test class and the suite engine runs the selected classes inside it.

The other selectors are @SelectPackages, @SelectClasspathResource and @SelectDirectories. They choose by location instead of by name, which is convenient for a whole module and fragile when a new package appears.

The two test classes

FastTest.java and SlowTest.java are ordinary test classes with one test each. No annotation ties them to the suite; the suite names them.

import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.Test; public class FastTest { @Test void adds() { assertEquals(4, 2 + 2); } }

import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.Test; public class SlowTest { @Test void halves() { assertEquals(5, 10 / 2); } }

The suite class

AllTests.java has the two annotations and nothing else. The braces are empty because the class is a container, not a test.

import org.junit.platform.suite.api.SelectClasses; import org.junit.platform.suite.api.Suite; @Suite @SelectClasses({FastTest.class, SlowTest.class}) public class AllTests { }

One run over both

The launcher selects the suite by name, and the suite engine runs the two classes. The classes do not need to sit in the same package as the suite; the selector uses the class object, so an import brings each one in.

javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out FastTest.java SlowTest.java AllTests.java
junit execute --class-path out --select-class AllTests --disable-ansi-colors

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

╷
├─ JUnit Platform Suite ✔
│  └─ AllTests ✔
│     └─ JUnit Jupiter ✔
│        ├─ FastTest ✔
│        │  └─ adds() ✔
│        └─ SlowTest ✔
│           └─ halves() ✔
├─ JUnit Jupiter ✔
└─ JUnit Vintage ✔

Test run finished after 1088 ms
[         7 containers found      ]
[         0 containers skipped    ]
[         7 containers started    ]
[         0 containers aborted    ]
[         7 containers successful ]
[         0 containers failed     ]
[         2 tests found           ]
[         0 tests skipped         ]
[         2 tests started         ]
[         0 tests aborted         ]
[         2 tests successful      ]
[         0 tests failed          ]

The nested report

The suite adds a layer to the tree: AllTests contains a Jupiter engine, which contains the two classes. The counts are seven containers because the suite and its inner engine are containers as well as the two classes. The tests are still two, because the suite holds tests, not extra ones.

The second JUnit Jupiter line at the foot is the engine of the launcher's own run, beside the suite. It is empty because the launcher selected only the suite class; the tests ran inside the suite's Jupiter line.

What a suite is for

A suite is a name for a set of classes: the smoke set, the integration set, the classes of one module. It is compiled with the tests and run by name, so a build script needs one argument instead of a package scan. The suite engine is in the standalone jar of this course; a project that uses JUnit through Maven adds the junit-platform-suite artifact for it.

A suite that lists classes by hand needs an edit when a class is renamed or added. That is the trade for an explicit set: the list is visible in one place and nothing runs by accident.

Exercises

  1. Remove one class from the selector and run. Which counts change?
  2. Add the same class twice to the selector. What does the report do?
  3. Run the folder with --scan-classpath instead of selecting the suite. How many tests run, and does the suite run twice?
  4. Replace @SelectClasses with @SelectPackages for the unnamed package and compare the counts.

Questions

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

  1. What does @Suite mark?

    Answer

    A class that selects other test classes

    The suite class is a container whose selection annotations name the tests to run.

  2. Which annotation lists the classes of this suite?

    Answer

    @SelectClasses

    SelectClasses takes the class objects of the test classes to include.

  3. Why does the suite report have more containers than a plain run of the same tests?

    Answer

    The suite and its inner engine are containers too

    Containers include the suite and the engine inside it; tests stay the same.

  4. What does this program print? public class Q1 { public static void main(String[] args) { System.out.println(2 + 2); } }

    Answer

    4

    The two integers are added, and println prints 4.

  5. What does this program print? public class Q2 { public static void main(String[] args) { System.out.println(10 / 2); } }

    Answer

    5

    Ten divided by two is five.

  6. What does this program print? public class Q3 { public static void main(String[] args) { System.out.println("AllTests".endsWith("Tests")); } }

    Answer

    true

    The class name ends with Tests, so the check is true.

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

    Answer

    SUITE

    toUpperCase changes every letter to upper case.

  8. What happens when a suite selector names a class that does not exist?

    Answer

    The suite fails before any test runs, with a clear error

    The class object cannot be resolved, so the suite cannot start and reports the missing class.

  9. What does this program print? public class Q5 { public static void main(String[] args) { System.out.println("FastTest".length()); } }

    Answer

    8

    FastTest has eight characters.

  10. Which selector chooses classes by location rather than by name?

    Answer

    @SelectPackages

    SelectPackages and SelectDirectories choose a location; SelectClasses names the classes.

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