Document causes of concurrent execution being disabled by default

Resolves #3849.

Author: marcphilipp

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

@@ -2698,11 +2698,11 @@ junit.jupiter.execution.parallel.mode.default = concurrent
 
 The default execution mode is applied to all nodes of the test tree with a few notable
 exceptions, namely test classes that use the `Lifecycle.PER_CLASS` mode or a
-`{MethodOrderer}` (except for `{MethodOrderer_Random}`). In the former case, test authors
-have to ensure that the test class is thread-safe; in the latter, concurrent execution
-might conflict with the configured execution order. Thus, in both cases, test methods in
-such test classes are only executed concurrently if the `@Execution(CONCURRENT)`
-annotation is present on the test class or method.
+`{MethodOrderer}`. In the former case, test authors have to ensure that the test class is
+thread-safe; in the latter, concurrent execution might conflict with the configured
+execution order. Thus, in both cases, test methods in such test classes are only executed
+concurrently if the `@Execution(CONCURRENT)` annotation is present on the test class or
+method.
 
 When parallel execution is enabled and a default `{ClassOrderer}` is registered (see
 <<writing-tests-test-execution-order-classes>> for details), top-level test classes will

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

@@ -20,6 +20,7 @@
 import java.lang.annotation.Target;
 
 import org.apiguardian.api.API;
+import org.junit.jupiter.api.parallel.Execution;
 
 /**
  * {@code @TestInstance} is a type-level annotation that is used to configure
@@ -59,8 +60,14 @@
  * create a custom <em>composed annotation</em> that inherits the semantics
  * of {@code @TestInstance}.
  *
+ * <h2>Parallel Execution</h2>
+ * <p>Using the {@link Lifecycle#PER_CLASS PER_CLASS} lifecycle mode disables
+ * parallel execution unless the test class or test method is annotated with
+ * {@link Execution @Execution(CONCURRENT)}.
+ *
  * @since 5.0
  * @see Nested @Nested
+ * @see Execution @Execution
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)

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

@@ -20,6 +20,7 @@
 import java.lang.annotation.Target;
 
 import org.apiguardian.api.API;
+import org.junit.jupiter.api.parallel.Execution;
 
 /**
  * {@code @TestMethodOrder} is a type-level annotation that is used to configure
@@ -64,6 +65,11 @@
  * }
  * </pre>
  *
+ * <h2>Parallel Execution</h2>
+ * <p>Using a {@link MethodOrderer} disables parallel execution unless the test
+ * class or test method is annotated with
+ * {@link Execution @Execution(CONCURRENT)}.
+ *
  * @since 5.4
  * @see MethodOrderer
  * @see TestClassOrder

junit-jupiter-api/src/main/java/org/junit/jupiter/api/parallel/Execution.java

@@ -20,6 +20,8 @@
 import java.lang.annotation.Target;
 
 import org.apiguardian.api.API;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.TestInstance;
 
 /**
  * {@code @Execution} is used to configure the parallel execution
@@ -44,6 +46,12 @@
  * <p>{@value #DEFAULT_CLASSES_EXECUTION_MODE_PROPERTY_NAME} overrides
  * {@value #DEFAULT_EXECUTION_MODE_PROPERTY_NAME} for top-level classes.
  *
+ * <p>The default execution mode is not applied to classes that use the
+ * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle or a
+ * {@link MethodOrderer}. In both cases, test methods in such test classes are
+ * only executed concurrently if the {@code @Execution(CONCURRENT)} annotation
+ * is present on the test class or method.
+ *
  * @see Isolated
  * @see ResourceLock
  * @since 5.3