Creating a Test Suite With JUnit

1. Introduction

JUnit is one of the most popular testing frameworks for Java applications, with a powerful and flexible way to create automated unit tests. One of its features is the ability to create test suites, which allows us to group multiple tests.

In this tutorial, we’ll explore how to create test suites with JUnit. First, we’ll implement and run a simple test suite. After that, we’ll explore some configurations to include or exclude some tests.

2. Creating a Test Suite

As we know, a test suite is a collection of tests grouped together and run as a single unit. We use them to organize tests into logical groups, such as tests for a specific component or application feature. We can also easily execute tests in a particular order or run a subset of tests based on specific criteria.

JUnit 5 provides several ways to create a test suite. Before we start, we need to make sure that we include the junit-platform-suite dependency:

<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-suite</artifactId>
    <version>1.11.0-M1</version>
    <scope>test</scope>
</dependency>

The JUnit Platform Suite Engine is responsible for running a custom test suite using one or more test engines in JUnit. It also brings us additional APIs that we’ll use to create a test suite.

2.1. Using @Suite Annotation

The easiest way to implement a test suite is to use the @Suite class-level annotation, which is also the most recommended solution. This annotation has been available since the 1.8.0 version of the JUnit Platform.

Let’s prepare a JUnitTestSuite class:

@Suite
@SuiteDisplayName("My Test Suite")
public class JUnitTestSuite {
}

In this example, we used the @Suite annotation telling JUnit to mark this class as executable in a single unit. Moreover, we added an optional @SuiteDisplayName annotation and specified a custom title.

From now on, we can use this class to execute all tests configured in this suite in a single run by using our IDE or the maven-surefire-plugin. Note that for now, this suite doesn’t include any tests.

2.2. Using @RunWith Annotation

Alternatively, we can rewrite our test suite using the @RunWith annotation that uses the JUnit 4 Runners Model:

@RunWith(JUnitPlatform.class)
@SuiteDisplayName("My Test Suite")
public class JUnitRunWithSuite {
}

If we’re missing the JUnitPlafrom class, we need to include an additional dependency:

<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-runner</artifactId>
    <version>1.11.0-M1</version>
    <scope>test</scope>
</dependency>

As a result, this test suite works similarly to our previous one created via the @Suite annotation. This solution is recommended only for developers using earlier versions of JUnit. In addition, the JUnitPlatform runner has been deprecated since 1.8.0 in favor of the @Suite support and will be removed in future releases.

3. Including and Excluding Tests

For now, our test suite doesn’t contain any tests. The JUnit Platform Suite Engine provides multiple annotations to include or exclude tests in our test suites.

We can distinguish two main groups of annotations: @Select and @Include/@Exclude.

The @Select annotations specify the resources where JUnit should look for tests. Meanwhile, the @Include/@Exclude annotations specify additional conditions to include or exclude previously found tests.

These two annotations won’t work without the @Select annotation first. We can mix all the annotations to determine exactly which tests we want to run.

Now let’s take a look at some of them by configuring our test suite.

3.1. @SelectClasses

The most common way to select tests for our test suites is to specify test classes using the @SelectClasses annotation:

@Suite
@SelectClasses({ClassOneUnitTest.class, ClassTwoUnitTest.class})
public class JUnitSelectClassesSuite {
}

The test suite now executes all @Test marked methods from both classes.

3.2. @SelectPackages

Instead of specifying the list of classes, we can use @SelectPackages to provide packages for test scanning:

@Suite
@SelectPackages({"com.baeldung.testsuite", "com.baeldung.testsuitetwo"})
public class JUnitSelectPackagesSuite {
}

Notably, this annotation also executes all classes from sub-packages.

3.3. @IncludePackages and @ExcludePackages

For now, we know how to include all classes from the packages. To further specify whether to include or exclude packages, we can use @IncludePackages and @ExcludePackages annotations, respectively:

@Suite
@SelectPackages({"com.baeldung.testsuite")
@IncludePackages("com.baeldung.testsuite.subpackage")
public class JUnitTestIncludePackagesSuite {
}

The above configuration executes all tests found in com.baeldung.testsuite.subpackage packages only, ignoring other findings.

Let’s see how we can exclude a single package:

@Suite
@SelectPackages("com.baeldung.testsuite")
@ExcludePackages("com.baeldung.testsuite.subpackage")
public class JUnitExcludePackagesSuite {
}

Now, JUnit executes all tests found in the com.baeldung.testsuite package and its sub-packages, ignoring only the classes found in the com.baeldung.testsuite.subpackage.

3.4. @IncludeClassNamePatterns and @ExcludeClassNamePatterns

If we don’t want to specify inclusion rules using packages, we can use @IncludeClassNamePatterns and @ExcludeClassNamePatterns annotations and implement regex checking for class names:

@Suite
@SelectPackages("com.baeldung.testsuite")
@IncludeClassNamePatterns("com.baeldung.testsuite.Class.*UnitTest")
@ExcludeClassNamePatterns("com.baeldung.testsuite.ClassTwoUnitTest")
public class JUnitClassNamePatternsSuite {
}

This example includes all tests found in the com.baeldung.testsuite package without its sub-packages. The class name must match the Class.*UnitTest regex pattern, like ClassOneUnitTest and ClassThreeUnitTest.

In addition, we also strictly excluded the ClassTwoUnitTest name, which will fulfill the first condition. As we know, in Java, the full class name also includes its package. This should also be taken into account when defining the patterns.

3.5. @IncludeTags and @ExcludeTags

As we know, in JUnit, we can mark classes and methods via the @Tag annotation. This’s an easy way to filter our tests with simple values. We can use the same mechanism when defining our test cases, using @IncludeTags and @ExcludeTags to run tests with specified @Tag:

@Suite
@SelectPackages("com.baeldung.testsuite")
@IncludeTags("slow")
public class JUnitTestIncludeTagsSuite {
}

This test suite will scan the com.baeldung.testsuite package and all sub-packages, running only tests annotated with the @Tag(“slow”).

Let’s now reverse the configuration:

@Suite
@SelectPackages("com.baeldung.testsuite")
@ExcludeTags("slow")
public class JUnitTestExcludeTagsSuite {
}

In this example, JUnit runs all tests without the @Tag(“slow”) annotation, including not tagged tests.

It’s worth noting that in JUnit, we can also tag a single method inside a test class. Using @IncludeTags and @ExcludeTags also allows us to include individual methods from classes, unlike the previous annotations.

3.6. @SelectMethod

Sometimes, we need to filter test methods by name in our test suites. We can use the @SelectMethod annotation to address this challenge.

Let’s see how we can select a single method:

@Suite
@SuiteDisplayName("My Test Suite")
@SelectMethod(type = ClassOneUnitTest.class, name = "whenFalse_thenFalse")
@SelectMethod("com.baeldung.testsuite.subpackage.ClassTwoUnitTest#whenFalse_thenFalse")
public class JUnitSelectMethodsSuite {
    // runs ClassOneUnitTest and ClassTwoUnitTest
}

We can select the class and method by using the type and name attributes. The type attribute specifies the class containing the test methods. The name attribute specifies the name of the test method to run within the class.

In addition, we can specify the fully qualified name of the test class and the name of the test method with ‘#’ as the delimiter.

In the above example, our test suite includes the method whenFalse_thenFalse() from the ClassOneUnitTest and ClassTwoUnitTest classes, so just the selected method from these classes will be executed when we run the suite.

4. Conclusion

JUnit provides an easy way to create automated tests, including the ability to create test suites. We can use test suites to organize our tests into logical groups, run a set of tests in a specific order, or run a subset of tests based on specific criteria.

In this article, we discussed two ways to implement a test suite, both via @Suite and @RunWith API. We then explored some additional annotations and checked how we could select tests for our test suites. Finally, we modified the list of selected tests by including and excluding them depending on various conditions.