The @IncludePackages annotation works in conjunction with @SelectPackages to filter which packages should be included from the selected package hierarchy. This allows for fine-grained control over package inclusion when you want to select broad package trees but exclude certain subpackages.

How @IncludePackages Works

When combined with @SelectPackages, @IncludePackages acts as a filter:

1. @SelectPackages defines the initial package selection scope
2. @IncludePackages filters this scope to only include specified packages
3. Only tests from packages that match the inclusion patterns are executed

Use Cases for @IncludePackages

• Selective Package Inclusion: Include only specific packages from a broader selection
• Component Testing: Test only specific components within a module
• Feature Testing: Run tests for specific features across packages
• Tiered Testing: Create different test suites for different testing tiers

Java source and doc

Definition of IncludePackages

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

Example

We have following test in different packages:

$ tree /F /A
\---com
    \---logicbig
        \---example
            |   SuiteIncludePackagesExample.java
            |   
            +---auth
            |   |   AuthenticationTests.java
            |   |   
            |   \---legacy
            |           LegacyAuthTests.java
            |           
            +---order
            |       OrderTests.java
            |       
            +---payment
            |       PaymentTests.java
            |       
            \---report
                    ReportTests.java
                    

Test classes

package com.logicbig.example.auth;

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

public class AuthenticationTests {

    @Test
    void testUserAuthentication() {
        System.out.println("AuthenticationTests - User authentication test (INCLUDED)");
        assertTrue(true, "User should be authenticated");
    }

    @Test
    void testAuthorizationCheck() {
        System.out.println("AuthenticationTests - Authorization check");
        assertTrue("admin".equals("admin"), "Admin role should be recognized");
    }
}

package com.logicbig.example.auth.legacy;

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

public class LegacyAuthTests {

    @Test
    void testLegacyLogin() {
        System.out.println("LegacyAuthTests - Legacy login test (INCLUDED - subpackage of auth)");
        assertTrue(true, "Legacy login should work");
    }
}

package com.logicbig.example.payment;

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

public class PaymentTests {

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

    @Test
    void testRefundProcessing() {
        System.out.println("PaymentTests - Refund processing test");
        assertEquals(0, 100 - 100, "Refund should be complete");
    }
}

package com.logicbig.example.order;

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

public class OrderTests {

    @Test
    void testOrderCreation() {
        System.out.println("OrderTests - Order creation test");

    }
}

package com.logicbig.example.report;

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

public class ReportTests {

    @Test
    void testReportGeneration() {
        System.out.println("ReportTests - Report generation test");

    }
}

Class with @Suite

package com.logicbig.example;

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

@Suite
@SuiteDisplayName("Selective Package Inclusion Suite")
@SelectPackages("com.logicbig.example")  // Select everything under com.logicbig.example
@IncludePackages({
    "com.logicbig.example.auth",           // Include auth package
    "com.logicbig.example.payment",        // Include payment package
    // Note: order package is NOT included
    // Note: report package is NOT included
})
public class SuiteIncludePackagesExample {
    // Only tests from auth and payment packages will be executed
    // Tests from order and report packages will be excluded
}

Output

$ mvn test -Dtest=SuiteIncludePackagesExample
[INFO] Scanning for projects...
[INFO] 
[INFO] ----< com.logicbig.example:junit-5-suite-include-packages-example >-----
[INFO] Building junit-5-suite-include-packages-example 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-suite-include-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-include-packages-example\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-suite-include-packages-example ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-suite-include-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-include-packages-example\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-suite-include-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-include-packages-example ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
AuthenticationTests - User authentication test (INCLUDED)
AuthenticationTests - Authorization check
[INFO] +--com.logicbig.example.auth.AuthenticationTests - 0.111 ss
[INFO] |  +-- [OK] testUserAuthentication - 0.057 ss
[INFO] |  '-- [OK] testAuthorizationCheck - 0.019 ss
LegacyAuthTests - Legacy login test (INCLUDED - subpackage of auth)
[INFO] +--com.logicbig.example.auth.legacy.LegacyAuthTests - 0.010 ss
[INFO] |  '-- [OK] testLegacyLogin - 0.005 ss
PaymentTests - Refund processing test
PaymentTests - Payment processing test (INCLUDED)
[INFO] +--com.logicbig.example.payment.PaymentTests - 0.019 ss
[INFO] |  +-- [OK] testRefundProcessing - 0.005 ss
[INFO] |  '-- [OK] testPaymentProcessing - 0.004 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.404 s
[INFO] Finished at: 2025-12-19T16:12:51+08:00
[INFO] ------------------------------------------------------------------------

The above output confirms that the suite configuration is working as expected, as only tests from the specified auth and payment packages were executed. We can see authentication tests (AuthenticationTests and LegacyAuthTests) and payment tests (PaymentTests) running successfully, while there is no evidence of any tests from the excluded order and report packages appearing in the results. This demonstrates that the @IncludePackages filter effectively restricts test execution to only the designated subpackages despite the broader @SelectPackages selection.

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