The @IncludeClassNamePatterns annotation allows you to filter test classes based on their name patterns using regular expressions. This provides flexible pattern-based inclusion when you want to select test classes whose names match specific patterns, regardless of their package location.

How @IncludeClassNamePatterns Works

This annotation uses regular expressions to match class names:

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

Pattern Syntax

The patterns use Java regular expression syntax:

• .*Test: Includes all classes ending with "Test"
• .*Integration.*: Includes classes containing "Integration"
• ^[A-Z].*Test$: Includes classes starting with uppercase and ending with "Test"
• User.*Test|.*ServiceTest: Includes classes matching either pattern

Common Use Cases

• Test Type Organization: Include all integration tests (.*IntegrationTest)
• Feature-Based Selection: Include tests for specific features (.*Payment.*Test)
• Naming Convention Enforcement: Ensure only properly named tests run
• Component Testing: Select tests for specific components by name pattern

Java source and doc

Definition of IncludeClassNamePatterns

 package org.junit.platform.suite.api;
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Inherited
 @Documented
 @API(status = MAINTAINED, since = "1.0")
 public @interface IncludeClassNamePatterns {
     String[] value() default "^(Test.*|.+[.$]Test.*|.*Tests?)$"; 1
 }

Example

We created following classes for this example:

D:\example-projects\junit-5\junit-5-suite-engine\junit-5-suite-include-classname-patterns-example\src\test\java>tree /a /f
\---com
    \---logicbig
        \---example
                ExcludedValidation.java
                IntegrationTest.java
                OrderValidationTest.java
                PaymentServiceTest.java
                SuiteIncludeClassNamePatternsExample.java
                UserLoginTest.java
                

Test Classes

package com.logicbig.example;

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

public class UserLoginTest {

    @Test
    void testUserAuthentication() {
        System.out.println("UserLoginTest - User authentication test (INCLUDED - matches patterns)");
        assertTrue(true, "User should authenticate successfully");
    }

    @Test
    void testLoginValidation() {
        System.out.println("UserLoginTest - Login validation test");
        assertEquals("valid", "valid", "Credentials should be valid");
    }
}

package com.logicbig.example;

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

public class PaymentServiceTest {

    @Test
    void testPaymentProcessing() {
        System.out.println("PaymentServiceTest - Payment processing test (INCLUDED - matches patterns)");
        assertTrue(true, "Payment should process");
    }

    @Test
    void testServiceIntegration() {
        System.out.println("PaymentServiceTest - Service integration test");
        assertFalse(false, "Service should integrate");
    }
}

package com.logicbig.example;

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

public class OrderValidationTest {

    @Test
    void testOrderValidation() {
        System.out.println("OrderValidationTest");
        assertTrue(true, "Order should validate");
    }
}

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("IntegrationTest - System integration test");
        assertTrue(true, "System should integrate");
    }
}

package com.logicbig.example;

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

public class ExcludedValidation {

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

Suite class

package com.logicbig.example;

import org.junit.platform.suite.api.IncludeClassNamePatterns;
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 Inclusion Suite")
@SelectPackages("com.logicbig.example")  // Select all packages
@IncludeClassNamePatterns({
    ".*Test$",           // Include classes ending with "Test"
    ".*Service.*",       // Include classes containing "Service"
    "^User.*",           // Include classes starting with "User"
    ".*Integration.*"    // Include classes containing "Integration"
})
public class SuiteIncludeClassNamePatternsExample {
    // Classes matching any of the patterns will be included
    // Classes not matching any pattern will be excluded
}

Output

$ mvn test -Dtest=SuiteIncludeClassNamePatternsExample
[INFO] Scanning for projects...
[INFO] 
[INFO] --< com.logicbig.example:junit-5-suite-include-classname-patterns-example >--
[INFO] Building junit-5-suite-include-classname-patterns-example 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-suite-include-classname-patterns-example ---
[WARNING] Using platform encoding (UTF-8 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-include-classname-patterns-example\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-suite-include-classname-patterns-example ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-suite-include-classname-patterns-example ---
[WARNING] Using platform encoding (UTF-8 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-include-classname-patterns-example\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-suite-include-classname-patterns-example ---
[INFO] Nothing to compile - all classes are up to date.
[INFO] 
[INFO] --- surefire:3.5.4:test (default-test) @ junit-5-suite-include-classname-patterns-example ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
UserLoginTest - User authentication test (INCLUDED - matches patterns)
UserLoginTest - Login validation test
[INFO] +--com.logicbig.example.UserLoginTest - 0.054 ss
[INFO] |  +-- [OK] testUserAuthentication - 0.026 ss
[INFO] |  '-- [OK] testLoginValidation - 0.008 ss
IntegrationTest - System integration test
[INFO] +--com.logicbig.example.IntegrationTest - 0.003 ss
[INFO] |  '-- [OK] testSystemIntegration - 0.001 ss
PaymentServiceTest - Service integration test
PaymentServiceTest - Payment processing test (INCLUDED - matches patterns)
[INFO] +--com.logicbig.example.PaymentServiceTest - 0.007 ss
[INFO] |  +-- [OK] testServiceIntegration - 0.002 ss
[INFO] |  '-- [OK] testPaymentProcessing - 0.002 ss
OrderValidationTest
[INFO] +--com.logicbig.example.OrderValidationTest - 0.004 ss
[INFO] |  '-- [OK] testOrderValidation - 0.002 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.970 s
[INFO] Finished at: 2025-12-19T16:16:28+08:00
[INFO] ------------------------------------------------------------------------

The above output confirms that the pattern-based class inclusion suite functions correctly, as only test classes matching the specified regex patterns were executed. The successful runs of UserLoginTest (matches ^User.* and .*Test$), IntegrationTest (matches .*Integration.*), PaymentServiceTest (matches both .*Test$ and .*Service.*), and OrderValidationTest (matches .*Test$) demonstrate that the @IncludeClassNamePatterns filter effectively selects classes based on their naming conventions while excluding any non-matching classes from the broader @SelectPackages scope.

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