The class under test and the test class

A test is not one file. The code under test and the code that checks it are two classes, usually in two files, and the compiler must see both at once: the test calls the class, so the class must be on the class path, and the class itself does not mention JUnit. This lesson separates the two roles and shows what each command reads.

Two files

Greeter.java is ordinary Java. It has one static method, and nothing in it imports a test library:

public class Greeter { static String greet(String name) { return "Hello, " + name + "!"; } }

GreeterTest.java is the test. It imports the assertion and the annotation, declares a method that returns void, and checks two inputs:

import static org.junit.jupiter.api.Assertions.assertEquals; import org.junit.jupiter.api.Test; public class GreeterTest { @Test void greetsByName() { assertEquals("Hello, Ada!", Greeter.greet("Ada")); } @Test void greetsAStranger() { assertEquals("Hello, stranger!", Greeter.greet("stranger")); } }

The test may live in the same package as the class, and here both are in the unnamed package, so no import names Greeter. A larger project puts both in a package, and then the test imports the class like any other.

The class path

The compiler reads GreeterTest.java and finds three names it does not define: Assertions, Test and Greeter. The first two come from the launcher jar, which is why the command names it after -cp. The third comes from the other source file, which is on the same command line, so the compiler reads it in the same run.

A class path is a list of places where compiled classes and jars live. Here it has one entry, the jar. The output folder is not on it during the build: the compiler writes the class files there with -d and does not need to read them back.

File names and class names

Both classes are public, so each file is named exactly after its class, case included. The compiler enforces the rule before it reads the body, and a test class is no exception: save GreeterTest in Test.java and the build stops with class GreeterTest is public, should be declared in a file named GreeterTest.java.

The launcher reads the class name from the compiled file, not from the source name, so the rule costs nothing at run time. It also means a page that shows a test class must say which file it is: the next lessons write the file name above every block.

One build, one run

The build compiles both files into out. The run gives the launcher that folder as its class path and asks it to scan the folder for test classes:

javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out Greeter.java GreeterTest.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 ✔
│  └─ GreeterTest ✔
│     ├─ greetsByName() ✔
│     └─ greetsAStranger() ✔
└─ JUnit Vintage ✔

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

Both methods ran, and the table counts two tests. The order in the tree is not the order of the source file: the launcher sorts the methods of a class by a deterministic but unspecified rule, and a test must not depend on another one having run first.

Two keys on the command line

--class-path out says where the compiled classes are, the same way the compiler's -cp does. --scan-classpath says to look through every folder and jar on that path for classes with tests. --disable-ansi-colors keeps the escape codes out of the output, so a page can show the report as text.

A run can name one class instead. Replace --scan-classpath with --select-class GreeterTest and the launcher runs that class only, even when the folder holds several test classes. The next lessons use both forms: scanning while a project is small, selecting when a run is about one class.

Exercises

  1. Save the test class in a file named Test.java and compile. Copy the first line of the error into your notes.
  2. Remove the jar from -cp and compile again. Which three symbols does the compiler fail to find?
  3. Add a third test, greetsAnEmptyName, that expects Hello, !. Does it pass with the current Greeter?
  4. Run the launcher with --select-class GreeterTest instead of --scan-classpath. What changes in the report?

Questions

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

  1. Which file contains the assertions?

    Answer

    The test class

    The test class imports the assertions and checks what the class under test returns; the class under test stays free of JUnit.

  2. Why does javac need the launcher jar on its class path?

    Answer

    The test class imports JUnit types that the compiler must resolve

    The imports of org.junit.jupiter are resolved from the jar during compilation.

  3. What does --scan-classpath tell the launcher to do?

    Answer

    Look through the class path for classes with tests

    The launcher walks the folder and the jars on the class path and discovers test classes.

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

    Answer

    Hello, Ada!

    The three strings are joined in order, and the space after the comma is part of the first string.

  5. What does this program print? public class Q2 { static int twice(int n) { return n + n; } public static void main(String[] args) { System.out.println(twice(3)); } }

    Answer

    6

    twice returns 3 + 3, and println prints the number.

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

    Answer

    6

    The loop runs for 1, 2 and 3 and stops when n becomes 4, so the total is 6.

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

    Answer

    TEST

    toUpperCase returns a new string with every letter in upper case.

  8. A public class named GreeterTest is saved in Helpers.java. What does javac report?

    Answer

    class GreeterTest is public, should be declared in a file named GreeterTest.java

    A public class must be in a file named exactly after it; the compiler checks the name before the body.

  9. Which two files does a single test of Greeter.greet need?

    Answer

    Greeter.java and GreeterTest.java

    The class under test and the test class are two classes, and the compiler reads both.

  10. What does this program print? public class Q5 { public static void main(String[] args) { System.out.println(Greeter.greet("Ada")); } } class Greeter { static String greet(String name) { return "Hi " + name; } }

    Answer

    Hi Ada

    The class in the same file returns Hi and the name, and println prints that string.

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