Close

JUnit 5 - Maven Surefire Tag Filtering

[Last Updated: Dec 15, 2025]

https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html

The maven-surefire-plugin is the primary plugin in Maven responsible for running the unit tests.
If you do not explicitly list this plugin in your pom.xml, Maven will still use it implicitly (via the Super POM). This implicit setup ensures that the mvn test commands execute your tests.

This plugin provides powerful tag-based filtering capabilities for JUnit 5 tests.

Including/Excluding JUnit Tags

  • To include tags or tag expressions, use can use groups
  • To exclude tags or tag expressions, use can use excludedGroups.

Via plugin

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-surefire-plugin</artifactId>
   <version>...</version>
        <configuration>
            <groups>acceptance | !feature-a</groups>
            <excludedGroups>integration, regression</excludedGroups
       </configuration>
 </plugin>

Via command line

mvn test -Dgroups="acceptance | !feature-a"
mvn test -DexcludedGroups=integration,regression

Example

package com.logicbig.example;

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Tag("integration")
public class MyIntegrationTest {

    @Test
    void dbTransactionTest() {
        assertTrue(true);
    }

    @Test
    @Tag("staging")
    void stagingTest() {
        assertTrue(true);
    }

    @Test
    @Tag("calc-test")
    void testFactorial(){
        assertTrue(true);
    }
}

Applying filter: staging

$ mvn test -Dgroups=staging
[INFO] Scanning for projects...
[INFO] 
[INFO] -----< com.logicbig.example:junit-5-maven-surefire-tag-filtering >------
[INFO] Building junit-5-maven-surefire-tag-filtering 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-maven-surefire-tag-filtering ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-tagging-and-filtering\junit-5-maven-surefire-tag-filtering\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-maven-surefire-tag-filtering ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-maven-surefire-tag-filtering ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-tagging-and-filtering\junit-5-maven-surefire-tag-filtering\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-maven-surefire-tag-filtering ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-maven-surefire-tag-filtering ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] +--com.logicbig.example.MyIntegrationTest - 0.099 ss
[INFO] |  '-- [OK] stagingTest - 0.068 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.472 s
[INFO] Finished at: 2025-12-14T21:29:16+08:00
[INFO] ------------------------------------------------------------------------

Applying filter: integration & !staging

$ mvn test -Dgroups="integration & !staging"
[INFO] Scanning for projects...
[INFO] 
[INFO] -----< com.logicbig.example:junit-5-maven-surefire-tag-filtering >------
[INFO] Building junit-5-maven-surefire-tag-filtering 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-maven-surefire-tag-filtering ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-tagging-and-filtering\junit-5-maven-surefire-tag-filtering\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-maven-surefire-tag-filtering ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-maven-surefire-tag-filtering ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-tagging-and-filtering\junit-5-maven-surefire-tag-filtering\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-maven-surefire-tag-filtering ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-maven-surefire-tag-filtering ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] +--com.logicbig.example.MyIntegrationTest - 0.169 ss
[INFO] |  +-- [OK] testFactorial - 0.127 ss
[INFO] |  '-- [OK] dbTransactionTest - 0.010 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.853 s
[INFO] Finished at: 2025-12-14T21:38:09+08:00
[INFO] ------------------------------------------------------------------------

Excluding: calc-test

$ mvn test -DexcludedGroups=calc-test
[INFO] Scanning for projects...
[INFO] 
[INFO] -----< com.logicbig.example:junit-5-maven-surefire-tag-filtering >------
[INFO] Building junit-5-maven-surefire-tag-filtering 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-maven-surefire-tag-filtering ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-tagging-and-filtering\junit-5-maven-surefire-tag-filtering\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-maven-surefire-tag-filtering ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-maven-surefire-tag-filtering ---
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-tagging-and-filtering\junit-5-maven-surefire-tag-filtering\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-maven-surefire-tag-filtering ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-maven-surefire-tag-filtering ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] +--com.logicbig.example.MyIntegrationTest - 0.093 ss
[INFO] |  +-- [OK] dbTransactionTest - 0.046 ss
[INFO] |  '-- [OK] stagingTest - 0.007 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.145 s
[INFO] Finished at: 2025-12-14T21:58:34+08:00
[INFO] ------------------------------------------------------------------------

Example Project

Dependencies and Technologies Used:

  • junit-jupiter-engine 6.0.1 (Module "junit-jupiter-engine" of JUnit)
     Version Compatibility: 5.0.0 - 6.0.1Version List
    ×

    Version compatibilities of junit-jupiter-engine with this example:

    • 5.0.0
    • 5.0.1
    • 5.0.2
    • 5.0.3
    • 5.1.0
    • 5.1.1
    • 5.2.0
    • 5.3.0
    • 5.3.1
    • 5.3.2
    • 5.4.0
    • 5.4.1
    • 5.4.2
    • 5.5.0
    • 5.5.1
    • 5.5.2
    • 5.6.0
    • 5.6.1
    • 5.6.2
    • 5.6.3
    • 5.7.0
    • 5.7.1
    • 5.7.2
    • 5.8.0
    • 5.8.1
    • 5.8.2
    • 5.9.0
    • 5.9.1
    • 5.9.2
    • 5.9.3
    • 5.10.0
    • 5.10.1
    • 5.10.2
    • 5.10.3
    • 5.10.4
    • 5.10.5
    • 5.11.0
    • 5.11.1
    • 5.11.2
    • 5.11.3
    • 5.11.4
    • 5.12.0
    • 5.12.1
    • 5.12.2
    • 5.13.0
    • 5.13.1
    • 5.13.2
    • 5.13.3
    • 5.13.4
    • 5.14.0
    • 5.14.1
    • 6.0.0
    • 6.0.1

    Versions in green have been tested.

  • JDK 25
  • Maven 3.9.11
JUnit 5 - Maven Surefire Tag Filtering Select All Download
  • junit-5-maven-surefire-tag-filtering
    • src
      • test
        • java
          • com
            • logicbig
              • example
                • MyIntegrationTest.java

    See Also
    Join