JUnit 5 - JUnit Suite Configuration Reuse via Superclass

JUnit 5 allows a test suite class annotated with @Suite to be extended. Subclasses can reuse configuration defined in the superclass, such as @SelectPackages, while defining additional filters like @IncludeTags or @ExcludeTags.

Example

Tests

package com.logicbig.example;

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Tag("integration")
public class IntegrationTest {

    @Test
    void integrationTestMethod() {
        assertTrue(true);
    }
}

package com.logicbig.example;

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;

@Tag("staging")
public class StagingTest {

    @Test
    void stagingTestMethod() {
        assertTrue(true);
    }
}

Base Suite

package com.logicbig.example;

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

@Suite
@SelectPackages("com.logicbig.example")
public abstract class BaseSuite {
    // Base configuration for all suites
}

Extending Suite

package com.logicbig.example;

import org.junit.platform.suite.api.IncludeTags;

@IncludeTags("integration")
public class ExtendedSuiteTest extends BaseSuite {
    // Inherits @SelectPackages from BaseSuite, adds an 'integration' tag filter
}

Output

$ mvn test -Dtest=ExtendedSuiteTest
[INFO] Scanning for projects...
[INFO] 
[INFO] ----< com.logicbig.example:junit-5-superclass-suite-configuration >-----
[INFO] Building junit-5-superclass-suite-configuration 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-superclass-suite-configuration ---
[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-superclass-suite-configuration\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-superclass-suite-configuration ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-superclass-suite-configuration ---
[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-superclass-suite-configuration\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-superclass-suite-configuration ---
[INFO] Changes detected - recompiling the module! :source
[WARNING] File encoding has not been set, using platform encoding Cp1252, i.e. build is platform dependent!
[INFO] Compiling 4 source files with javac [debug target 17] to target\test-classes
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-superclass-suite-configuration ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] +--ExtendedSuiteTest IntegrationTest - 0.096 ss
[INFO] |  '-- [OK] integrationTestMethod - 0.068 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.601 s
[INFO] Finished at: 2025-12-21T09:28:26+08:00
[INFO] ------------------------------------------------------------------------

Explanation

The BaseSuite defines common configuration like @SelectPackages("com.logicbig.example"). The subclass ExtendedSuiteTest inherits this configuration and adds a filter @IncludeTags("integration"). When executed, only tests matching the inherited package selection and the integration tag are run.

This approach allows you to maintain a central suite configuration in a superclass and selectively customize filtering in multiple subclasses without duplicating common annotations.

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