How to control test class execution order in JUnit 5 suites?

Question

I'm organizing my tests using JUnit 5's @Suite and @SelectClasses, but need to control the execution sequence of the test classes. According to the documentation, @SelectClasses doesn't guarantee execution order, but I have a specific sequence requirement for my test pipeline.

Here's my current suite setup:

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

@Suite
@SelectClasses({
    Test1.class,        // Should run FIRST
    Suite1.class,       // Should run after Test1 but before Test2
    Suite2.class,        // Should run after Test1 but before Test2
    Suite3.class,        // Should run after Test1 but before Test2
    Test2.class         // Should run LAST
})
public class SuiteA {  }

The subordinate suites look like:

@Suite
@SelectClasses({TestXxx.class, SuiteXxx.class})
public class Suite1 {   }

My test dependencies require that:

Test1 executes first (initial setup and validation)

Suite1, Suite2, Suite3 execute in between (main test batches)

Test2 executes last (cleanup and final verification)

What I've tried/researched:

I know about @TestMethodOrder for ordering methods within a class, but I need class-level ordering across the suite

I've looked at @Suite documentation but didn't find explicit ordering controls

I considered separate suites, but need this specific sequence in a single execution

Question:

What is the standard JUnit 5 approach to enforcing test class execution order within a suite? If declarative ordering isn't supported, what are the recommended patterns or workarounds to achieve this test sequence? I'm using JUnit 5.8+/Jupiter with the junit-platform-suite engine.

Please provide a concrete solution - I already know @SelectClasses doesn't order tests. I need a working implementation.

You are using inline code format which makes the code difficult to read and understand. Instead please use code block format for code, errors and logs. — aled
– aled, Commented Oct 23 at 17:16
AFAIK JUnit has always advised against method (or class) order dependency. As such, they made very little effort to support this. You might want to look at TestNG. — SiKing
– SiKing, Commented Oct 23 at 18:13

Slaw · Accepted Answer · 2025-10-24 16:19:49Z

JUnit Jupiter added ClassOrderer in version 5.8. It became stable API in version 5.10. Also see §2.11.2. Class Order of the user guide:

Although test classes typically should not rely on the order in which they are executed, there are times when it is desirable to enforce a specific test class execution order. You may wish to execute test classes in a random order to ensure there are no accidental dependencies between test classes, or you may wish to order test classes to optimize build time as outlined in the following scenarios.

Run previously failing tests and faster tests first: "fail fast" mode

With parallel execution enabled, schedule longer tests first: "shortest test plan execution duration" mode

Various other use cases

To configure test class execution order globally for the entire test suite, use the junit.jupiter.testclass.order.default configuration parameter to specify the fully qualified class name of the ClassOrderer you would like to use. The supplied class must implement the ClassOrderer interface.

You can implement your own custom ClassOrderer or use one of the following built-in ClassOrderer implementations.

ClassOrderer.ClassName: sorts test classes alphanumerically based on their fully qualified class names

ClassOrderer.DisplayName: sorts test classes alphanumerically based on their display names (see display name generation precedence rules)

ClassOrderer.OrderAnnotation: sorts test classes numerically based on values specified via the @Order annotation

ClassOrderer.Random: orders test classes pseudo-randomly and supports configuration of a custom seed

For example, for the @Order annotation to be honored on test classes, you should configure the ClassOrderer.OrderAnnotation class orderer using the configuration parameter with the corresponding fully qualified class name (e.g., in src/test/resources/junit-platform.properties):
junit.jupiter.testclass.order.default = \
    org.junit.jupiter.api.ClassOrderer$OrderAnnotation
The configured ClassOrderer will be applied to all top-level test classes (including static nested test classes) and @Nested test classes.

Top-level test classes will be ordered relative to each other; whereas, @Nested test classes will be ordered relative to other @Nested test classes sharing the same enclosing class.

To configure test class execution order locally for @Nested test classes, declare the @TestClassOrder annotation on the enclosing class for the @Nested test classes you want to order, and supply a class reference to the ClassOrderer implementation you would like to use directly in the @TestClassOrder annotation. The configured ClassOrderer will be applied recursively to @Nested test classes and their @Nested test classes. If you want to avoid that a @Nested test class uses the same ClassOrderer as its enclosing class, you can specify ClassOrderer.Default together with @TestClassOrder. Note that a local @TestClassOrder declaration always overrides an inherited @TestClassOrder declaration or a ClassOrderer configured globally via the junit.jupiter.testclass.order.default configuration parameter.

[...]

With suites, another way to set a configuration parameter is via the @ConfigurationParameter annotation and/or @ConfigurationParametersResource annotation. Either would let you define the "global" class orderer for the suite.

But note there is currently no way to control the order suites execute relative to each other. The ClassOrderer mechanism currently only has an effect in the Jupiter engine, not the Suite engine.

Also, as noted in the discussion you opened on GitHub, you can't interleave the execution of non-suite tests with suites. They are executed by different engines. You may want to consider using @BeforeSuite and @AfterSuite instead. Or you may have to rethink your test organization.

Collectives™ on Stack Overflow

How to control test class execution order in JUnit 5 suites?

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related