@Tag Annotation: Organizing and Running Tests in JUnit 5

In this tutorial, you will learn how to use the @Tag annotation in JUnit 5 for organizing and running your unit tests. By the end of this tutorial, you’ll have a solid understanding of the @Tag annotation, its benefits, and how to apply it effectively in your own test cases. Let’s dive in!

What is the @Tag annotation?

The @Tag annotation is a feature introduced in JUnit 5 that allows us to categorize our test methods. It means we can group related tests together, and this can be really useful for large codebases. This is especially beneficial when we only want to run a specific group of tests, skipping others for a particular test run.

How to use @Tag annotation?

Let’s see how we can use the @Tag annotation in a JUnit 5 test.

Suppose you’re working on a project where you have a bunch of test cases – some are slow, some are fast, and others are integration tests. You want to segregate these test cases based on their characteristics. That’s where @Tag comes into play.

Consider the following example:

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

public class FastTest {

    void testFastMethod1() {
        // test logic here

    void testFastMethod2() {
        // test logic here

In this example, I’ve used the @Tag annotation at the class level, which means that all tests within this class are tagged as “Fast”. You can also use the @Tag annotation on individual methods if you want to tag them differently.

Now let’s see an example of a slow test:

public class SlowTest {

    void testSlowMethod1() {
        // test logic here

    void testSlowMethod2() {
        // test logic here

This is how you can categorize your tests using @Tag. But how can you run specific groups of tests based on these tags? Let’s explore that next.

Running tests based on tags

In order to run tests based on their tags, you can use the Maven Surefire Plugin (if you’re using Maven).

For example, if you want to run only the “Fast” tests with Maven, you would configure the Surefire Plugin in your pom.xml like this:


In this configuration, ${tag} is a placeholder for the tag name. This allows us to provide the tag name at runtime.

To specify the tag at runtime, you can use the -D option followed by the property name and its value on the command line. Here’s how you can run only the tests tagged with “Fast”:

mvn test -Dtag=Fast

This command will run only the tests that have been tagged with “Fast”. You can replace “Fast” with any tag name you have used in your tests to run those specific tests.

Remember, the tag name is case-sensitive, so “Fast” and “fast” would refer to different groups of tests.

This approach makes it extremely flexible to run a specific group of tests, as you can change the tag you want to run just by changing the command line argument. This can be really useful in situations like CI/CD pipelines, where you might want to customize which tests to run based on various conditions.


We’ve come a long way in this tutorial and now you should have a good understanding of how to use the @Tag annotation in JUnit 5. Let’s recap the main key takeaways:

  1. What is @Tag annotation: The @Tag annotation is a powerful feature introduced in JUnit 5, which allows us to categorize our test methods for better organization.
  2. How to use @Tag annotation: We can apply the @Tag annotation at both class and method level to label our tests, enhancing their categorization based on their characteristics, for example, “Fast”, “Slow”, “Integration”, etc.
  3. Running tests based on tags: With the help of Maven, we can selectively execute tests based on their assigned tags. By configuring the Maven Surefire Plugin in our pom.xml file, we can supply the desired tag as a runtime parameter to the mvn test command.

Remember, good testing practices are a crucial part of software development. Categorizing your tests using the @Tag annotation can help you manage your tests better, making your test suite more efficient and your development process smoother.

For more in-depth knowledge about JUnit 5, I highly recommend visiting the “JUnit 5 tutorials for beginners” page.

Continue exploring and happy testing!