JUnit 5 Test Suites Examples

Using JUnit 5 test suites, you can run tests spread into multiple test classes and different packages. JUnit 5 provides two annotations: @SelectPackages and @SelectClasses to create test suites. Additionally, you can use other annotations for filtering test packages, classes or even test methods.

Table of Contents

Project Structure for Test classes and Suite
Create Test Suite with JUnit 5 @SelectPackages
Create Test Suite with JUnit 5 @SelectClasses
Filtering Packages with @IncludePackages and @ExcludePackages
Filtering Test Classes with @IncludeClassNamePatterns and @ExcludeClassNamePatterns
Filtering Tests with @IncludeTags and @ExcludeTags

1. Project Structure for Test classes and Suite

For this example, I am using below project structure.

2. Create Test Suite with @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.

@RunWith(JUnitPlatform.class)
@SelectPackages("com.howtodoinjava.junit5.examples.packageA") 
public class JUnit5TestSuiteExample 
{
}

Specify Multiple Packages

Pass package names in parameter as string array (inside curly braces {}) to @SelectPackages annotation.

@RunWith(JUnitPlatform.class)
@SelectPackages({"com.howtodoinjava.junit5.examples.packageA","com.howtodoinjava.junit5.examples.packageB"}) 
public class JUnit5TestSuiteExample 
{
}

3. Create Test Suite with @SelectClasses

@SelectClasses specifies the classes to select when running a test suite via @RunWith(JUnitPlatform.class).

Specify Single Class

Pass ClassName.class as parameter to @SelectClasses annotation.

@RunWith(JUnitPlatform.class)
@SelectClasses( ClassATest.class )
public class JUnit5TestSuiteExample 
{
}

Specify Multiple Classes

Pass class names in parameter as array (inside curly braces {}) to @SelectClasses annotation.

@RunWith(JUnitPlatform.class)
@SelectClasses( { ClassATest.class, ClassBTest.class, ClassCTest.class } )
public class JUnit5TestSuiteExample 
{
}

4. @IncludePackages and @ExcludePackages

As we learn that @SelectPackages causes all it’s sub-packages as well to be scanned for test classes. If you want to exclude any specific sub-package, or include any package then you may use @IncludePackages and @ExcludePackages annotations.

@IncludePackages Example

@RunWith(JUnitPlatform.class)
@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

@RunWith(JUnitPlatform.class)
@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.

5. @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 appy filtering on which test classes to be included or excluded from 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 name ending with ATest or ATests.

@RunWith(JUnitPlatform.class)
@SelectPackages("com.howtodoinjava.junit5.examples")
@IncludeClassNamePatterns({"^.*ATests?$"})
public class JUnit5TestSuiteExample 
{
}

@ExcludeClassNamePatterns Example

Exclude all test classes with name ending with ATest or ATests.

@RunWith(JUnitPlatform.class)
@SelectPackages("com.howtodoinjava.junit5.examples")
@ExcludeClassNamePatterns({"^.*ATests?$"})
public class JUnit5TestSuiteExample 
{
}

6. @IncludeTags and @ExcludeTags

In enterprise applications, you may have tagged test cases which 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 it’s sub-packages).

@RunWith(JUnitPlatform.class)
@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).

@RunWith(JUnitPlatform.class)
@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 a strong support for filtering tests to/from test suites.

Drop me your questions in comments section.

Happy Learning !!