Test Execution Order

By default, test classes and methods will be ordered using an algorithm that is deterministic but intentionally nonobvious. This ensures that subsequent runs of a test suite execute test classes and test methods in the same order, thereby allowing for repeatable builds.

See Definitions for a definition of test method and test class.

Method Order

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 — for example, when writing integration tests or functional tests where the sequence of the tests is important, especially in conjunction with @TestInstance(Lifecycle.PER_CLASS).

To control the order in which test methods are executed, annotate your test class or test interface with @TestMethodOrder and specify the desired MethodOrderer implementation. You can implement your own custom MethodOrderer or use one of the following built-in MethodOrderer implementations.

The MethodOrderer configured on a test class is inherited by the @Nested test classes it contains, recursively. If you want to avoid that a @Nested test class uses the same MethodOrderer as its enclosing class, you can specify MethodOrderer.Default together with @TestMethodOrder.

See also: Wrapping Behavior of Callbacks

The following example demonstrates how to guarantee that test methods are executed in the order specified via the @Order annotation.

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 OrderedTestsDemo {

	@Test
	@Order(1)
	void nullValues() {
		// perform assertions against null values
	}

	@Test
	@Order(2)
	void emptyValues() {
		// perform assertions against empty values
	}

	@Test
	@Order(3)
	void validValues() {
		// perform assertions against valid values
	}

}

Setting the Default Method Orderer

You can use the junit.jupiter.testmethod.order.default configuration parameter to specify the fully qualified class name of the MethodOrderer you would like to use by default. Just like for the orderer configured via the @TestMethodOrder annotation, the supplied class has to implement the MethodOrderer interface. The default orderer will be used for all tests unless the @TestMethodOrder annotation is present on an enclosing test class or test interface.

For example, to use the MethodOrderer.OrderAnnotation method orderer by default, you should set the configuration parameter to the corresponding fully qualified class name (e.g., in src/test/resources/junit-platform.properties):

junit.jupiter.testmethod.order.default = \
    org.junit.jupiter.api.MethodOrderer$OrderAnnotation

Similarly, you can specify the fully qualified name of any custom class that implements MethodOrderer.

Class Order

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.

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.

The following example demonstrates how to guarantee that @Nested test classes are executed in the order specified via the @Order annotation.

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

@TestClassOrder(ClassOrderer.OrderAnnotation.class)
class OrderedNestedTestClassesDemo {

	@Nested
	@Order(1)
	class PrimaryTests {

		@Test
		void test1() {
		}
	}

	@Nested
	@Order(2)
	class SecondaryTests {

		@Test
		void test2() {
		}
	}
}