Junit 5 @Tag and Filtering tagged tests with Examples

In this article we will see how to tag test cases using Junit 5 @Tag, rules for declare @Tag for the tests, how to discover or filter the tagged tests to execute tagged test cases with several examples.

1. Junit 5 @Tag

Test classes and methods can be tagged in the JUnit 5 using @Tag annotation, those tags can later be used to filter test discovery and execution.

1.1. Rules to create Tags

The label for tagging tests should meet the following syntax rules.

1. A tag must not be null or blank.
2. A trimmed ( leading and trailing white space characters have been removed ) tag must not contain white space.
3. A trimmed tag must not contain ISO control characters.
4. A trimmed @Tag must not contain any of the following reserved characters. comma(,), left parenthesis((), right parenthesis ()), ampersand (&), vertical bar (|), exclamation (!).

1.2. Junit 5 Tagging tests

Following example shows you how to create Junit 5 @Tag at class level and test method level.

@Tags(value = 
 {@Tag("regression"),
  @Tag("user_module")
 })
public class Junit5_Tag_Test {
	
	@Tag("acceptance")
	@Test
	void acceptance_test1() {
		System.out.println("acceptance_test1()");
	}
	
	@Tag("acceptance")
	@Test
	void acceptance_test2() {
		System.out.println("acceptance_test2()");
	}

	@Tag("accessability")
	@Test
	void accessability_test1() {
		System.out.println("accessability_test1()");
	}
	
	@Tag("security")
	@Test
	void security_test1() {
		System.out.println("security_test1()");
	}
	
	@Tag("api")
	@Test
	void api_test1() {
		System.out.println("api_test1()");
	}
	
	@Tag("api")
	@Test
	void api_test2() {
		System.out.println("api_test2()");
	}
	
	@Tag("load")
	@Test
	void load_test1() {
		System.out.println("load_test1()");
	}
	
	@Tag("performance")
	@Test
	void performance_test1() {
		System.out.println("performance_test1()");
	}
}

2. Creating your own custom tag annotation

2.1. For example if you are using same tag @Tag("performance") or combination with @Tag("api") in several tests, instead of copying and pasting @Tag("performance"), @Tag("api") throughout your code base, you can create a custom composed annotation named @PerformanceApiTag as follows. @PerformanceApiTag can then be used instead using 2 annotations every time.

Following example shows you how to create custom tag annotation for  @Tag("performance"), @Tag("api") .

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Tag("api") @Tag("performance")
@Test
public @interface PerformanceApiTag {

}

2.2. Using custom tag annotation to the tests

@Tags(value = 
 {@Tag("regression"),
  @Tag("payment_module")
 })
public class Junit5_CustomTag_Test {
	
	@Tag("accessability")
	@Test
	void api_test1() {
		System.out.println("api_test1()");
	}
	
	@PerformanceApiTag
	@Test
	void performance_api_test1() {
		System.out.println("performance_api_test1()");
	}
	
	@Tag("load")
	@Test
	void load_test1() {
		System.out.println("load_test1()");
	}
	
	@PerformanceApiTag
	@Test
	void performance_api_test2() {
		System.out.println("performance_api_test2()");
	}
}

3. Junit 5 Filter Or discover and execute tagged tests

3.1. Maven filtering Junit 5 @Tag tests using surefire plugin

You can use JUnit5 Tags and filter tests by tags or tag expressions. If you would like to run your tests along with your build you can configure the following parameters in surefire plugin, then issue command mvn test.

1. To include tags or tag expressions, use groups.
2. To exclude tags or tag expressions, use excludedGroups.

<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>${maven-surefire-plugin.version}</version>
				<configuration>
				    <!-- Include tags -->
					<groups>performance | api</groups>
					<!-- Exclude tags -->
					<excludedGroups>load, acceptance</excludedGroups>
				</configuration>
			</plugin>

3.2. Running your test from console.

# Run tests which tagged with `load` and exclude tagged with `api`
 mvn test -Dgroups="load" -DexcludedGroups="api" 

# Run tests which tagged with `api` or  `performance`
 mvn test -Dgroups="api | performance" 

# Run tests which tagged both `api` and  `performance`
 mvn test -Dgroups="api & performance" 

4. Tag Expression

Tag expressions are boolean expressions with the operators !, & and |. In addition, ( and ) can be used to adjust for operator precedence. If you are tagging your tests across multiple dimensions, tag expressions help you to select which tests to execute.

Following are Tag expressions supported by Junit 5.

1. ! – to exclude tagged tests from execution. Example: mvn test -Dgroups="!api" excludes “api” tests.
2. & – to include where intersected 2 or more tagged tests from execution. Example: mvn test -Dgroups="api & performance" includes only if tagged “api” and “performance” both for the tests.
3. | – to include all the tagged tests from execution. Example: mvn test -Dgroups="load | api" includes both “load” tests and “api” tests in the execution.

Another example for Tag Expressions :

mvn test -Dgroups="(api | load) & (accessibility | performance)" – to run tagged with “api” or “load” and “accessibility” or “performance” tests.

Conclusion

In this article we have seen how to tag test cases using Junit 5 @Tag, rules for declare @Tag for the tests, how to discover or filter the tagged tests to execute tagged test cases with several examples.

You also might be interested in following examples :

1. Junit 5 Dynamic Tests and @TestFactory annotation.
2. Junit 5 run tag-specific test via gradle command.
3. Junit 5 Timeout tests, fail tests if not completed within time.
4. Junit 5 Repeated tests and display Repetition info.
5. Junit 5 parameterized tests with different argument sources.
6. Creating a Custom ParameterResolver and built in Junit 5 Parameter Resolvers.