JUnit @Tag + Filter with Maven

By Arvind Rai, May 08, 2021

On this page we will learn using @Tag annotation in our JUnit tests. We will also learn filtering test classes and test methods using tags with Maven.
1. JUnit @Tag annotation is introduced in JUnit 5.
2. A @Tag is used at test class level as well as test method level.
3. We need to pass a tag name to @Tag annotation. Tag names are used to filter which tests are included or excluded for a given test plan.
4. The @Tag is repeatable annotation. It means we can use @Tag more than one time at method level as well as class level.
5. Tag name should not contain white spaces. Tag name should not contain ISO control characters and reserved characters such as comma, left parenthesis, right parenthesis, ampersand, vertical bar, exclamation point.
6. Tags can be filtered using build file such as Maven and Gradle. IDE can also be used to filter tags while running JUnit tests.

Technologies Used
Using @Tag Annotation
Filter with Maven
References
Download Source Code

Technologies Used

Find the technologies being used in our example.
1. Java 14
2. JUnit 5.7.1
3. Maven 3.8.1

Using @Tag Annotation

Find the examples to use @Tag annotation.
Example-1:
MyAppTest1.java

public class MyAppTest1 {
  @Tag("feature2")
  @Test
  void additionTest() {
	int sum = 50 + 60;
	assertEquals(110, sum);
  }
  @Tag("integration")
  @Tag("feature1")
  @Test
  void multiplyTest() {
	int multi = 15 * 5;
	assertEquals(75, multi);
  }  
}

Example-2:
MyAppTest2.java

@Tag("integration")
@Tag("acceptance")
public class MyAppTest2 {
  @Tag("feature1")
  @Test
  void additionTest() {
	int sum = 60 + 40;
	assertEquals(100, sum);
  }
  @Test
  void multiplyTest() {
	int multi = 20 * 5;
	assertEquals(100, multi);
  }  
}

Filter with Maven

1. Maven provides maven-surefire-plugin to execute the unit tests of an application. The reports are generated in *.txt and *.xml files. By default these reports are generated in below directory.

${basedir}/target/surefire-reports/

2. We can filter tests by tags or tag expressions. Here we will learn to filter test using Maven. In Maven,
a. To include tags or tag expressions, use <groups>
b. To exclude tags or tag expressions, use <excludedGroups>
Find the sample Maven code.
pom.xml

<properties>
	<maven.compiler.source>14</maven.compiler.source>
	<maven.compiler.target>14</maven.compiler.target>
</properties>
<dependencies>
	<dependency>
		<groupId>org.junit.jupiter</groupId>
		<artifactId>junit-jupiter-api</artifactId>
		<version>5.7.1</version>
		<scope>test</scope>
	</dependency>
</dependencies>
<build>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-surefire-plugin</artifactId>
			<version>3.0.0-M5</version>
			<configuration>
				<groups>integration | feature2</groups>
				<excludedGroups>feature1</excludedGroups>
			</configuration>
		</plugin>
	</plugins>
</build>

3. Tag expression can be created using ! , & , | . To adjust operator precedence, use ( and ). JUnit also supports two special expressions i.e. any() and none().
any(): Selects all tests with any tags at all.
none(): Selects all tests without any tags.
feature1 : Selects all tests for 'feature1'.
integration | feature2 : Selects all tests for 'integration ' plus all tests for 'feature2'.
integration & feature2 : Selects all tests for the intersection between 'integration' and 'feature2'.

4. We can run test files using Maven command as following.
a. Run only single test class, for ex. MyAppTest1