The @ExcludeClassNamePatterns annotation allows you to exclude test classes based on their name patterns using regular expressions. This is useful when you want to run most tests but exclude specific categories of tests based on naming conventions.

How @ExcludeClassNamePatterns Works

This annotation filters out classes matching specified patterns:

1. Define regex patterns for class names you want to exclude
2. The Suite Engine evaluates each discovered class name against the patterns
3. Classes with names matching any pattern are excluded
4. Classes not matching any pattern are included

Pattern Matching Strategy

Exclusion patterns use Java regular expressions and can target:

• Test types: .*IntegrationTest to exclude integration tests
• Feature areas: .*Legacy.* to exclude legacy feature tests
• Naming conventions: ^Test.* to exclude classes starting with "Test"
• Multiple criteria: Combine patterns for complex exclusion logic

Common Exclusion Scenarios

• Performance Tests: Exclude long-running performance tests
• Integration Tests: Exclude external dependency tests from unit test runs
• Legacy Code: Exclude tests for deprecated functionality
• Experimental Features: Exclude tests for features under development
• Environment-Specific Tests: Exclude tests not relevant to current environment

Java source and doc

Definition of ExcludeClassNamePatterns

 package org.junit.platform.suite.api;
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Inherited
 @Documented
 @API(status = MAINTAINED, since = "1.0")
 public @interface ExcludeClassNamePatterns {
     String[] value(); 1
 }

Example

We have following classes in our example:

D:\example-projects\junit-5\junit-5-suite-engine\junit-5-suite-exclude-classname-patterns-example\src\test\java>tree /a /f
Folder PATH listing for volume Joe Projects
Volume serial number is D064-5C43
D:.
\---com
    \---logicbig
        \---example
                CoreBusinessTest.java
                ExperimentalFeatureTest.java
                IntegrationTest.java
                LegacySystemTest.java
                PerformanceTest.java
                SuiteExcludeClassNamePatternsExample.java
                

Test Classes

package com.logicbig.example;

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

public class CoreBusinessTest {

    @Test
    void testCoreFunctionality() {
        System.out.println("CoreBusinessTest - Core functionality test");
        assertTrue(true, "Core functionality should work");
    }

    @Test
    void testBusinessLogic() {
        System.out.println("CoreBusinessTest - Business logic test");
        assertEquals(2, 1 + 1, "Business logic should compute correctly");
    }
}

package com.logicbig.example;

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

public class IntegrationTest {

    @Test
    void testSystemIntegration() {
        System.out.println("testSystemIntegration");
    }
}

package com.logicbig.example;

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

public class PerformanceTest {

    @Test
    void testSystemPerformance() {
        System.out.println("testSystemPerformance");
    }
}

package com.logicbig.example;

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

public class LegacySystemTest {

    @Test
    void testLegacyFunctionality() {
        System.out.println("testLegacyFunctionality");
    }
}

package com.logicbig.example;

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

public class ExperimentalFeatureTest {

    @Test
    void testExperimentalFeature() {
        System.out.println("experimental feature test");
    }
}

Suite Class

package com.logicbig.example;

import org.junit.platform.suite.api.ExcludeClassNamePatterns;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.platform.suite.api.Suite;
import org.junit.platform.suite.api.SuiteDisplayName;

@Suite
@SuiteDisplayName("Pattern-Based Class Exclusion Suite")
@SelectPackages("com.logicbig.example")  // Select all packages
@ExcludeClassNamePatterns({
    ".*Integration.*",       // Exclude classes containing "Integration"
    ".*Performance.*",       // Exclude classes containing "Performance"
    ".*Legacy.*",            // Exclude classes containing "Legacy"
    ".*Experimental.*"       // Exclude classes containing "Experimental"
})
public class SuiteExcludeClassNamePatternsExample {
    // Classes matching any exclusion pattern will be excluded
    // Classes not matching any pattern will be included
}

Output

$ mvn test -Dtest=SuiteExcludeClassNamePatternsExample
[INFO] Scanning for projects...
[INFO] 
[INFO] --< com.logicbig.example:junit-5-suite-exclude-classname-patterns-example >--
[INFO] Building junit-5-suite-exclude-classname-patterns-example 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-suite-exclude-classname-patterns-example ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-suite-engine\junit-5-suite-exclude-classname-patterns-example\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-suite-exclude-classname-patterns-example ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-suite-exclude-classname-patterns-example ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-suite-engine\junit-5-suite-exclude-classname-patterns-example\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-suite-exclude-classname-patterns-example ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-suite-exclude-classname-patterns-example ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
CoreBusinessTest - Business logic test
CoreBusinessTest - Core functionality test
[INFO] +--Pattern-Based Class Exclusion Suite CoreBusinessTest - 0.108 ss
[INFO] |  +-- [OK] testBusinessLogic - 0.059 ss
[INFO] |  '-- [OK] testCoreFunctionality - 0.013 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.283 s
[INFO] Finished at: 2025-12-19T11:14:22+08:00
[INFO] ------------------------------------------------------------------------

The test output validates that the pattern-based class exclusion suite works as expected, as only the CoreBusinessTest class executed successfully while all classes matching the exclusion patterns were omitted. The complete absence of any Integration, Performance, Legacy, or Experimental test classes in the results demonstrates that the @ExcludeClassNamePatterns filter effectively prevented their execution, allowing only non-matching classes from the selected packages to run and confirming precise control over test inclusion through regex-based pattern matching.

Example Project

Dependencies and Technologies Used:

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

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

  • 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.

• junit-platform-suite-engine 6.0.1 (Module "junit-platform-suite-engine" of JUnit)
  
• JDK 25
• Maven 3.9.11