Document wrapping for lifecycle callback extensions

Based on the excellent work of @sbrannen in the user guide. Resolves #1620.
junit-team · Feb 7, 2019 · 4544de3 · sbrannen · Feb 8, 2019 · 4544de3
1 parent 29c7ad9
commit 4544de3
Show file tree

Hide file tree

Showing 7 changed files with 109 additions and 1 deletion.
diff --git a/documentation/src/docs/asciidoc/user-guide/extensions.adoc b/documentation/src/docs/asciidoc/user-guide/extensions.adoc
@@ -636,7 +636,7 @@ please consult the respective Javadoc for each annotation and extension.
 
 JUnit Jupiter always guarantees _wrapping_ behavior for multiple registered extensions
 that implement lifecycle callbacks such as `BeforeAllCallback`, `AfterAllCallback`,
-`BeforeEachCallback`, `AfterAllCallback`, `BeforeTestExecutionCallback`, and
+`BeforeEachCallback`, `AfterEachCallback`, `BeforeTestExecutionCallback`, and
 `AfterTestExecutionCallback`.
 
 That means that, given two extensions `Extension1` and `Extension2` with `Extension1`

diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterAllCallback.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterAllCallback.java
@@ -29,6 +29,24 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h3>Wrapping Behavior</h3>
+ *
+ * <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
+ * registered extensions that implement lifecycle callbacks such as
+ * {@link BeforeAllCallback}, {@link AfterAllCallback},
+ * {@link BeforeEachCallback}, {@link AfterEachCallback},
+ * {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
+ *
+ * <p>That means that, given two extensions {@code Extension1} and
+ * {@code Extension2} with {@code Extension1} registered before
+ * {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute before any "before" callbacks implemented by
+ * {@code Extension2}. Similarly, given the two same two extensions registered
+ * in the same order, any "after" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute after any "after" callbacks implemented by
+ * {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
+ * {@code Extension2}.
+ *
  * @since 5.0
  * @see org.junit.jupiter.api.AfterAll
  * @see BeforeAllCallback

diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterEachCallback.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterEachCallback.java
@@ -31,6 +31,24 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h3>Wrapping Behavior</h3>
+ *
+ * <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
+ * registered extensions that implement lifecycle callbacks such as
+ * {@link BeforeAllCallback}, {@link AfterAllCallback},
+ * {@link BeforeEachCallback}, {@link AfterEachCallback},
+ * {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
+ *
+ * <p>That means that, given two extensions {@code Extension1} and
+ * {@code Extension2} with {@code Extension1} registered before
+ * {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute before any "before" callbacks implemented by
+ * {@code Extension2}. Similarly, given the two same two extensions registered
+ * in the same order, any "after" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute after any "after" callbacks implemented by
+ * {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
+ * {@code Extension2}.
+ *
  * @since 5.0
  * @see org.junit.jupiter.api.AfterEach
  * @see BeforeEachCallback

diff --git a/...jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterTestExecutionCallback.java b/...jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterTestExecutionCallback.java
@@ -30,6 +30,24 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h3>Wrapping Behavior</h3>
+ *
+ * <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
+ * registered extensions that implement lifecycle callbacks such as
+ * {@link BeforeAllCallback}, {@link AfterAllCallback},
+ * {@link BeforeEachCallback}, {@link AfterEachCallback},
+ * {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
+ *
+ * <p>That means that, given two extensions {@code Extension1} and
+ * {@code Extension2} with {@code Extension1} registered before
+ * {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute before any "before" callbacks implemented by
+ * {@code Extension2}. Similarly, given the two same two extensions registered
+ * in the same order, any "after" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute after any "after" callbacks implemented by
+ * {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
+ * {@code Extension2}.
+ *
  * @since 5.0
  * @see org.junit.jupiter.api.Test
  * @see BeforeTestExecutionCallback

diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeAllCallback.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeAllCallback.java
@@ -29,6 +29,24 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h3>Wrapping Behavior</h3>
+ *
+ * <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
+ * registered extensions that implement lifecycle callbacks such as
+ * {@link BeforeAllCallback}, {@link AfterAllCallback},
+ * {@link BeforeEachCallback}, {@link AfterEachCallback},
+ * {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
+ *
+ * <p>That means that, given two extensions {@code Extension1} and
+ * {@code Extension2} with {@code Extension1} registered before
+ * {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute before any "before" callbacks implemented by
+ * {@code Extension2}. Similarly, given the two same two extensions registered
+ * in the same order, any "after" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute after any "after" callbacks implemented by
+ * {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
+ * {@code Extension2}.
+ *
  * @since 5.0
  * @see org.junit.jupiter.api.BeforeAll
  * @see AfterAllCallback

diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeEachCallback.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeEachCallback.java
@@ -29,6 +29,24 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h3>Wrapping Behavior</h3>
+ *
+ * <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
+ * registered extensions that implement lifecycle callbacks such as
+ * {@link BeforeAllCallback}, {@link AfterAllCallback},
+ * {@link BeforeEachCallback}, {@link AfterEachCallback},
+ * {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
+ *
+ * <p>That means that, given two extensions {@code Extension1} and
+ * {@code Extension2} with {@code Extension1} registered before
+ * {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute before any "before" callbacks implemented by
+ * {@code Extension2}. Similarly, given the two same two extensions registered
+ * in the same order, any "after" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute after any "after" callbacks implemented by
+ * {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
+ * {@code Extension2}.
+ *
  * @since 5.0
  * @see org.junit.jupiter.api.BeforeEach
  * @see AfterEachCallback

diff --git a/...upiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.java b/...upiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.java
@@ -30,6 +30,24 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h3>Wrapping Behavior</h3>
+ *
+ * <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
+ * registered extensions that implement lifecycle callbacks such as
+ * {@link BeforeAllCallback}, {@link AfterAllCallback},
+ * {@link BeforeEachCallback}, {@link AfterEachCallback},
+ * {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
+ *
+ * <p>That means that, given two extensions {@code Extension1} and
+ * {@code Extension2} with {@code Extension1} registered before
+ * {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute before any "before" callbacks implemented by
+ * {@code Extension2}. Similarly, given the two same two extensions registered
+ * in the same order, any "after" callbacks implemented by {@code Extension1}
+ * are guaranteed to execute after any "after" callbacks implemented by
+ * {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
+ * {@code Extension2}.
+ *
  * @since 5.0
  * @see org.junit.jupiter.api.Test
  * @see AfterTestExecutionCallback