Document execution order and wrapping behavior

Issue: #1620

Author: marcphilipp

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

@@ -38,7 +38,7 @@
  * methods may optionally declare parameters to be resolved by
  * {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolvers}.
  *
- * <h3>Inheritance</h3>
+ * <h3>Inheritance and Execution Order</h3>
  *
  * <p>{@code @AfterAll} methods are inherited from superclasses as long as
  * they are not <em>hidden</em> or <em>overridden</em>. Furthermore,
@@ -50,6 +50,27 @@
  * and {@code @AfterAll} methods from an interface will be executed after
  * {@code @AfterAll} methods in the class that implements the interface.
  *
+ * <p>JUnit Jupiter does not guarantee the execution order of multiple
+ * {@code @AfterAll} methods that are declared within a single test class or
+ * test interface. While it may at times appear that these methods are invoked
+ * in alphabetical order, they are in fact sorted using an algorithm that is
+ * deterministic but intentionally non-obvious.
+ *
+ * <p>In addition, {@code @AfterAll} methods are in no way linked to
+ * {@code @BeforeAll} methods. Consequently, there are no guarantees with regard
+ * to their <em>wrapping</em> behavior. For example, given two
+ * {@code @BeforeAll} methods {@code createA()} and {@code createB()} as well as
+ * two {@code @AfterAll} methods {@code destroyA()} and {@code destroyB()}, the
+ * order in which the {@code @BeforeAll} methods are executed (e.g.
+ * {@code createA()} before {@code createB()}) does not imply any order for the
+ * seemingly corresponding {@code @AfterAll} methods. In other words,
+ * {@code destroyA()} might be called before <em>or</em> after
+ * {@code destroyB()}. The JUnit Team therefore recommends that developers
+ * declare at most one {@code @BeforeAll} method and at most one
+ * {@code @AfterAll} method per test class or test interface unless there are no
+ * dependencies between the {@code @BeforeAll} methods or between the
+ * {@code @AfterAll} methods.
+ *
  * <h3>Composition</h3>
  *
  * <p>{@code @AfterAll} may be used as a meta-annotation in order to create

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

@@ -33,7 +33,7 @@
  * They may optionally declare parameters to be resolved by
  * {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolvers}.
  *
- * <h3>Inheritance</h3>
+ * <h3>Inheritance and Execution Order</h3>
  *
  * <p>{@code @AfterEach} methods are inherited from superclasses as long as
  * they are not overridden. Furthermore, {@code @AfterEach} methods from
@@ -44,6 +44,27 @@
  * {@code @AfterEach} default methods will be executed after {@code @AfterEach}
  * methods in the class that implements the interface.
  *
+ * <p>JUnit Jupiter does not guarantee the execution order of multiple
+ * {@code @AfterEach} methods that are declared within a single test class or
+ * test interface. While it may at times appear that these methods are invoked
+ * in alphabetical order, they are in fact sorted using an algorithm that is
+ * deterministic but intentionally non-obvious.
+ *
+ * <p>In addition, {@code @AfterEach} methods are in no way linked to
+ * {@code @BeforeEach} methods. Consequently, there are no guarantees with
+ * regard to their <em>wrapping</em> behavior. For example, given two
+ * {@code @BeforeEach} methods {@code createA()} and {@code createB()} as well
+ * as two {@code @AfterEach} methods {@code destroyA()} and {@code destroyB()},
+ * the order in which the {@code @BeforeEach} methods are executed (e.g.
+ * {@code createA()} before {@code createB()}) does not imply any order for the
+ * seemingly corresponding {@code @AfterEach} methods. In other words,
+ * {@code destroyA()} might be called before <em>or</em> after
+ * {@code destroyB()}. The JUnit Team therefore recommends that developers
+ * declare at most one {@code @BeforeEach} method and at most one
+ * {@code @AfterEach} method per test class or test interface unless there are
+ * no dependencies between the {@code @BeforeEach} methods or between the
+ * {@code @AfterEach} methods.
+ *
  * <h3>Composition</h3>
  *
  * <p>{@code @AfterEach} may be used as a meta-annotation in order to create

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

@@ -58,14 +58,15 @@
  *
  * <p>In addition, {@code @BeforeAll} methods are in no way linked to
  * {@code @AfterAll} methods. Consequently, there are no guarantees with regard
- * to their <em>wrapping</em> behavior. For example, given two {@code @BeforeAll}
- * methods {@code createA()} and {@code createB()} as well as two {@code @AfterAll}
- * methods {@code destroyA()} and {@code destroyB()}, the order in which the
- * {@code @BeforeAll} methods are executed (e.g. {@code createA()} before
- * {@code createB()}) does not imply any order for the seemingly corresponding
- * {@code @AfterAll} methods. In other words, {@code destroyA()} might be called
- * before <em>or</em> after {@code destroyB()}. The JUnit Team therefore recommends
- * that developers declare at most one {@code @BeforeAll} method and at most one
+ * to their <em>wrapping</em> behavior. For example, given two
+ * {@code @BeforeAll} methods {@code createA()} and {@code createB()} as well as
+ * two {@code @AfterAll} methods {@code destroyA()} and {@code destroyB()}, the
+ * order in which the {@code @BeforeAll} methods are executed (e.g.
+ * {@code createA()} before {@code createB()}) does not imply any order for the
+ * seemingly corresponding {@code @AfterAll} methods. In other words,
+ * {@code destroyA()} might be called before <em>or</em> after
+ * {@code destroyB()}. The JUnit Team therefore recommends that developers
+ * declare at most one {@code @BeforeAll} method and at most one
  * {@code @AfterAll} method per test class or test interface unless there are no
  * dependencies between the {@code @BeforeAll} methods or between the
  * {@code @AfterAll} methods.

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

@@ -33,7 +33,7 @@
  * They may optionally declare parameters to be resolved by
  * {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolvers}.
  *
- * <h3>Inheritance</h3>
+ * <h3>Inheritance and Execution Order</h3>
  *
  * <p>{@code @BeforeEach} methods are inherited from superclasses as long as
  * they are not overridden. Furthermore, {@code @BeforeEach} methods from
@@ -44,6 +44,27 @@
  * {@code @BeforeEach} default methods will be executed before {@code @BeforeEach}
  * methods in the class that implements the interface.
  *
+ * <p>JUnit Jupiter does not guarantee the execution order of multiple
+ * {@code @BeforeEach} methods that are declared within a single test class or
+ * test interface. While it may at times appear that these methods are invoked
+ * in alphabetical order, they are in fact sorted using an algorithm that is
+ * deterministic but intentionally non-obvious.
+ *
+ * <p>In addition, {@code @BeforeEach} methods are in no way linked to
+ * {@code @AfterEach} methods. Consequently, there are no guarantees with regard
+ * to their <em>wrapping</em> behavior. For example, given two
+ * {@code @BeforeEach} methods {@code createA()} and {@code createB()} as well
+ * as two {@code @AfterEach} methods {@code destroyA()} and {@code destroyB()},
+ * the order in which the {@code @BeforeEach} methods are executed (e.g.
+ * {@code createA()} before {@code createB()}) does not imply any order for the
+ * seemingly corresponding {@code @AfterEach} methods. In other words,
+ * {@code destroyA()} might be called before <em>or</em> after
+ * {@code destroyB()}. The JUnit Team therefore recommends that developers
+ * declare at most one {@code @BeforeEach} method and at most one
+ * {@code @AfterEach} method per test class or test interface unless there are
+ * no dependencies between the {@code @BeforeEach} methods or between the
+ * {@code @AfterEach} methods.
+ *
  * <h3>Composition</h3>
  *
  * <p>{@code @BeforeEach} may be used as a meta-annotation in order to create