Skip to content

Commit 4544de3

Browse files
marcphilippmarcphilipp
committed
Document wrapping for lifecycle callback extensions
Based on the excellent work of @sbrannen in the user guide. Resolves #1620.
1 parent 29c7ad9 commit 4544de3

File tree

7 files changed

+109
-1
lines changed

7 files changed

+109
-1
lines changed

‎documentation/src/docs/asciidoc/user-guide/extensions.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -636,7 +636,7 @@ please consult the respective Javadoc for each annotation and extension.
636636

637637
JUnit Jupiter always guarantees _wrapping_ behavior for multiple registered extensions
638638
that implement lifecycle callbacks such as `BeforeAllCallback`, `AfterAllCallback`,
639-
`BeforeEachCallback`, `AfterAllCallback`, `BeforeTestExecutionCallback`, and
639+
`BeforeEachCallback`, `AfterEachCallback`, `BeforeTestExecutionCallback`, and
640640
`AfterTestExecutionCallback`.
641641

642642
That means that, given two extensions `Extension1` and `Extension2` with `Extension1`

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterAllCallback.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,24 @@
2929
* <p>Consult the documentation in {@link Extension} for details on
3030
* constructor requirements.
3131
*
32+
* <h3>Wrapping Behavior</h3>
33+
*
34+
* <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
35+
* registered extensions that implement lifecycle callbacks such as
36+
* {@link BeforeAllCallback}, {@link AfterAllCallback},
37+
* {@link BeforeEachCallback}, {@link AfterEachCallback},
38+
* {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
39+
*
40+
* <p>That means that, given two extensions {@code Extension1} and
41+
* {@code Extension2} with {@code Extension1} registered before
42+
* {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
43+
* are guaranteed to execute before any "before" callbacks implemented by
44+
* {@code Extension2}. Similarly, given the two same two extensions registered
45+
* in the same order, any "after" callbacks implemented by {@code Extension1}
46+
* are guaranteed to execute after any "after" callbacks implemented by
47+
* {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
48+
* {@code Extension2}.
49+
*
3250
* @since 5.0
3351
* @see org.junit.jupiter.api.AfterAll
3452
* @see BeforeAllCallback

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterEachCallback.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,24 @@
3131
* <p>Consult the documentation in {@link Extension} for details on
3232
* constructor requirements.
3333
*
34+
* <h3>Wrapping Behavior</h3>
35+
*
36+
* <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
37+
* registered extensions that implement lifecycle callbacks such as
38+
* {@link BeforeAllCallback}, {@link AfterAllCallback},
39+
* {@link BeforeEachCallback}, {@link AfterEachCallback},
40+
* {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
41+
*
42+
* <p>That means that, given two extensions {@code Extension1} and
43+
* {@code Extension2} with {@code Extension1} registered before
44+
* {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
45+
* are guaranteed to execute before any "before" callbacks implemented by
46+
* {@code Extension2}. Similarly, given the two same two extensions registered
47+
* in the same order, any "after" callbacks implemented by {@code Extension1}
48+
* are guaranteed to execute after any "after" callbacks implemented by
49+
* {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
50+
* {@code Extension2}.
51+
*
3452
* @since 5.0
3553
* @see org.junit.jupiter.api.AfterEach
3654
* @see BeforeEachCallback

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterTestExecutionCallback.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,24 @@
3030
* <p>Consult the documentation in {@link Extension} for details on
3131
* constructor requirements.
3232
*
33+
* <h3>Wrapping Behavior</h3>
34+
*
35+
* <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
36+
* registered extensions that implement lifecycle callbacks such as
37+
* {@link BeforeAllCallback}, {@link AfterAllCallback},
38+
* {@link BeforeEachCallback}, {@link AfterEachCallback},
39+
* {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
40+
*
41+
* <p>That means that, given two extensions {@code Extension1} and
42+
* {@code Extension2} with {@code Extension1} registered before
43+
* {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
44+
* are guaranteed to execute before any "before" callbacks implemented by
45+
* {@code Extension2}. Similarly, given the two same two extensions registered
46+
* in the same order, any "after" callbacks implemented by {@code Extension1}
47+
* are guaranteed to execute after any "after" callbacks implemented by
48+
* {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
49+
* {@code Extension2}.
50+
*
3351
* @since 5.0
3452
* @see org.junit.jupiter.api.Test
3553
* @see BeforeTestExecutionCallback

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeAllCallback.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,24 @@
2929
* <p>Consult the documentation in {@link Extension} for details on
3030
* constructor requirements.
3131
*
32+
* <h3>Wrapping Behavior</h3>
33+
*
34+
* <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
35+
* registered extensions that implement lifecycle callbacks such as
36+
* {@link BeforeAllCallback}, {@link AfterAllCallback},
37+
* {@link BeforeEachCallback}, {@link AfterEachCallback},
38+
* {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
39+
*
40+
* <p>That means that, given two extensions {@code Extension1} and
41+
* {@code Extension2} with {@code Extension1} registered before
42+
* {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
43+
* are guaranteed to execute before any "before" callbacks implemented by
44+
* {@code Extension2}. Similarly, given the two same two extensions registered
45+
* in the same order, any "after" callbacks implemented by {@code Extension1}
46+
* are guaranteed to execute after any "after" callbacks implemented by
47+
* {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
48+
* {@code Extension2}.
49+
*
3250
* @since 5.0
3351
* @see org.junit.jupiter.api.BeforeAll
3452
* @see AfterAllCallback

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeEachCallback.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,24 @@
2929
* <p>Consult the documentation in {@link Extension} for details on
3030
* constructor requirements.
3131
*
32+
* <h3>Wrapping Behavior</h3>
33+
*
34+
* <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
35+
* registered extensions that implement lifecycle callbacks such as
36+
* {@link BeforeAllCallback}, {@link AfterAllCallback},
37+
* {@link BeforeEachCallback}, {@link AfterEachCallback},
38+
* {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
39+
*
40+
* <p>That means that, given two extensions {@code Extension1} and
41+
* {@code Extension2} with {@code Extension1} registered before
42+
* {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
43+
* are guaranteed to execute before any "before" callbacks implemented by
44+
* {@code Extension2}. Similarly, given the two same two extensions registered
45+
* in the same order, any "after" callbacks implemented by {@code Extension1}
46+
* are guaranteed to execute after any "after" callbacks implemented by
47+
* {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
48+
* {@code Extension2}.
49+
*
3250
* @since 5.0
3351
* @see org.junit.jupiter.api.BeforeEach
3452
* @see AfterEachCallback

‎junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,24 @@
3030
* <p>Consult the documentation in {@link Extension} for details on
3131
* constructor requirements.
3232
*
33+
* <h3>Wrapping Behavior</h3>
34+
*
35+
* <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
36+
* registered extensions that implement lifecycle callbacks such as
37+
* {@link BeforeAllCallback}, {@link AfterAllCallback},
38+
* {@link BeforeEachCallback}, {@link AfterEachCallback},
39+
* {@link BeforeTestExecutionCallback}, and {@link AfterTestExecutionCallback}.
40+
*
41+
* <p>That means that, given two extensions {@code Extension1} and
42+
* {@code Extension2} with {@code Extension1} registered before
43+
* {@code Extension2}, any "before" callbacks implemented by {@code Extension1}
44+
* are guaranteed to execute before any "before" callbacks implemented by
45+
* {@code Extension2}. Similarly, given the two same two extensions registered
46+
* in the same order, any "after" callbacks implemented by {@code Extension1}
47+
* are guaranteed to execute after any "after" callbacks implemented by
48+
* {@code Extension2}. {@code Extension1} is therefore said to <em>wrap</em>
49+
* {@code Extension2}.
50+
*
3351
* @since 5.0
3452
* @see org.junit.jupiter.api.Test
3553
* @see AfterTestExecutionCallback

0 commit comments

Comments
 (0)