JUnit 5 test suites are written with @Suite annotation. Suites help us run the tests spread into multiple classes and packages.
We can use Include and Exclude annotations (discussed later in this tutorial) for filtering test packages, test classes or even test methods.
@RunWith(JUnitPlatform.class)has been deprecated in favor of@Suite
annotation and will be removed in JUnit Platform 2.0.
1. Project Structure and Maven Dependency
For this example, we are using the below project structure.

To run the suites, include junit-platform-suite-engine dependency (version 1.8 or later).
<dependency>
<groupId>org.junit.platform</groupId>
<artifactId>junit-platform-suite-engine</artifactId>
<version>1.8.1</version>
</dependency>
2. Creating Test Suites
2.1. @Suite
Creating suites is easy. Just add the @Suite
annotation of a class and start including or excluding the test classes and methods into the suite.
When we want to run the suite, simply run it as a normal JUnit test class and it will execute all the included tests in the suite.
import org.junit.platform.suite.api.IncludeTags;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.platform.suite.api.Suite;
@SelectPackages({"com.howtodoinjava.junit5.examples.packageA"
,"com.howtodoinjava.junit5.examples.packageB"})
@IncludeTags("production")
@Suite
public class JUnit5TestSuiteExample {
}
3.2. @SuiteDisplayName
Use this annotation to give a display name for the annotated test class that is executed as a test suite on the JUnit Platform.
Display names are typically used for test reporting in IDEs and build tools and may contain spaces, special characters, and even emoji.
@IncludeTags("production")
@Suite
@SuiteDisplayName("A demo Test Suite")
public class JUnit5TestSuiteExample {
}
3. Including and Excluding Tests
JUnit 5 provides the following annotations to include or exclude the tests in the suites.
- @SelectClasses
- @SelectPackages
- @IncludePackages
- @ExcludePackages
- @IncludeClassNamePatterns
- @ExcludeClassNamePatterns
- @IncludeTags
- @ExcludeTags
Let’s learn about these annotations in detail.
3.1. @SelectPackages
@SelectPackages
specifies the names of packages to select when running a test suite via @RunWith(JUnitPlatform.class)
.
3.1.1. Specify Single Package
Pass “packageName” as parameter to @SelectPackages
annotation.
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples.packageA")
public class JUnit5TestSuiteExample
{
}

3.1.2. Specify Multiple Packages
Pass package names in the parameter as a string array (inside curly braces {}
) to @SelectPackages
annotation.
@Suite
@SelectPackages({"com.howtodoinjava.junit5.examples.packageA",
"com.howtodoinjava.junit5.examples.packageB"})
public class JUnit5TestSuiteExample
{
}

Please note that if we pass ‘com.demo.app’ in
@SelectPackages
annotation, then test classes present in the package ‘com.demo.app’ AND all it’s sub-packages will be selected for test suite.
3.2. @SelectClasses
@SelectClasses
specifies the classes to select when running a test suite via @RunWith(JUnitPlatform.class)
.
3.2.1. Specify Single Test Class
Pass ClassName.class
as parameter to @SelectClasses
annotation.
@Suite
@SelectClasses( ClassATest.class )
public class JUnit5TestSuiteExample
{
}

3.2.2. Specify Multiple Test Classes
Pass class names in the parameter as array (inside curly braces {}
) to @SelectClasses
annotation.
@Suite
@SelectClasses( { ClassATest.class, ClassBTest.class, ClassCTest.class } )
public class JUnit5TestSuiteExample
{
}

3.3. @IncludePackages and @ExcludePackages
As we learn that @SelectPackages
causes all its sub-packages as well to be scanned for test classes.
If you want to exclude any specific package or include any package then you may use @IncludePackages and @ExcludePackages annotations.
3.3.1. @IncludePackages Example
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples")
@IncludePackages("com.howtodoinjava.junit5.examples.packageC")
public class JUnit5TestSuiteExample
{
}
This will add tests from test classes in com.howtodoinjava.junit5.examples.packageC
only i.e. ClassCTest
.
3.3.2. @ExcludePackages Example
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples")
@ExcludePackages("com.howtodoinjava.junit5.examples.packageC")
public class JUnit5TestSuiteExample
{
}
This will add tests from test classes in com.howtodoinjava.junit5.examples
but exclude all test classes from sub-package com.howtodoinjava.junit5.examples.packageC
i.e. ClassATest
and ClassBTest
.
3.4. @IncludeClassNamePatterns and @ExcludeClassNamePatterns
Many times it is not feasible to include all packages or test class names in select annotations. In that case, you may give a broader package scope and apply filtering on which test classes to be included or excluded from the suite.
To specify test class names patterns to exclude or include, you can use @IncludeClassNamePatterns and @ExcludeClassNamePatterns annotations.
3.4.1. @IncludeClassNamePatterns Example
Include all test classes with names ending with ATest
or ATests
.
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples")
@IncludeClassNamePatterns({"^.*ATests?$"})
public class JUnit5TestSuiteExample
{
}
3.4.2. @ExcludeClassNamePatterns Example
Exclude all test classes with names ending with ATest
or ATests
.
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples")
@ExcludeClassNamePatterns({"^.*ATests?$"})
public class JUnit5TestSuiteExample
{
}
You may apply more than one pattern in above annotations. In case of multiple patterns, they are combined using
OR
semantics.It means that if fully qualified name of a class matches against at least one of the patterns, the class will be included/excluded from the test suite.
3.5. @IncludeTags and @ExcludeTags
In enterprise applications, you may have tagged test cases that you want to run in specific environments e.g. development or production. You can include or exclude tests based on these tags as well, from a test suite.
3.5.1. @IncludeTags Example
This test suite will run all tests tagged with production
inside package com.howtodoinjava.junit5.examples
(and its sub-packages).
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples")
@IncludeTags("production")
public class JUnit5TestSuiteExample
{
}
3.5.2. @ExcludeTags Example
This test suite will exclude all tests tagged with development
inside package com.howtodoinjava.junit5.examples
(and it’s sub-packages).
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples")
@ExcludeTags("development")
public class JUnit5TestSuiteExample
{
}
Clearly, there are multiple ways to create test suites in JUnit 5 and it has strong support for filtering tests to/from test suites.
4. Running a Single Test Suite
By default mvn test
will run all the tests and suites in the application.
Use Maven surefire plugin’s configuration
and test
elements to include the test suites and classes in the test execution. In the following example, we are executing a single suite TempDirectoryTestSuite.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0-M7</version>
<configuration>
<test>com.howtodoinjava.junit5.examples.suites.TempDirectoryTestSuite</test>
</configuration>
</plugin>
I tried to run the above suite from command line using the JVM system property
test
, but it was executing all the tests and suite in the application. Let me know if it works for you.
If we want to exclude few tests classes and suites, we can use the exclude tag.
<configuration>
<excludes>
<exclude>some test to exclude here</exclude>
</excludes>
</configuration>
Happy Learning !!
Comments