The @ExcludePackages annotation works with @SelectPackages to filter out specific packages from the selected package hierarchy. This is useful when you want to run most tests from a package tree but exclude certain packages, such as legacy code, integration tests, or experimental features.

How @ExcludePackages Works

The exclusion mechanism follows this process:

1. @SelectPackages defines the initial package selection scope
2. @ExcludePackages filters out specified packages from this scope
3. Tests from excluded packages are not executed
4. All other tests from selected packages run normally

Practical Applications

• Legacy Code Exclusion: Exclude deprecated or legacy test packages
• Environment-Specific Tests: Exclude tests not relevant to current environment
• Performance Testing: Exclude long-running integration tests from unit test suite
• Feature Flags: Exclude tests for features that are disabled

Java source and doc

Definition of ExcludePackages

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

Example

We are using following packages in our example:

$ tree /a /f
\---com
    \---logicbig
        \---example
            |   SuiteExcludePackagesExample.java
            |   
            +---core
            |       CoreTests.java
            |       
            +---experimental
            |       ExperimentalTests.java
            |       
            +---integration
            |       IntegrationTests.java
            |       
            +---legacy
            |       LegacyTests.java
            |       
            \---performance
                    PerformanceTests.java
                    

Test Classes

package com.logicbig.example.core;

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

public class CoreTests {

    @Test
    void testCoreBusinessLogic() {
        System.out.println("CoreTests - Core business logic test (INCLUDED)");
        assertTrue(true, "Core logic should execute successfully");
    }

    @Test
    void testDataValidation() {
        System.out.println("CoreTests - Data validation test");
        assertNotNull("test data", "Data should not be null");
    }
}

package com.logicbig.example.integration;

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

public class IntegrationTests {

    @Test
    void testExternalServiceIntegration() {
        System.out.println("IntegrationTests - External service integration test (INCLUDED)");
        assertTrue(true, "Integration should work");
    }

    @Test
    void testDatabaseConnection() {
        System.out.println("IntegrationTests - Database connection test");
        assertEquals(1, 1, "Database connection should be established");
    }
}

package com.logicbig.example.legacy;

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

public class LegacyTests {

    @Test
    void testLegacyFunctionality() {
        System.out.println("LegacyTests - Legacy functionality test");
    }

    @Test
    void testDeprecatedAPI() {
        System.out.println("LegacyTests - Deprecated API test");

    }
}

package com.logicbig.example.experimental;

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

public class ExperimentalTests {

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

package com.logicbig.example.performance;

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

public class PerformanceTests {

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

    }

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

    }
}

Our suite class

package com.logicbig.example;

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

@Suite
@SuiteDisplayName("Exclusion-Based Test Suite")
@SelectPackages("com.logicbig.example")  // Select everything under com.logicbig.example
@ExcludePackages({
    "com.logicbig.example.legacy",        // Exclude legacy package
    "com.logicbig.example.experimental",  // Exclude experimental package
    "com.logicbig.example.performance"    // Exclude performance package
})
public class SuiteExcludePackagesExample {
    // Tests from core and integration packages will be executed
    // Tests from legacy, experimental, and performance packages will be excluded
}

Output

$ mvn test -Dtest=SuiteExcludePackagesExample
[INFO] Scanning for projects...
[INFO] 
[INFO] ----< com.logicbig.example:junit-5-suite-exclude-packages-example >-----
[INFO] Building junit-5-suite-exclude-packages-example 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-suite-exclude-packages-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-exclude-packages-example\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-suite-exclude-packages-example ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-suite-exclude-packages-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-exclude-packages-example\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-suite-exclude-packages-example ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 6 source files with javac [debug target 25] to target\test-classes
[INFO] 
[INFO] --- surefire:3.5.4:test (default-test) @ junit-5-suite-exclude-packages-example ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
IntegrationTests - External service integration test (INCLUDED)
IntegrationTests - Database connection test
[INFO] +--com.logicbig.example.integration.IntegrationTests - 0.142 ss
[INFO] |  +-- [OK] testExternalServiceIntegration - 0.088 ss
[INFO] |  '-- [OK] testDatabaseConnection - 0.016 ss
CoreTests - Data validation test
CoreTests - Core business logic test (INCLUDED)
[INFO] +--com.logicbig.example.core.CoreTests - 0.028 ss
[INFO] |  +-- [OK] testDataValidation - 0.009 ss
[INFO] |  '-- [OK] testCoreBusinessLogic - 0.004 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.794 s
[INFO] Finished at: 2025-12-19T16:14:07+08:00
[INFO] ------------------------------------------------------------------------

The above output confirms that the exclusion-based suite configuration functions as intended, as all tests from the selected com.logicbig.example package hierarchy ran successfully without any tests from the excluded subpackages appearing. The execution of AuthenticationTests and PaymentTests (which include LegacyAuthTests as a subpackage of auth) demonstrates that only non-excluded packages were included, while the complete absence of any legacy, experimental, or performance package tests in the results verifies that the @ExcludePackages filter correctly prevented their execution.

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