Document test method execution order in Javadoc

Issue: #13

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -425,7 +425,7 @@ or meta-annotated with `@Test`, `@RepeatedTest`, `@ParameterizedTest`, `@TestFac
 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
+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

junit-jupiter-api/src/main/java/org/junit/jupiter/api/RepeatedTest.java

@@ -43,6 +43,27 @@
  * create a custom <em>composed annotation</em> that inherits the semantics
  * of {@code @RepeatedTest}.
  *
+ * <h3>Test Execution Order</h3>
+ *
+ * <p>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 <em>test method</em> is any instance
+ * method that is directly annotated or meta-annotated with {@code @Test},
+ * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or
+ * {@code @TestTemplate}.
+ *
+ * <p>Although true <em>unit tests</em> 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 &mdash; for example, when writing
+ * <em>integration tests</em> or <em>functional tests</em> where the sequence of
+ * the tests is important, especially in conjunction with
+ * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}.
+ *
+ * <p>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

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}.
  *
- * <p>{@code @Test} may also be used as a meta-annotation in order to
- * create a custom <em>composed annotation</em> that inherits the semantics
- * of {@code @Test}.
+ * <p>{@code @Test} may also be used as a meta-annotation in order to create
+ * a custom <em>composed annotation</em> that inherits the semantics of
+ * {@code @Test}.
+ *
+ * <h3>Test Execution Order</h3>
+ *
+ * <p>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 <em>test method</em> is any instance
+ * method that is directly annotated or meta-annotated with {@code @Test},
+ * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or
+ * {@code @TestTemplate}.
+ *
+ * <p>Although true <em>unit tests</em> 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 &mdash; for example, when writing
+ * <em>integration tests</em> or <em>functional tests</em> where the sequence of
+ * the tests is important, especially in conjunction with
+ * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}.
+ *
+ * <p>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

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}.
  *
+ * <h3>Test Execution Order</h3>
+ *
+ * <p>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 <em>test method</em> is any instance
+ * method that is directly annotated or meta-annotated with {@code @Test},
+ * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or
+ * {@code @TestTemplate}.
+ *
+ * <p>Although true <em>unit tests</em> 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 &mdash; for example, when writing
+ * <em>integration tests</em> or <em>functional tests</em> where the sequence of
+ * the tests is important, especially in conjunction with
+ * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}.
+ *
+ * <p>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

junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java

@@ -49,6 +49,27 @@
  * create a custom <em>composed annotation</em> that inherits the semantics
  * of {@code @TestTemplate}.
  *
+ * <h3>Test Execution Order</h3>
+ *
+ * <p>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 <em>test method</em> is any instance
+ * method that is directly annotated or meta-annotated with {@code @Test},
+ * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or
+ * {@code @TestTemplate}.
+ *
+ * <p>Although true <em>unit tests</em> 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 &mdash; for example, when writing
+ * <em>integration tests</em> or <em>functional tests</em> where the sequence of
+ * the tests is important, especially in conjunction with
+ * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}.
+ *
+ * <p>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

junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java

@@ -79,6 +79,29 @@
  * to create a custom <em>composed annotation</em> that inherits the semantics
  * of {@code @ParameterizedTest}.
  *
+ * <h3>Test Execution Order</h3>
+ *
+ * <p>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 <em>test method</em> is any instance
+ * method that is directly annotated or meta-annotated with {@code @Test},
+ * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory}, or
+ * {@code @TestTemplate}.
+ *
+ * <p>Although true <em>unit tests</em> 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 &mdash; for example, when writing
+ * <em>integration tests</em> or <em>functional tests</em> where the sequence of
+ * the tests is important, especially in conjunction with
+ * {@link org.junit.jupiter.api.TestInstance @TestInstance(Lifecycle.PER_CLASS)}.
+ *
+ * <p>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