The @SelectPackages annotation allows you to include all test classes from specified packages in your test suite. This is useful when you want to run all tests within particular package hierarchies without listing each class individually.

How @SelectPackages Works

When you annotate a suite class with @SelectPackages, the Suite Engine will:

1. Scan the specified packages recursively
2. Discover all test classes within those packages
3. Include them in the test suite execution
4. Execute tests according to their configuration and ordering

Package Selection Behavior

The selection includes:

• All direct subpackages of the specified packages
• Test classes in the package itself
• Test classes in all nested subpackages
• Both JUnit Jupiter and JUnit Vintage tests (if configured)

Use Cases

• Module Testing: Run all tests for a specific module or component
• Integration Tests: Group all integration tests from different packages
• Smoke Tests: Create a smoke test suite from critical packages
• Regression Testing: Organize regression tests by functional area

Java source and doc

Definition of SelectPackages

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

Example

pom.xml

<dependency>
   <groupId>org.junit.jupiter</groupId>
   <artifactId>junit-jupiter-engine</artifactId>
   <version>6.0.1</version>
</dependency>
<dependency>
   <groupId>org.junit.platform</groupId>
   <artifactId>junit-platform-suite-engine</artifactId>
   <version>6.0.1</version>
</dependency>

Creating different packages

We have number of Test classes in different package as seen here:

$ tree /F /A
\---com
    \---logicbig
        \---example
            |   SuiteSelectPackagesExample.java
            |   
            +---auth
            |       AuthenticationTests.java
            |       
            +---order
            |       OrderManagementTests.java
            |       
            \---payment
                    PaymentProcessingTests.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 testUserLogin() {
        System.out.println("AuthenticationTests - User login test (auth package)");
        assertTrue(true, "User login should succeed");
    }

    @Test
    void testPasswordValidation() {
        System.out.println("AuthenticationTests - Password validation test");
        assertEquals(8, "password".length(), "Password should be 8 characters");
    }

    @Test
    void testSessionCreation() {
        System.out.println("AuthenticationTests - Session creation test");
        assertNotNull(System.currentTimeMillis(), "Session should have creation time");
    }
}

package com.logicbig.example.payment;

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

public class PaymentProcessingTests {

    @Test
    void testCreditCardPayment() {
        System.out.println("PaymentProcessingTests - Credit card payment test (payment package)");
        assertTrue(true, "Credit card payment should process successfully");
    }

    @Test
    void testPaymentAmountValidation() {
        System.out.println("PaymentProcessingTests - Payment amount validation");
        assertTrue(100.0 > 0, "Payment amount should be positive");
    }

    @Test
    void testPaymentGatewayConnection() {
        System.out.println("PaymentProcessingTests - Payment gateway connection test");
        assertFalse(false, "Gateway connection should be established");
    }
}

package com.logicbig.example.order;

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

public class OrderManagementTests {

    @Test
    void testOrderCreation() {
        System.out.println("OrderManagementTests - Order creation test (order package)");
        assertTrue(true, "Order should be created successfully");
    }

    @Test
    void testOrderTotalCalculation() {
        System.out.println("OrderManagementTests - Order total calculation");
        double itemPrice = 25.99;
        double tax = 2.60;
        double shipping = 5.00;
        double expectedTotal = itemPrice + tax + shipping;

        assertEquals(expectedTotal, 33.59, 0.01, "Order total should be calculated correctly");
    }

    @Test
    void testOrderStatusUpdate() {
        System.out.println("OrderManagementTests - Order status update test");
        String status = "PROCESSING";
        assertEquals("PROCESSING", status, "Order status should be PROCESSING");
    }
}

Suite Class

package com.logicbig.example;

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

@Suite
@SuiteDisplayName("Quick Application Test Suite")
@SelectPackages({
    "com.logicbig.example.auth",
    "com.logicbig.example.order"
})
public class SuiteSelectPackagesExample {
    // This class acts as a test suite container
    // All test classes in the specified packages will be executed
}

Output

$ mvn test -Dtest=SuiteSelectPackagesExample
[INFO] Scanning for projects...
[INFO] 
[INFO] -----< com.logicbig.example:junit-5-suite-select-packages-example >-----
[INFO] Building junit-5-suite-select-packages-example 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-suite-select-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-select-packages-example\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-suite-select-packages-example ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-suite-select-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-select-packages-example\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-suite-select-packages-example ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 4 source files with javac [debug target 25] to target\test-classes
[INFO] 
[INFO] --- surefire:3.5.4:test (default-test) @ junit-5-suite-select-packages-example ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
AuthenticationTests - Session creation test
AuthenticationTests - User login test (auth package)
AuthenticationTests - Password validation test
[INFO] +--com.logicbig.example.auth.AuthenticationTests - 0.176 ss
[INFO] |  +-- [OK] testSessionCreation - 0.080 ss
[INFO] |  +-- [OK] testUserLogin - 0.021 ss
[INFO] |  '-- [OK] testPasswordValidation - 0.008 ss
OrderManagementTests - Order total calculation
OrderManagementTests - Order status update test
OrderManagementTests - Order creation test (order package)
[INFO] +--com.logicbig.example.order.OrderManagementTests - 0.048 ss
[INFO] |  +-- [OK] testOrderTotalCalculation - 0.005 ss
[INFO] |  +-- [OK] testOrderStatusUpdate - 0.014 ss
[INFO] |  '-- [OK] testOrderCreation - 0.007 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.666 s
[INFO] Finished at: 2025-12-19T16:13:21+08:00
[INFO] ------------------------------------------------------------------------

As configured, the test suite only executed tests within the com.logicbig.example.auth and com.logicbig.example.order packages. Tests in the com.logicbig.example.payment package were deliberately excluded, as defined by the @SelectPackages annotation below:

@SelectPackages({
  "com.logicbig.example.auth",
  "com.logicbig.example.order"
})

@SuiteDisplayName annotation

As seen in above example, we used @SuiteDisplayName annotation as well. @SuiteDisplayName is used to declare a custom display name for the suite class.

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