JUnit 5 Test Suites

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.

JUnit 5 Test Suite Project Structure
JUnit 5 Test Suite 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
{
}
@SelectPackages - Single Package Example
@SelectPackages – Single Package Example

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
{
}
@SelectPackages - Multiple Packages Example
@SelectPackages – Multiple Packages Example

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
{
}
@SelectClasses - Single Class Example
@SelectClasses – Single Class Example

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
{
}
@SelectClasses - Multiple Test Classes Example
@SelectClasses – Multiple Test Classes Example

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 !!

Sourcecode Download

Was this post helpful?

Join 7000+ Awesome Developers

Get the latest updates from industry, awesome resources, blog updates and much more.

* We do not spam !!

14 thoughts on “JUnit 5 Test Suites”

  1. 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

    Reply
  2. 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!

    Reply
  3. 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.

    Reply
  4. 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.

    Reply
  5. Hello,

    The test suites are executed only in Junit 4 runner. How is it possible to make it in runner junit 5

    Reply
  6. 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

    Reply
  7. 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!

    Reply

Leave a Comment

HowToDoInJava

A blog about Java and related technologies, the best practices, algorithms, and interview questions.