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.
- A tag must not be
null
or blank. - A trimmed ( leading and trailing white space characters have been removed ) tag must not contain white space.
- A trimmed tag must not contain ISO control characters.
- 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
.
- To include
tags
ortag expressions
, usegroups
. - To exclude
tags
ortag expressions
, useexcludedGroups
.
<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.
!
– to exclude tagged tests from execution. Example:mvn test -Dgroups="!api"
excludes “api” tests.&
– 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.|
– 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 can download source code from our github repository.
You also might be interested in following examples :
- Junit 5 Dynamic Tests
- Junit 5 run tag-specific test via gradle command
- Junit 5 Timeout
- Junit 5 Repeated tests
- Junit 5 parameterized test
- JUnit 5 ParameterResolver