JUnit 5 - Ordering of nested test classes by Using TestClassOrder

[Last Updated: Dec 22, 2025]

The @TestClassOrder annotation works with ClassOrderer implementations to control the execution order of test classes within a test suite. This is useful for integration tests, performance tests, or any scenario where class execution sequence matters.

ClassOrderer Implementations

JUnit 5 provides several built-in ClassOrderer implementations similar to MethodOrderer:

ClassOrderer.ClassName: Orders classes alphabetically by name
ClassOrderer.DisplayName: Orders classes by display name
ClassOrderer.OrderAnnotation: Orders classes using @Order annotation
ClassOrderer.Random: Random class ordering

Usage Considerations

Class ordering should be used judiciously as it can create dependencies between test classes. It's most appropriate for integration test suites or when tests have expensive setup/teardown that should be ordered.

Execution Behavior

When using @TestClassOrder with a ClassOrderer on a parent class, all immediate nested test classes within that parent are executed in the order determined by the specified ClassOrderer. Each nested class can declare its own @TestMethodOrder to control method execution within itself, and if it has its own nested classes, it can declare @TestClassOrder to control their ordering, creating a hierarchical ordering strategy.

Examples

Ordering by class name (ClassOrderer.ClassName)

package com.logicbig.example;

import org.junit.jupiter.api.ClassOrderer;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestClassOrder;

@TestClassOrder(ClassOrderer.ClassName.class)
public class OrderedNestedClassByNameTest {

    @Nested
    class BetaTest {

        @Test
        void testBeta() {
            System.out.println("BetaTest executed");
        }
    }

    @Nested
    class GammaTest {

        @Test
        void testGamma() {
            System.out.println("GammaTest executed");
        }
    }

    @Nested
    class AlphaTest {
        @Test
        void testAlpha() {
            System.out.println("AlphaTest executed");
        }
    }
}

Output

$ mvn test -Dtest=OrderedNestedClassByNameTest
[INFO] Scanning for projects...
[INFO] 
[INFO] -----------< com.logicbig.example:junit-5-test-class-order >------------
[INFO] Building junit-5-test-class-order 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-test-class-order ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-test-class-order ---
[INFO] Changes detected - recompiling the module! :input tree
[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-test-class-order ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
AlphaTest executed
BetaTest executed
GammaTest executed
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$AlphaTest - 0.098 ss
[INFO] |  |  '-- [OK] testAlpha - 0.050 ss
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$BetaTest - 0.098 ss
[INFO] |  |  '-- [OK] testBeta - 0.015 ss
[INFO] +-----com.logicbig.example.OrderedNestedClassByNameTest$GammaTest - 0.098 ss
[INFO] |     '-- [OK] testGamma - 0.002 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.537 s
[INFO] Finished at: 2025-12-22T13:09:08+08:00
[INFO] ------------------------------------------------------------------------

Ordering by display name (ClassOrderer.DisplayName)

package com.logicbig.example;

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

@TestClassOrder(ClassOrderer.DisplayName.class)
public class OrderedNestedClassByDisplayNameTest {

    @Nested
    @DisplayName("Test B")
    class BetaTest {

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

    @Nested
    @DisplayName("Test A")
    class GammaTest {

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

    @Nested
    @DisplayName("Test C")
    class AlphaTest {
        @Test
        void testAlpha() {
            assertTrue(true);
        }
    }
}

Output

$ mvn test -Dtest=OrderedNestedClassByNameTest
[INFO] Scanning for projects...
[INFO] 
[INFO] -----------< com.logicbig.example:junit-5-test-class-order >------------
[INFO] Building junit-5-test-class-order 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-test-class-order ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-test-class-order ---
[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-test-class-order ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
AlphaTest executed
BetaTest executed
GammaTest executed
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$AlphaTest - 0.099 ss
[INFO] |  |  '-- [OK] testAlpha - 0.047 ss
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$BetaTest - 0.099 ss
[INFO] |  |  '-- [OK] testBeta - 0.008 ss
[INFO] +-----com.logicbig.example.OrderedNestedClassByNameTest$GammaTest - 0.099 ss
[INFO] |     '-- [OK] testGamma - 0.001 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.509 s
[INFO] Finished at: 2025-12-22T13:30:54+08:00
[INFO] ------------------------------------------------------------------------

Ordering by @Order (ClassOrderer.OrderAnnotation)

package com.logicbig.example;

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

@TestClassOrder(ClassOrderer.OrderAnnotation.class)
public class OrderedNestedClassByOrderAnnotationTest {

    @Nested
    @Order(3)
    class BetaTest {

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

    @Nested
    @Order(1)
    class GammaTest {

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

    @Nested
    @Order(3)
    class AlphaTest {
        @Test
        void testAlpha() {
            assertTrue(true);
        }
    }
}

Output

$ mvn test -Dtest=OrderedNestedClassByNameTest
[INFO] Scanning for projects...
[INFO] 
[INFO] -----------< com.logicbig.example:junit-5-test-class-order >------------
[INFO] Building junit-5-test-class-order 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-test-class-order ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-test-class-order ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-test-class-order ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
AlphaTest executed
BetaTest executed
GammaTest executed
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$AlphaTest - 0.067 ss
[INFO] |  |  '-- [OK] testAlpha - 0.032 ss
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$BetaTest - 0.067 ss
[INFO] |  |  '-- [OK] testBeta - 0.014 ss
[INFO] +-----com.logicbig.example.OrderedNestedClassByNameTest$GammaTest - 0.067 ss
[INFO] |     '-- [OK] testGamma - 0.003 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.141 s
[INFO] Finished at: 2025-12-22T13:30:58+08:00
[INFO] ------------------------------------------------------------------------

Order randomly (ClassOrderer.Random)

package com.logicbig.example;

import org.junit.jupiter.api.ClassOrderer;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestClassOrder;
import static org.junit.jupiter.api.Assertions.assertTrue;

@TestClassOrder(ClassOrderer.Random.class)
public class OrderedNestedClassRandomTest {

    @Nested
    class BetaTest {

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

    @Nested
    class GammaTest {

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

    @Nested
    class AlphaTest {
        @Test
        void testAlpha() {
            assertTrue(true);
        }
    }
}

Output

$ mvn test -Dtest=OrderedNestedClassByNameTest
[INFO] Scanning for projects...
[INFO] 
[INFO] -----------< com.logicbig.example:junit-5-test-class-order >------------
[INFO] Building junit-5-test-class-order 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\main\resources
[INFO] 
[INFO] --- compiler:3.11.0:compile (default-compile) @ junit-5-test-class-order ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-test-class-order ---
[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-ordering\junit-5-test-class-order\src\test\resources
[INFO] 
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ junit-5-test-class-order ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-test-class-order ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
AlphaTest executed
BetaTest executed
GammaTest executed
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$AlphaTest - 0.060 ss
[INFO] |  |  '-- [OK] testAlpha - 0.027 ss
[INFO] +--.--com.logicbig.example.OrderedNestedClassByNameTest$BetaTest - 0.060 ss
[INFO] |  |  '-- [OK] testBeta - 0.009 ss
[INFO] +-----com.logicbig.example.OrderedNestedClassByNameTest$GammaTest - 0.060 ss
[INFO] |     '-- [OK] testGamma - 0.001 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.106 s
[INFO] Finished at: 2025-12-22T13:31:04+08:00
[INFO] ------------------------------------------------------------------------

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.
JDK 25
Maven 3.9.11

JUnit 5 - TestClassOrder.ClassName

Select All

Download

junit-5-test-class-order
- src
  - test
    - java
      - com
        logicbig
        example
        
        OrderedNestedClassByDisplayNameTest.java
        
        OrderedNestedClassByNameTest.java
        
        OrderedNestedClassByOrderAnnotationTest.java
        
        OrderedNestedClassRandomTest.java
- pom.xml

JUnit 5 - Ordering of nested test classes by Using TestClassOrder

ClassOrderer Implementations

Usage Considerations

Execution Behavior

Examples

Ordering by class name (ClassOrderer.ClassName)

Output

Ordering by display name (ClassOrderer.DisplayName)

Output

Ordering by @Order (ClassOrderer.OrderAnnotation)

Output

Order randomly (ClassOrderer.Random)

Output

Example Project

See Also