From 4544de38863e2abd2c52d4b430e3915184d11939 Mon Sep 17 00:00:00 2001
From: Marc Philipp <mail@marcphilipp.de>
Date: Thu, 7 Feb 2019 20:54:02 +0100
Subject: [PATCH] Document wrapping for lifecycle callback extensions

Based on the excellent work of @sbrannen in the user guide.

Resolves #1620.
---
 .../docs/asciidoc/user-guide/extensions.adoc   |  2 +-
 .../api/extension/AfterAllCallback.java        | 18 ++++++++++++++++++
 .../api/extension/AfterEachCallback.java       | 18 ++++++++++++++++++
 .../extension/AfterTestExecutionCallback.java  | 18 ++++++++++++++++++
 .../api/extension/BeforeAllCallback.java       | 18 ++++++++++++++++++
 .../api/extension/BeforeEachCallback.java      | 18 ++++++++++++++++++
 .../extension/BeforeTestExecutionCallback.java | 18 ++++++++++++++++++
 7 files changed, 109 insertions(+), 1 deletion(-)

diff --git a/documentation/src/docs/asciidoc/user-guide/extensions.adoc b/documentation/src/docs/asciidoc/user-guide/extensions.adoc
index 75191714f4eb..7859a4e49c96 100644
--- 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
index 126a197b0516..83a22fea13a6 100644
--- 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
index 88174dd16839..7953fa418dc5 100644
--- 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/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterTestExecutionCallback.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterTestExecutionCallback.java
index 4dc89c455448..d5a5e237a7aa 100644
--- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterTestExecutionCallback.java
+++ b/junit-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
index da26708cacaa..b032481b5fdf 100644
--- 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
index 27c7f097608c..ce03af82206c 100644
--- 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/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.java
index 4aaea3e9fa07..e35e4188c250 100644
--- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.java
+++ b/junit-jupiter-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