1. Overview
It’s very common to execute all our JUnits automatically as a part of the CI build using Maven. This, however, is often time-consuming.
Therefore, we often want to filter our tests and execute either unit tests or integration tests or both at various stages of the build process.
In this tutorial, we’ll look at a few filtering techniques for test cases with JUnit5. In the following sections, we’ll also look at various filtering mechanisms before JUnit5.
2. JUnit5 Tags
2.1. Annotating JUnits with Tag
With JUnit5 we can filter JUnits by tagging a subset of them under a unique tag name. For example, suppose we have both unit tests and integration tests implemented using JUnit5. We can add tags on both sets of test cases:
@Test
@Tag("IntegrationTest")
public void testAddEmployeeUsingSimpelJdbcInsert() {
}
@Test
@Tag("UnitTest")
public void givenNumberOfEmployeeWhenCountEmployeeThenCountMatch() {
}
Henceforth we can execute all JUnits under a particular tag name separately. We can also tag the class instead of methods. Thereby including all tests in a class under a tag.
In the next few sections, we’ll see various ways of filtering and executing the tagged JUnits.
2.2. Filtering Tags with Test Suite
JUnit5 allows us to implement test suites through which we can execute tagged test cases:
@RunWith(JUnitPlatform.class)
@SelectPackages("com.baeldung.tags")
@IncludeTags("UnitTest")
public class EmployeeDAOUnitTestSuite {
}
Now, if we run this suite, all JUnits under the tag UnitTest would be executed. Similarly, we can exclude JUnits with ExcludeTags annotation.
2.3. Filtering Tags with Maven Surefire Plugin
For filtering JUnits within the various phases of the Maven build, we can use the Maven Surefire plugin. The Surefire plugin allows us to include or exclude the tags in the plugin configuration:
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20.1</version>
<configuration>
<groups>UnitTest</groups>
</configuration>
</plugin>
If we now execute this plugin, it will execute all JUnits which are tagged as UnitTest. Similarly, we can exclude test cases under a tag name:
<excludedGroups>IntegrationTest</excludedGroups>
2.4. Filtering Tags with an IDE
IDEs now allow filtering the JUnits by tags. This way we can execute a specific set of tagged JUnits directly from our IDE.
IntelliJ allows such filtering through a custom Run/Debug Configuration:
As shown in this image, we selected the Test Kind as tags and the tag to be executed in the Tag Expression.
JUnit5 allows various Tag Expressions which can be used to filter the tags. For example, to run everything but the integration tests, we could use !IntegrationTest as the Tag Expression. Or for executing both UnitTest and IntegrationTest, we can use UnitTest | IntegrationTest.
Similarly, Eclipse also allows including or excluding tags in the JUnit Run/Debug configurations:
3. JUnit4 Categories
3.1. Categorizing JUnits
JUnit4 allows us to execute a subset of JUnit tests by adding them into different categories. As a result, we can execute the test cases in a particular category while excluding other categories.
We can create as many categories by implementing marker interfaces where the name of the marker interface represents the name of the category. For our example, we’ll implement two categories, UnitTest:
public interface UnitTest {
}
and IntegrationTest:
public interface IntegrationTest {
}
Now, we can categorize our JUnit by annotating it with Category annotation:
@Test
@Category(IntegrationTest.class)
public void testAddEmployeeUsingSimpelJdbcInsert() {
}
@Test
@Category(UnitTest.class)
public void givenNumberOfEmployeeWhenCountEmployeeThenCountMatch() {
}
In our example, we put the Category annotation on the test methods. Similarly, we can also add this annotation on the test class, thus adding all tests into one category.
3.2. Categories Runner
In order to execute JUnits in a category, we need to implement a test suite class:
@RunWith(Categories.class)
@IncludeCategory(UnitTest.class)
@SuiteClasses(EmployeeDAOCategoryIntegrationTest.class)
public class EmployeeDAOUnitTestSuite {
}
This test suite can be executed from an IDE and would execute all JUnits under the UnitTest category. Similarly, we can also exclude a category of JUnits in the suite:
@RunWith(Categories.class)
@ExcludeCategory(IntegrationTest.class)
@SuiteClasses(EmployeeDAOCategoryIntegrationTest.class)
public class EmployeeDAOUnitTestSuite {
}
3.3. Excluding or Including Categories in Maven
Finally, we can also include or exclude the categories of JUnit tests from the Maven build. Thus, we can execute different categories of JUnit tests in different Maven profiles.
We’ll use the Maven Surefire plugin for this:
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20.1</version>
<configuration>
<groups>com.baeldung.categories.UnitTest</groups>
</configuration>
</plugin>
And similarly we can exclude a category from the Maven build:
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20.1</version>
<configuration>
<excludedGroups>com.baeldung.categories.IntegrationTest</excludedGroups>
</configuration>
</plugin>
This is similar to the example we discussed in the previous section. The only difference is that we replaced the tag name with the fully qualified name of the Category implementation.
4. Filtering JUnits with Maven Surefire Plugin
Both of the approaches we’ve discussed have been implemented with the JUnit library. An implementation agnostic way of filtering test cases is by following a naming convention. For our example, we’ll use UnitTest suffix for unit tests and IntegrationTest for integration tests.
Now we’ll use the Maven Surefire Plugin for executing either the unit tests or the integrations tests:
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20.1</version>
<configuration>
<excludes>
**/*IntegrationTest.java
</excludes>
</configuration>
</plugin>
The excludes tag here filters all integration tests and executes only the unit tests. Such a configuration would save a considerable amount of build time.
Furthermore, we can execute the Surefire plugin within various Maven profiles with different exclusions or inclusions.
Although Surefire works well for filtering, it is recommended to use the Failsafe Plugin for executing integration tests in Maven.
5. Conclusion
In this article, we saw a way to tag and filter test cases with JUnit5. We used the Tag annotation and also saw various ways for filtering the JUnits with a specific tag through the IDE or in the build process using Maven.
We also discussed some of the filtering mechanisms before JUnit5.
All examples are available at Github.