Tags and filtering
A suite of tests is often run in more than one shape: the fast ones before every commit, the slow ones before a release, the integration ones when a service is up. JUnit calls those groups tags. A tag is a string on a class or a method, and the launcher can include or exclude it without a second build.
@Tag
@Tag("fast") on a class tags every test in it; on a method it tags that one. A test may have several tags. Tags are plain strings, and the launcher accepts a comma-separated list for include and exclude. The same classes are compiled once and filtered at run time.
Two classes, two tags
FastTest.java is tagged fast and has one test. SlowTest.java is tagged slow and has one test. Both are built by the same command; the difference is the filter on the run.
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
@Tag("fast")
public class FastTest {
@Test
void adds() {
assertEquals(4, 2 + 2);
}
}
Include one tag
--include-tag fast runs only the tests that carry the tag. The launcher still scans the folder, finds both classes, and drops the slow one before it starts. The tree of the fast report has one class and one test.
javac -Xlint:all -cp /opt/java-tools/junit-platform-console-standalone.jar -d out FastTest.java SlowTest.java
junit execute --class-path out --scan-classpath --include-tag fast --disable-ansi-colors
Thanks for using JUnit! Support its development at https://junit.org/sponsoring
╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ FastTest ✔
│ └─ adds() ✔
└─ JUnit Vintage ✔
Test run finished after 602 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 ]
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
@Tag("slow")
public class SlowTest {
@Test
void halves() {
assertEquals(5, 10 / 2);
}
}
Exclude one tag
--exclude-tag fast is the other way to say the same thing: run everything except the fast tests. Here that leaves the slow one. The exclude form is the one for a release job that runs the slow tests and skips the quick ones it already ran, or for a local run that skips the tests which need a service.
junit execute --class-path out --scan-classpath --exclude-tag fast --disable-ansi-colors
Thanks for using JUnit! Support its development at https://junit.org/sponsoring
╷
├─ JUnit Platform Suite ✔
├─ JUnit Jupiter ✔
│ └─ SlowTest ✔
│ └─ halves() ✔
└─ JUnit Vintage ✔
Test run finished after 234 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 two reports
Both runs used the same compiled classes and the same folder; only the filter changed. The counts are one test each because each filter left one class. Without a filter the same run would find two tests, one in each class. The tree does not print the tag, so the report alone does not say why a class was left out; the command in the job log does.
Tag names
A tag is a string with no registry, so two teams can tag the same suite fast and quick and get two filters that never meet. Keep the names short, lower case and few, and write them down: fast, slow, integration cover most projects. A tag is not a display name and does not appear in the tree.
Exercises
- Run without a filter and check that the report has two tests.
- Add a second tag to SlowTest and include it. Which tests run?
- Put @Tag("fast") on one method of a second class and include fast. Is the class line red or green when one method is filtered out?
- Pass a tag that no test has and read the counts. Is the run green?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Where can
@Tagbe placed?Answer
On a class or on a test method
A class tag applies to every test in it; a method tag applies to that test.
-
What does
--include-tag fastdo?Answer
Runs only the tests tagged fast
Include keeps the matching tests and drops the rest before they start.
-
Do tags change the compiled class files?
Answer
No; the classes are compiled once and filtered at run time
A tag is an annotation read by the launcher; the compiled classes are the same.
-
What does this program print?
public class Q1 { public static void main(String[] args) { String tag = "fast"; System.out.println(tag.length()); } }Answer
4
The word fast has four characters.
-
What does this program print?
public class Q2 { public static void main(String[] args) { System.out.println("slow".equals("slow")); } }Answer
true
The two strings have the same characters, so equals is true.
-
What does this program print?
public class Q3 { public static void main(String[] args) { System.out.println(2 + 2); } }Answer
4
The two integers are added, and println prints 4.
-
What does this program print?
public class Q4 { public static void main(String[] args) { System.out.println(10 / 2); } }Answer
5
Ten divided by two is five.
-
Why does the report not show a tag?
Answer
The tree shows the class and method names, not the annotations
The report is about tests and outcomes; the tag is part of the command that selected them.
-
What happens when no test has the included tag?
Answer
The run finds no tests and returns 0
A filter that matches nothing leaves an empty run, which is green but silent.
-
What does this program print?
public class Q5 { public static void main(String[] args) { System.out.println("integration".startsWith("int")); } }Answer
true
The word begins with int, so startsWith is true.
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