JUnit Tagging and Filtering

Introduction

In this chapter, we will explore how to use tagging and filtering in JUnit. Tagging allows you to categorize tests, and filtering enables you to run specific categories of tests based on tags. This can be particularly useful in large projects where you want to run subsets of tests, such as unit tests, integration tests, or tests related to a specific feature.

What is Tagging and Filtering?

Tagging in JUnit involves assigning one or more tags to test methods or classes. These tags can then be used to include or exclude specific tests during test execution. Filtering allows you to run tests that match specific tags, enabling more flexible and targeted test runs.

Overview of @Tag Annotation

The @Tag annotation is used to assign tags to test methods or classes. Tags are simple string labels that can be applied to any test element.

Syntax of @Tag

@Tag("tagName")

Example: Tagging and Filtering Tests

Let’s create examples to demonstrate how to use the @Tag annotation and filter tests based on tags.

Step 1: Create a Class Under Test

Calculator Class

The Calculator class will have basic arithmetic operations.

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }

    public int subtract(int a, int b) {
        return a - b;
    }

    public int multiply(int a, int b) {
        return a * b;
    }

    public int divide(int a, int b) {
        if (b == 0) {
            throw new IllegalArgumentException("Division by zero");
        }
        return a / b;
    }
}

Step 2: Create a Test Class with Tags

CalculatorTest

The CalculatorTest class will contain tests for the Calculator class with tags assigned to different methods.

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

public class CalculatorTest {

    private Calculator calculator = new Calculator();

    @Test
    @Tag("unit")
    @Tag("fast")
    void testAdd() {
        assertEquals(5, calculator.add(2, 3), "2 + 3 should equal 5");
    }

    @Test
    @Tag("unit")
    void testSubtract() {
        assertEquals(2, calculator.subtract(5, 3), "5 - 3 should equal 2");
    }

    @Test
    @Tag("integration")
    @Tag("slow")
    void testMultiply() {
        assertEquals(6, calculator.multiply(2, 3), "2 * 3 should equal 6");
    }

    @Test
    @Tag("integration")
    void testDivide() {
        assertEquals(2, calculator.divide(6, 3), "6 / 3 should equal 2");
    }

    @Test
    @Tag("unit")
    void testDivideByZero() {
        Exception exception = assertThrows(IllegalArgumentException.class, () -> {
            calculator.divide(1, 0);
        });
        assertEquals("Division by zero", exception.getMessage());
    }
}

Step 3: Filtering Tests by Tags

JUnit tests can be filtered by tags using build tools like Maven and Gradle or directly within IDEs.

Filtering with Maven

To filter tests by tags in Maven, you can configure the maven-surefire-plugin in your pom.xml file:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.0.0-M5</version>
            <configuration>
                <groups>unit</groups> <!-- Only runs tests with the "unit" tag -->
                <!-- <excludedGroups>integration</excludedGroups> --> <!-- Excludes tests with the "integration" tag -->
            </configuration>
        </plugin>
    </plugins>
</build>

Filtering with Gradle

To filter tests by tags in Gradle, you can configure the test task in your build.gradle file:

test {
    useJUnitPlatform {
        includeTags 'unit'
        // excludeTags 'integration'
    }
}

Important Points

• @Tag: Use this annotation to assign one or more tags to test methods or classes. Tags help categorize tests and enable selective test execution.
• Filtering: Use build tools or IDE configurations to filter tests based on tags to run only the relevant subset of tests.

Running the Tests with Filters

To run the tests with filters, configure your build tool (Maven or Gradle) as shown above and execute the test task. The tests matching the specified tags will be executed.

Using Eclipse

• Run Tests with Filters: Use the “Run Configurations” to specify the tags to include or exclude during test execution.
  • Right-click on the test file or project and select Run As > Run Configurations.
  • In the “JUnit” configuration, go to the “Include Tags” field and enter the tags you want to include (e.g., unit). You can also specify tags to exclude.
  • Click “Run” to execute the tests with the specified tags.
• View Results: The results will be displayed in the JUnit view, showing only the tests that match the specified tags.

Using IntelliJ IDEA

• Run Tests with Filters:
  • Open the “Run/Debug Configurations” dialog.
  • Select “JUnit” and click the “+” icon to add a new configuration.
  • In the configuration settings, go to the “Tags” field and enter the tags you want to include (e.g., unit). You can also specify tags to exclude.
  • Click “Apply” and then “Run” to execute the tests with the specified tags.
• 
• View Results: The results will be displayed in the Run window, showing only the tests that match the specified tags.

Conclusion

JUnit tagging and filtering provide a powerful way to categorize and selectively run tests. By using the @Tag annotation, you can assign meaningful tags to your test methods and classes. Filtering tests based on tags allows you to run specific subsets of tests, improving the efficiency and focus of your testing efforts. This approach is particularly useful in large projects where running all tests might be time-consuming or unnecessary.