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
- Save the test class in a file named Test.java and compile. Copy the first line of the error into your notes.
- Remove the jar from -cp and compile again. Which three symbols does the compiler fail to find?
- Add a third test, greetsAnEmptyName, that expects Hello, !. Does it pass with the current Greeter?
- 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.
-
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.
-
Why does
javacneed 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.
-
What does
--scan-classpathtell 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.
-
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.
-
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.
-
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.
-
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.
-
A public class named
GreeterTestis saved inHelpers.java. What doesjavacreport?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.
-
Which two files does a single test of
Greeter.greetneed?Answer
Greeter.java and GreeterTest.java
The class under test and the test class are two classes, and the compiler reads both.
-
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