Top Description Inners Fields Methods
org.junit.jupiter.api

public Interface ClassOrderer

Known Direct Implementers
org.junit.jupiter.api.ClassOrderer.Default, org.junit.jupiter.api.ClassOrderer.ClassName, org.junit.jupiter.api.ClassOrderer.DisplayName, org.junit.jupiter.api.ClassOrderer.OrderAnnotation, org.junit.jupiter.api.ClassOrderer.Random
Annotations
@API
status:STABLE
since:5.10
Static Imports
java.util.Comparator.comparingInt, org.apiguardian.api.API.Status.EXPERIMENTAL, .API.Status.STABLE

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.

Since
5.8
See Also
TestClassOrder, ClassOrdererContext, orderClasses(ClassOrdererContext), MethodOrderer

Nested and Inner Type Summary

Modifier and TypeClass 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.Default

ClassOrderer that allows to explicitly specify that the default ordering should be applied.

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 TypeField and Description
public static final String
DEFAULT_ORDER_PROPERTY_NAME

Property name used to set the default class orderer class name: Supported Values

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

Method Summary

Modifier and TypeMethod 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_NAMEback to summary
public static final String DEFAULT_ORDER_PROPERTY_NAME

Property name used to set the default class orderer class name:

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

orderClassesback 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

org.junit.jupiter.api back to summary

public Class ClassOrderer.ClassName

extends Object
implements ClassOrderer
Class Inheritance
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 TypeField and Description
private static final Comparator<ClassDescriptor>

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
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.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

comparatorback to summary
private static final Comparator<ClassDescriptor> comparator

Constructor Detail

ClassNameback to summary
public ClassName()

Method Detail

orderClassesback 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.

Annotations
@Override
org.junit.jupiter.api back to summary

public final Class ClassOrderer.Default

extends Object
implements ClassOrderer
Class Inheritance
All Implemented Interfaces
org.junit.jupiter.api.ClassOrderer
Annotations
@API
status:EXPERIMENTAL
since:6.0

ClassOrderer that allows to explicitly specify that the default ordering should be applied.

If the junit.jupiter.testclass.order.default is set, specifying this ClassOrderer has the same effect as referencing the configured class directly. Otherwise, it has the same effect as not specifying any ClassOrderer.

This class can be used to reset the ClassOrderer for a @Nested class and its @Nested inner classes, recursively, when a ClassOrderer is configured using @TestClassOrder on an enclosing class.

Since
6.0

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public void
orderClasses(ClassOrdererContext context)

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

Order the classes encapsulated in the supplied ClassOrdererContext.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Defaultback to summary
private Default()

Method Detail

orderClassesback to summary
public void orderClasses(ClassOrdererContext context)

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

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

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());
}
Annotations
@Override
org.junit.jupiter.api back to summary

public Class ClassOrderer.DisplayName

extends Object
implements ClassOrderer
Class Inheritance
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 TypeField and Description
private static final Comparator<ClassDescriptor>

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
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.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

comparatorback to summary
private static final Comparator<ClassDescriptor> comparator

Constructor Detail

DisplayNameback to summary
public DisplayName()

Method Detail

orderClassesback 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.

Annotations
@Override
org.junit.jupiter.api back to summary

public Class ClassOrderer.OrderAnnotation

extends Object
implements ClassOrderer
Class Inheritance
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

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
private static int
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.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

OrderAnnotationback to summary
public OrderAnnotation()

Method Detail

getOrderback to summary
private static int getOrder(ClassDescriptor descriptor)
orderClassesback 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.

Annotations
@Override
org.junit.jupiter.api back to summary

public Class ClassOrderer.Random

extends Object
implements ClassOrderer
Class Inheritance
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 class initialization. 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 TypeField and Description
private static final Logger
public static final String
RANDOM_SEED_PROPERTY_NAME

Property name used to set the random seed used by this ClassOrderer:

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

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public void
orderClasses(ClassOrdererContext context)

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

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

loggerback to summary
private static final Logger logger
RANDOM_SEED_PROPERTY_NAMEback to summary
public static final String RANDOM_SEED_PROPERTY_NAME

Property name used to set the random seed used by this ClassOrderer:

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

Randomback to summary
public Random()

Method Detail

orderClassesback to summary
public void orderClasses(ClassOrdererContext context)

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

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

Annotations
@Override