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)
.
Specify Single Package
Pass “packageName” as parameter to @SelectPackages
annotation.
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples.packageA")
public class JUnit5TestSuiteExample
{
}

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)
.
Specify Single Test Class
Pass ClassName.class
as parameter to @SelectClasses
annotation.
@Suite
@SelectClasses( ClassATest.class )
public class JUnit5TestSuiteExample
{
}

Specify Multiple Test Classes
Pass class names in 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.
@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
.
@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.
@IncludeClassNamePatterns Example
Include all test classes with names ending with ATest
or ATests
.
@Suite
@SelectPackages("com.howtodoinjava.junit5.examples")
@IncludeClassNamePatterns({"^.*ATests?$"})
public class JUnit5TestSuiteExample
{
}
@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.
@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
{
}
@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.
Happy Learning !!
Thanks for the post it is very usefull
I have 4 test suits and during execution I want to provide the option of which file to run. when I give the below command no test case is run. can you please help
my pom file is
**/FastTestSuite.class
</properties
org.apache.maven.plugins
maven-surefire-plugin
${runSuite}
execution command :vn clean install test -Dtest=suit1.class -DfailIfNoTests=false
Hello,
Thanks for your great sharing!
Q1: If I have multiple test suites class(ex: one for regression Test, another for Smoke test), how would I go about executing specific one from a script ?
Q2 In Jenkins Job, how to configure certain(different) suites to run different cases?
Thanks!
Can you tell what maven modules and which version you are using for this examples?
Please refer to link.
This is using the JUnit 4 runner in order to execute Junit 5 Tests. The title is extremely misleading. It would suggest that you are able to run suites without JUnit4, solely using Junit5.
When these tutorials were written, IDEs didn’t have junit 5 support. But you can run same test code with Junit 5 runner, without any modification.
Did you ever run it with JUnit5?
Because print screens are of JUnit4 runner.
So would be great if you change the header of this tutorial or provide an example with JUnit5.
When I wrote these tutorials, eclipse did not have Junit support so they are like this. Thanks for reminding, I will update them.
Hello,
The test suites are executed only in Junit 4 runner. How is it possible to make it in runner junit 5
I think he didn’t even try his own code. Just copy pasted it from another source code. This code won’t work in JUnit5!
🙂
Junit 5 is backward compitable.
No, it’s not. That’s the purpose of vintage.
Hello, how are you?
I studing JUnit5 now and in my examples, the annotations @SelectClasses and @SelectPackages are only for JUnit Vintage, with is the same of JUnit4.
If you want, put in the article’s begining an observtion to no make some confusion to your readers.
Thanks
If I have multiple test suites, how would I go about executing specific ones from a script or from a gradle task? In one job/task, I may only want one of my test suites to run, while in others, I may want different ones to run or want to exclude certain suites. Thanks!