JUnit Test Execution Order: @TestMethodOrder and @Order

What Is the Default Test Order in JUnit?

The JUnit user guide's test execution order page states it in one line: by default, test classes and methods will be ordered using an algorithm that is deterministic but intentionally nonobvious. Deterministic means the same build produces the same order every time. Nonobvious means the order is not the one in the source file and not alphabetical, so a test that happens to pass because of its neighbors will keep passing until a method is added or renamed.

I ran a four-method class with no orderer on a TestMu AI HyperExecute Linux VM (job 665c5859, Java 17, JUnit 6.1.3) to see what that looks like. The methods are declared in the order charlie, alpha, bravo, delta, and each prints its name:

[INFO] Running ordering.DefaultOrderTest
[default-order] alpha
[default-order] bravo
[default-order] delta
[default-order] charlie
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.086 s -- in ordering.DefaultOrderTest

Neither declaration order nor alphabetical order, and the same sequence on every rerun. The design is deliberate: the project, whose junit-team/junit-framework repository had 7,055 stars on GitHub on October 7, 2026, wants a suite that works in any order, and an order that looks meaningful would invite tests that depend on it. When you do need control, you ask for it explicitly.

Order Methods With @TestMethodOrder and @Order

The job takes one annotation on the class and one on each method. @TestMethodOrder on the class names the strategy, and @Order on each method supplies the number; lower values run first. Both live in org.junit.jupiter.api, and the orderer is the nested class MethodOrderer.OrderAnnotation:

import org.junit.jupiter.api.MethodOrderer.OrderAnnotation;
import org.junit.jupiter.api.Order;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestMethodOrder;

@TestMethodOrder(OrderAnnotation.class)
class OrderedByAnnotationTest {

    @Test
    @Order(3)
    void validValues() {
        System.out.println("[order-annotation] 3 validValues");
    }

    @Test
    @Order(1)
    void nullValues() {
        System.out.println("[order-annotation] 1 nullValues");
    }

    @Test
    @Order(2)
    void emptyValues() {
        System.out.println("[order-annotation] 2 emptyValues");
    }
}

The methods are declared 3, 1, 2 on purpose. The same job ran them as declared by the annotation, not by the file:

[INFO] Running ordering.OrderedByAnnotationTest
[order-annotation] 1 nullValues
[order-annotation] 2 emptyValues
[order-annotation] 3 validValues
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.024 s -- in ordering.OrderedByAnnotationTest

Methods without an @Order value get the default value Integer.MAX_VALUE / 2, so they run after any method numbered below that, and @Order applies only inside one class; it says nothing about which class runs first, which is what ClassOrderer is for below. If a numbered sequence does not take effect, the class-level @TestMethodOrder is almost always the missing piece.

MethodName, DisplayName, and Random Orderers

The user guide lists four MethodOrderer implementations, and the right one depends on why you want order at all:

MethodName is the one most teams reach for when they only want the report to read top to bottom. The run confirms it does exactly what it says, turning charlie, alpha, bravo into alphabetical order:

[INFO] Running ordering.MethodNameOrderTest
[method-name] alpha
[method-name] bravo
[method-name] charlie
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.032 s -- in ordering.MethodNameOrderTest

Random is the least used of the four and the most useful for finding hidden dependencies. Its javadoc names the configuration parameter junit.jupiter.execution.order.random.seed, and when no seed is supplied the default seed is logged at CONFIG level, so a failing nightly run can be replayed with the same order the next morning. Running it once a night surfaces the shared-state bugs that a fixed order hides.

Set a Default Orderer in junit-platform.properties

Annotating every class is noisy. The configuration parameter junit.jupiter.testmethod.order.default applies one orderer to every class that does not declare its own, and the usual place to set it is src/test/resources/junit-platform.properties, where the user guide's example reads:

# src/test/resources/junit-platform.properties
junit.jupiter.testmethod.order.default = \
    org.junit.jupiter.api.MethodOrderer$OrderAnnotation

The value is the fully qualified class name with a dollar sign before the nested class, because MethodOrderer.OrderAnnotation is a nested type. A class-level @TestMethodOrder overrides the property, so a project can default to MethodName for readable reports and switch one integration class to OrderAnnotation. The same file is where parallel execution is switched on, which the JUnit Parallel Testing chapter covers; an ordered class and a concurrent class can live in the same suite as long as the ordered one runs its methods on a single thread.

Order Test Classes With ClassOrderer

Method order says nothing about which class runs first. For that the Platform provides ClassOrderer, with four implementations that mirror the method ones: ClassName sorts by fully qualified class name, DisplayName by display name, OrderAnnotation by an @Order value placed on the class, and Random pseudo-randomly with a seed. It is selected globally rather than per class:

# src/test/resources/junit-platform.properties
junit.jupiter.testclass.order.default = \
    org.junit.jupiter.api.ClassOrderer$OrderAnnotation

@Order(1)
class SchemaMigrationIT { /* runs first */ }

@Order(2)
class DataSeedingIT { /* runs second */ }

Class ordering only holds within one JVM and one run. Surefire's -Dtest selection, a JUnit Test Suite that selects a subset, or a cloud grid that splits classes across machines all change which classes are present, and a class that must run before another is a class that cannot be split away from it.

Nested Classes, Parameterized Tests, and Repeated Tests

These cases trip people up once ordering is in place:

• @Nested classes - the user guide states that top-level test classes are ordered relative to each other, whereas @Nested test classes are ordered relative to other @Nested test classes sharing the same enclosing class. An @Order on a nested class therefore competes only with its siblings, and the JUnit 6.0 release notes list deterministic ordering of nested classes among the changes. The JUnit Nested Tests chapter covers the lifecycle inside them.
• @ParameterizedTest invocations - the method is one unit for the orderer; its invocations run in argument-source order, so @Order sorts the method among its neighbors but cannot interleave individual rows. See JUnit Parameterized Tests.
• @RepeatedTest - the same rule: the repetitions stay together, numbered 1 to n, wherever the method lands. The JUnit Repeated Tests chapter explains the RepetitionInfo each one receives.

Disabled tests keep their position too: a method skipped with @Disabled still occupies its slot in the order, which matters when step 2 of a numbered flow is switched off and step 3 assumes it ran. The JUnit Ignore Test chapter covers the conditional annotations that cause that.

JUnit 4: @FixMethodOrder and MethodSorters

JUnit 4 had the same philosophy and a coarser tool. The @FixMethodOrder javadoc explains that the default order within a class is deterministic but not predictable, and that JUnit 4.11 introduced it because the earlier JVM order was not guaranteed and could change from run to run. The annotation takes one of the MethodSorters values: DEFAULT, the deterministic but not predictable order; NAME_ASCENDING, lexicographic by method name with Method.toString() as a tiebreaker; or JVM, the order the JVM returns, which may vary from run to run.

// JUnit 4
@FixMethodOrder(MethodSorters.NAME_ASCENDING)
public class LegacyOrderedTest {
    @Test public void test1_create() { }
    @Test public void test2_update() { }
}

// JUnit 5 and 6 equivalent
@TestMethodOrder(MethodOrderer.MethodName.class)
class OrderedTest {
    @Test void test1_create() { }
    @Test void test2_update() { }
}

The migration is a one-line swap for NAME_ASCENDING, and an upgrade for everything else: JUnit 4 had no per-method @Order, so suites that encoded sequence in method names like test1_ and test2_ can finally drop the prefixes. The JUnit 4 vs JUnit 5 chapter lists the rest of the annotation map.

When Ordering Is the Wrong Fix

The user guide puts the caveat next to the feature: although true unit tests typically should not rely on the order in which they are executed, there are times when it is necessary to enforce a specific test method execution order. The distinction is between a sequence the domain requires and a sequence the test code accidentally requires.

TestNG offers the same tools under different names, priority and dependsOnMethods, and the same caution applies; the Priority in TestNG chapter covers that side. Where ordering is legitimate, the cost shows up at scale: an ordered class is a unit that cannot be split. HyperExecute works with that constraint rather than against it. Its Auto-Split discovers test classes and distributes whole classes across fresh VMs with mvn test -Dtest=$test, so an @Order sequence inside a class always executes on one machine in one JVM, while unrelated classes run in parallel elsewhere, and the merged report still reads as one run. The HyperExecute getting started guide shows the discovery command for a Maven project.

Note: Keep ordered classes intact and still cut suite time: TestMu AI runs each JUnit class on its own VM and merges the results. Try TestMu AI free!

Best Practices for JUnit Test Order

• Default to no order - if a test needs a neighbor, fix the test; @TestMethodOrder is for flows, not for making a red build green.
• Number in tens - @Order(10), @Order(20), @Order(30) leaves room to insert a step without renumbering the class.
• Mark ordered classes - a @Tag("flow") or an IT suffix tells the next reader, and the pipeline, that the class must run whole and single-threaded.
• Run Random in CI once a day - with the seed in the log, an order-dependent test is found and reproduced the same morning.
• Prefer MethodName for reports - when the only goal is a readable report, the alphabetical orderer costs nothing and tempts nobody to add dependencies.
• Keep ClassOrderer for integration packages - class order across a whole unit suite is a sign the tests share infrastructure that should be per class.

Conclusion

Add @TestMethodOrder(MethodOrderer.Random.class) to one class that you suspect of hidden dependencies and run it ten times; if it survives, it never needed ordering. For the flows that do, @TestMethodOrder(OrderAnnotation.class) with @Order values in tens, a junit-platform.properties default for the rest, and a ClassOrderer only in integration packages cover every case of JUnit test execution order this chapter ran.

The next chapter, JUnit Ignore Test, covers @Disabled and the conditional annotations, including how a skipped step behaves inside an ordered class. The What Is JUnit chapter explains the engine that applies these orderers if you want the model behind them.