How to tag and filter JUnit5 tests – @Tag

HOME

This tutorial explains to run the specific tests in JUnit5 using @Tag annotation. Imagine, there are 500 test cases for different functionalities. Out of 500 test cases, 350 tests are related to Integration test and rest 150 are for E2E test. We want to run only Integration tests. How this can be achieved? To overcome this problem, JUnit5 provides a filtering mechanism – @Tag annotation. We can apply the @Tag annotation on a test class or test method or both.

The JUnit Platform enforces the following rules for Tag:

  • A tag must not be null or blank.
  • A trimmed tag must not contain whitespace.
  • 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 point

Annotating JUnit Test Class with Tag

Scenario 1 – Apply @Tag on the test class. It will run all the tests present within this test class.

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

@Tag("Sprint-5")
class JUnit5TagsTests {

    @Test
    void test_Addition() {
        System.out.println("test_Add()");
        assertEquals(18, 3 + 7 + 8);
    }

    @Test
    void test_Subtraction() {
        System.out.println("test_Subtraction()");
        assertEquals(18, 26 - 8);
    }

    @Test
    void test_Calculator() {
        System.out.println("test_Calculator()");
        assertEquals(18, 10 + 8);
        assertEquals(2, 10 - 8);
    }

    @Test
    void test_Functions() {
        System.out.println("test_Functions()");
        assertEquals(8, Math.sqrt(64));
        assertEquals(64, Math.pow(8,2));
    }

    @Test
    void test_IsEven() {
        System.out.println("test_IsEven()");
        assertEquals(0, 16%2);
    }

}

Let us say we a number of classes and we want to execute only this specific test class that is tagged as – @Sprint-5.

Go to the command line or in case of IntelliJ to the terminal.

mvn clean test -Dgroups="Sprint-5"

The result of the above program is

Annotating JUnit Test Methods with Tag

With JUnit 5 we can filter tests by tagging a subset of them under a unique tag name.

Scenario 2 – Let’s say we have 5 tests and we want to run 3 tests in the development environment, 1 test in both development and QA, 1 test in Production and 1 test In-Progress. So we will tag the tests as below:

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;

class JUnit5TagsTests {

    @Test
    @Tag("Development")
    void test1() {
        System.out.println("This test is for Development");
    }

    @Test
    @Tag("Development")
    void test2() {
        System.out.println("This test is for Development");
    }

    @Test
    @Tag("Development")
    @Tag("QA")
    void test3() {
        System.out.println("This test is for Development & QA");
    }

    @Test
    @Tag("Production")
    void test4() {
        System.out.println("This test is for Production");
    }

    @Test
    @Tag("Regression")
    @Tag("QA")
    void test5() {
        System.out.println("This is Regression Test for QA");
    }
}

To run the tests tagged with “production” in IntelliJ. Edit the configuration. Click on the Run and select “Edit Configurations”.

Select Tags from a list of components and mention the name of tag you want to execute. Apply the changes by clicking on the “Apply” button and then Click on the “OK” button.

Now, this create a new Configuration as shown in the below image.

Click on this configuration. It will only run the test method tagged with @Production.

2. We can apply multiple tags on a single test case as well. Here, test method – test_Calculator() is tagged with @Development and @QA.

    @Test
    @Tag("Development")
    @Tag("QA")
    void test_Calculator() {
        System.out.println("test_Calculator()");
        assertEquals(18, 10 + 8);
        assertEquals(2, 10 - 8);
    }

To run above test, edit the configuration as shown below.

The output of the above program is

3. Filtering Tags with Maven Surefire Plugin

In Maven, we can run tests based on tags via the configuration parameters of the maven-surefire-plugin.

<plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-surefire-plugin</artifactId>
       <version>3.0.0-M5</version>
       <configuration>
           <!-- Include tags -->
           <groups>Development,QA,Production</groups>
           <!-- Exclude tags -->
           <excludedGroups>In-Progress</excludedGroups>
       </configuration>
</plugin>

If we now execute this plugin, it will execute all tests which are tagged as Development,QA,Production. 

If we want to exclude any specific test from the test execution, mention it with <excludeGroups>

Below mentioned command will run all the tests except test tagged with “In-Progress”.

mvn clean test -DexcludeGroups="In-Progress"

4. Creating your own custom tag annotation

If we are using same tag @Tag(“Security”) or combination with @Tag(“QA”) in several tests, instead of copying and pasting @Tag(“Security”), @Tag(“QA”) throughout your code base, you can create a custom composed annotation named @SecurityQATest as follows. @SecurityQATest can then be used instead using 2 annotations every time.

Following example shows you how to create custom tag annotation for @Tag(“Security”), @Tag(“QA”).

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestTemplate;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.ANNOTATION_TYPE,ElementType.METHOD})
@Tag("Security")
@Tag("QA")
@Test
public @interface SecurityQATest {

}

    @SecurityQATest
    void test6() {
        System.out.println("This is Security Testing for QA");
    }

To run this test, use the below command:

mvn clean test -Dgroups="Security&QA"

The result of the above program is

Congratulations. We have understood the usage of @Tag annotation. Happy Learning!!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s