ClassOrderer defines the API for ordering top-level test classes and @Nested test classes.

In this context, the term "test class" refers to any class containing methods annotated with @Test, @RepeatedTest, @ParameterizedTest, @TestFactory, or @TestTemplate.

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.

A ClassOrderer can be configured globally for the entire test suite via the junit.jupiter.testclass.order.default configuration parameter (see the User Guide for details) or locally for @Nested test classes via the @TestClassOrder annotation.

Built-in Implementations

JUnit Jupiter provides the following built-in ClassOrderer implementations.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	ClassOrderer.ClassName `ClassOrderer` that sorts classes alphanumerically based on their fully qualified names using `String#compareTo(String)`.
public static class	ClassOrderer.DisplayName `ClassOrderer` that sorts classes alphanumerically based on their display names using `String#compareTo(String)`
public static class	ClassOrderer.OrderAnnotation `ClassOrderer` that sorts classes based on the `@Order` annotation.
public static class	ClassOrderer.Random `ClassOrderer` that orders classes pseudo-randomly.

Field Summary

Modifier and Type	Field and Description
public static final String	DEFAULT_ORDER_PROPERTY_NAME Property name used to set the default class orderer class name: junit.jupiter.testclass.order.default Supported Values Supported values include fully qualified class names for types that implement `org.junit.jupiter.api.ClassOrderer`.

Method Summary

Modifier and Type	Method and Description
public void	orderClasses(ClassOrdererContext the `ClassOrdererContext` containing the class descriptors to order; never `null` context) Order the classes encapsulated in the supplied `ClassOrdererContext`.

Field Detail

DEFAULT_ORDER_PROPERTY_NAME back to summary

DEFAULT_ORDER_PROPERTY_NAME	back to summary
public static final String DEFAULT_ORDER_PROPERTY_NAME Property name used to set the default class orderer class name: junit.jupiter.testclass.order.default Supported Values Supported values include fully qualified class names for types that implement `org.junit.jupiter.api.ClassOrderer`. If not specified, test classes are not ordered unless test classes are annotated with `@TestClassOrder`. Annotations @API status:STABLE since:5.9 Since 5.8

public static final String DEFAULT_ORDER_PROPERTY_NAME

Property name used to set the default class orderer class name: junit.jupiter.testclass.order.default

Supported Values

Supported values include fully qualified class names for types that implement org.junit.jupiter.api.ClassOrderer.

If not specified, test classes are not ordered unless test classes are annotated with @TestClassOrder.

Annotations

@API
status:STABLE
since:5.9

Since: 5.8

Method Detail

orderClasses back to summary

orderClasses	back to summary
public void orderClasses(ClassOrdererContext context) Order the classes encapsulated in the supplied `ClassOrdererContext`. The classes to order or sort are made indirectly available via `ClassOrdererContext#getClassDescriptors()`. Since this method has a `void` return type, the list of class descriptors must be modified directly. For example, a simplified implementation of the `ClassOrderer.Random` `ClassOrderer` might look like the following. public void orderClasses(ClassOrdererContext context) { Collections.shuffle(context.getClassDescriptors()); } Parameters context:ClassOrdererContext the `ClassOrdererContext` containing the class descriptors to order; never `null`

public void orderClasses(ClassOrdererContext context)

Order the classes encapsulated in the supplied ClassOrdererContext.

The classes to order or sort are made indirectly available via ClassOrdererContext#getClassDescriptors(). Since this method has a void return type, the list of class descriptors must be modified directly.

For example, a simplified implementation of the ClassOrderer.Random ClassOrderer might look like the following.

public void orderClasses(ClassOrdererContext context) {
    Collections.shuffle(context.getClassDescriptors());
}

Parameters

context:ClassOrdererContext: the ClassOrdererContext containing the class descriptors to order; never null

org.junit.jupiter.api back to summary

public Class ClassOrderer.ClassName

Class Inheritance

extends Object
implements ClassOrderer

java.lang.Object
org.junit.jupiter.api.ClassOrderer.ClassName

All Implemented Interfaces

org.junit.jupiter.api.ClassOrderer

ClassOrderer that sorts classes alphanumerically based on their fully qualified names using String#compareTo(String).

Field Summary

Modifier and Type	Field and Description
private static final Comparator<ClassDescriptor>	comparator

Constructor Summary

Access	Constructor and Description
public	ClassName()

Method Summary

Modifier and Type	Method and Description
public void	orderClasses(ClassOrdererContext the `ClassOrdererContext` containing the class descriptors to order; never `null` context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Sort the classes encapsulated in the supplied `ClassOrdererContext` alphanumerically based on their fully qualified names.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

comparator	back to summary
private static final Comparator<ClassDescriptor> comparator

Constructor Detail

ClassName	back to summary
public ClassName()

Method Detail

orderClasses back to summary

orderClasses	back to summary
public void orderClasses(ClassOrdererContext context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Sort the classes encapsulated in the supplied `ClassOrdererContext` alphanumerically based on their fully qualified names. Parameters context:ClassOrdererContext Doc from org.junit.jupiter.api.ClassOrderer.orderClasses. the `ClassOrdererContext` containing the class descriptors to order; never `null` Annotations @Override

public void orderClasses(ClassOrdererContext context)

Implements org.junit.jupiter.api.ClassOrderer.orderClasses.

Sort the classes encapsulated in the supplied ClassOrdererContext alphanumerically based on their fully qualified names.

Parameters

context:ClassOrdererContext

Doc from org.junit.jupiter.api.ClassOrderer.orderClasses.

the ClassOrdererContext containing the class descriptors to order; never null

Annotations

@Override

org.junit.jupiter.api back to summary

public Class ClassOrderer.DisplayName

Class Inheritance

extends Object
implements ClassOrderer

java.lang.Object
org.junit.jupiter.api.ClassOrderer.DisplayName

All Implemented Interfaces

org.junit.jupiter.api.ClassOrderer

ClassOrderer that sorts classes alphanumerically based on their display names using String#compareTo(String)

Field Summary

Modifier and Type	Field and Description
private static final Comparator<ClassDescriptor>	comparator

Constructor Summary

Access	Constructor and Description
public	DisplayName()

Method Summary

Modifier and Type	Method and Description
public void	orderClasses(ClassOrdererContext the `ClassOrdererContext` containing the class descriptors to order; never `null` context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Sort the classes encapsulated in the supplied `ClassOrdererContext` alphanumerically based on their display names.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

comparator	back to summary
private static final Comparator<ClassDescriptor> comparator

Constructor Detail

DisplayName	back to summary
public DisplayName()

Method Detail

orderClasses back to summary

orderClasses	back to summary
public void orderClasses(ClassOrdererContext context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Sort the classes encapsulated in the supplied `ClassOrdererContext` alphanumerically based on their display names. Parameters context:ClassOrdererContext Doc from org.junit.jupiter.api.ClassOrderer.orderClasses. the `ClassOrdererContext` containing the class descriptors to order; never `null` Annotations @Override

public void orderClasses(ClassOrdererContext context)

Implements org.junit.jupiter.api.ClassOrderer.orderClasses.

Sort the classes encapsulated in the supplied ClassOrdererContext alphanumerically based on their display names.

Parameters

context:ClassOrdererContext

Doc from org.junit.jupiter.api.ClassOrderer.orderClasses.

the ClassOrdererContext containing the class descriptors to order; never null

Annotations

@Override

org.junit.jupiter.api back to summary

public Class ClassOrderer.OrderAnnotation

Class Inheritance

extends Object
implements ClassOrderer

java.lang.Object
org.junit.jupiter.api.ClassOrderer.OrderAnnotation

All Implemented Interfaces

org.junit.jupiter.api.ClassOrderer

ClassOrderer that sorts classes based on the @Order annotation.

Any classes that are assigned the same order value will be sorted arbitrarily adjacent to each other.

Any classes not annotated with @Order will be assigned the default order value which will effectively cause them to appear at the end of the sorted list, unless certain classes are assigned an explicit order value greater than the default order value. Any classes assigned an explicit order value greater than the default order value will appear after non-annotated classes in the sorted list.

Constructor Summary

Access	Constructor and Description
public	OrderAnnotation()

Method Summary

Modifier and Type	Method and Description
private static int	getOrder(ClassDescriptor descriptor)
public void	orderClasses(ClassOrdererContext the `ClassOrdererContext` containing the class descriptors to order; never `null` context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Sort the classes encapsulated in the supplied `ClassOrdererContext` based on the `@Order` annotation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

OrderAnnotation	back to summary
public OrderAnnotation()

Method Detail

getOrder	back to summary
private static int getOrder(ClassDescriptor descriptor)

orderClasses back to summary

orderClasses	back to summary
public void orderClasses(ClassOrdererContext context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Sort the classes encapsulated in the supplied `ClassOrdererContext` based on the `@Order` annotation. Parameters context:ClassOrdererContext Doc from org.junit.jupiter.api.ClassOrderer.orderClasses. the `ClassOrdererContext` containing the class descriptors to order; never `null` Annotations @Override

public void orderClasses(ClassOrdererContext context)

Implements org.junit.jupiter.api.ClassOrderer.orderClasses.

Sort the classes encapsulated in the supplied ClassOrdererContext based on the @Order annotation.

Parameters

context:ClassOrdererContext

Doc from org.junit.jupiter.api.ClassOrderer.orderClasses.

the ClassOrdererContext containing the class descriptors to order; never null

Annotations

@Override

org.junit.jupiter.api back to summary

public Class ClassOrderer.Random

Class Inheritance

extends Object
implements ClassOrderer

java.lang.Object
org.junit.jupiter.api.ClassOrderer.Random

All Implemented Interfaces

org.junit.jupiter.api.ClassOrderer

ClassOrderer that orders classes pseudo-randomly.

Custom Seed

By default, the random seed used for ordering classes is the value returned by System#nanoTime() during static initialization of this class. In order to support repeatable builds, the value of the default random seed is logged at CONFIG level. In addition, a custom seed (potentially the default seed from the previous test plan execution) may be specified via the junit.jupiter.execution.order.random.seed configuration parameter which can be supplied via the Launcher API, build tools (e.g., Gradle and Maven), a JVM system property, or the JUnit Platform configuration file (i.e., a file named junit-platform.properties in the root of the class path). Consult the User Guide for further information.

See Also: Random#RANDOM_SEED_PROPERTY_NAME, java.util.Random

Field Summary

Modifier and Type	Field and Description
private static final long	DEFAULT_SEED Default seed, which is generated during initialization of this class via `System#nanoTime()` for reproducibility of tests.
private static final Logger	logger
public static final String	RANDOM_SEED_PROPERTY_NAME Property name used to set the random seed used by this `ClassOrderer`: junit.jupiter.execution.order.random.seed The same property is used by `MethodOrderer.Random` for consistency between the two random orderers.

Constructor Summary

Access	Constructor and Description
public	Random()

Method Summary

Modifier and Type	Method and Description
private Optional<Long>	getCustomSeed(ClassOrdererContext context)
public void	orderClasses(ClassOrdererContext the `ClassOrdererContext` containing the class descriptors to order; never `null` context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Order the classes encapsulated in the supplied `ClassOrdererContext` pseudo-randomly.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

DEFAULT_SEED	back to summary
private static final long DEFAULT_SEED Default seed, which is generated during initialization of this class via `System#nanoTime()` for reproducibility of tests.

logger	back to summary
private static final Logger logger

RANDOM_SEED_PROPERTY_NAME back to summary

RANDOM_SEED_PROPERTY_NAME	back to summary
public static final String RANDOM_SEED_PROPERTY_NAME Property name used to set the random seed used by this `ClassOrderer`: junit.jupiter.execution.order.random.seed The same property is used by `MethodOrderer.Random` for consistency between the two random orderers. Supported Values Supported values include any string that can be converted to a `Long` via `Long#valueOf(String)`. If not specified or if the specified value cannot be converted to a `Long`, the default random seed will be used (see the class-level Javadoc for details). See Also `MethodOrderer.Random`

public static final String RANDOM_SEED_PROPERTY_NAME

Property name used to set the random seed used by this ClassOrderer: junit.jupiter.execution.order.random.seed

The same property is used by MethodOrderer.Random for consistency between the two random orderers.

Supported Values

Supported values include any string that can be converted to a Long via Long#valueOf(String).

If not specified or if the specified value cannot be converted to a Long, the default random seed will be used (see the class-level Javadoc for details).

See Also: MethodOrderer.Random

Constructor Detail

Random	back to summary
public Random()

Method Detail

getCustomSeed	back to summary
private Optional<Long> getCustomSeed(ClassOrdererContext context)

orderClasses back to summary

orderClasses	back to summary
public void orderClasses(ClassOrdererContext context) Implements org.junit.jupiter.api.ClassOrderer.orderClasses. Order the classes encapsulated in the supplied `ClassOrdererContext` pseudo-randomly. Parameters context:ClassOrdererContext Doc from org.junit.jupiter.api.ClassOrderer.orderClasses. the `ClassOrdererContext` containing the class descriptors to order; never `null` Annotations @Override

public void orderClasses(ClassOrdererContext context)

Implements org.junit.jupiter.api.ClassOrderer.orderClasses.

Order the classes encapsulated in the supplied ClassOrdererContext pseudo-randomly.

Parameters

context:ClassOrdererContext

Doc from org.junit.jupiter.api.ClassOrderer.orderClasses.

the ClassOrdererContext containing the class descriptors to order; never null

Annotations

@Override

public Interface ClassOrderer

Built-in Implementations

Nested and Inner Type Summary

Field Summary

Method Summary

Field Detail

Supported Values

Method Detail

public Class ClassOrderer.ClassName

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class ClassOrderer.DisplayName

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class ClassOrderer.OrderAnnotation

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public Class ClassOrderer.Random

Custom Seed

Field Summary

Constructor Summary

Method Summary

Field Detail

Supported Values

Constructor Detail

Method Detail