By default, test methods will be ordered using an algorithm that is + * deterministic but intentionally nonobvious. This ensures that subsequent runs + * of a test suite execute test methods in the same order, thereby allowing for + * repeatable builds. In this context, a test method is any instance + * method that is directly annotated or meta-annotated with {@code @Test}, + * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or + * {@code @TestTemplate}. + * + *
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 + * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}. + * + *
To control the order in which test methods are executed, annotate your + * test class or test interface with {@link TestMethodOrder @TestMethodOrder} + * and specify the desired {@link MethodOrderer} implementation. + * * @since 5.0 * @see DisplayName * @see RepetitionInfo diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java index fd18a5fcd8c8..cfa67305c572 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java @@ -32,11 +32,36 @@ * resolved by {@link org.junit.jupiter.api.extension.ParameterResolver * ParameterResolvers}. * - *
{@code @Test} may also be used as a meta-annotation in order to - * create a custom composed annotation that inherits the semantics - * of {@code @Test}. + *
{@code @Test} may also be used as a meta-annotation in order to create + * a custom composed annotation that inherits the semantics of + * {@code @Test}. + * + *
By default, test methods will be ordered using an algorithm that is + * deterministic but intentionally nonobvious. This ensures that subsequent runs + * of a test suite execute test methods in the same order, thereby allowing for + * repeatable builds. In this context, a test method is any instance + * method that is directly annotated or meta-annotated with {@code @Test}, + * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or + * {@code @TestTemplate}. + * + *
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 + * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}. + * + *
To control the order in which test methods are executed, annotate your + * test class or test interface with {@link TestMethodOrder @TestMethodOrder} + * and specify the desired {@link MethodOrderer} implementation. * * @since 5.0 + * @see RepeatedTest + * @see org.junit.jupiter.params.ParameterizedTest + * @see TestTemplate + * @see TestFactory * @see TestInfo * @see DisplayName * @see Tag diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java index 5d572dad6ad3..17e6a57d4f46 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java @@ -43,6 +43,27 @@ * resolved by {@link org.junit.jupiter.api.extension.ParameterResolver * ParameterResolvers}. * + *
By default, test methods will be ordered using an algorithm that is + * deterministic but intentionally nonobvious. This ensures that subsequent runs + * of a test suite execute test methods in the same order, thereby allowing for + * repeatable builds. In this context, a test method is any instance + * method that is directly annotated or meta-annotated with {@code @Test}, + * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or + * {@code @TestTemplate}. + * + *
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 + * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}. + * + *
To control the order in which test methods are executed, annotate your + * test class or test interface with {@link TestMethodOrder @TestMethodOrder} + * and specify the desired {@link MethodOrderer} implementation. + * * @since 5.0 * @see Test * @see DynamicNode diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java index 21c237320aa8..9bb103043f88 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java @@ -49,6 +49,27 @@ * create a custom composed annotation that inherits the semantics * of {@code @TestTemplate}. * + *
By default, test methods will be ordered using an algorithm that is + * deterministic but intentionally nonobvious. This ensures that subsequent runs + * of a test suite execute test methods in the same order, thereby allowing for + * repeatable builds. In this context, a test method is any instance + * method that is directly annotated or meta-annotated with {@code @Test}, + * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or + * {@code @TestTemplate}. + * + *
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 + * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}. + * + *
To control the order in which test methods are executed, annotate your + * test class or test interface with {@link TestMethodOrder @TestMethodOrder} + * and specify the desired {@link MethodOrderer} implementation. + * * @since 5.0 * @see Test * @see org.junit.jupiter.api.extension.TestTemplateInvocationContext diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java index da6ea158b650..ebea989de020 100644 --- a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java +++ b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java @@ -79,6 +79,29 @@ * to create a custom composed annotation that inherits the semantics * of {@code @ParameterizedTest}. * + *
By default, test methods will be ordered using an algorithm that is + * deterministic but intentionally nonobvious. This ensures that subsequent runs + * of a test suite execute test methods in the same order, thereby allowing for + * repeatable builds. In this context, a test method is any instance + * method that is directly annotated or meta-annotated with {@code @Test}, + * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or + * {@code @TestTemplate}. + * + *
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 + * {@link org.junit.jupiter.api.TestInstance @TestInstance(Lifecycle.PER_CLASS)}. + * + *
To control the order in which test methods are executed, annotate your + * test class or test interface with + * {@link org.junit.jupiter.api.TestMethodOrder @TestMethodOrder} and specify + * the desired {@link org.junit.jupiter.api.MethodOrderer MethodOrderer} + * implementation. + * * @since 5.0 * @see org.junit.jupiter.params.provider.Arguments * @see org.junit.jupiter.params.provider.ArgumentsProvider