Document semantics for a disabled test regarding class-level callbacks

Closes #3649

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-5.11.0-M1.adoc

@@ -51,6 +51,8 @@ repository on GitHub.
 ==== New Features and Improvements
 
 * `JAVA_23` has been added to the `JRE` enum for use with JRE-based execution conditions.
+* Improved documentation for semantics of a disabled test regarding class-level lifecycle
+  methods and callbacks.
 * New `@AutoClose` annotation that can be applied to fields within tests to automatically
   close the annotated resource after test execution. See the
   <<../user-guide/index.adoc#writing-tests-built-in-extensions-AutoClose, User Guide>> for

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

@@ -358,6 +358,15 @@ annotation, via one of the annotations discussed in
 <<writing-tests-conditional-execution>>, or via a custom <<extensions-conditions,
 `ExecutionCondition`>>.
 
+When `@Disabled` is applied at the class level, all test methods within that class are
+automatically disabled as well.
+
+If a test method is disabled via `@Disabled`, that prevents execution of the test method
+and method-level lifecycle callbacks such as `@BeforeEach` methods, `@AfterEach` methods,
+and corresponding extension APIs. However, that does not prevent the test class from being
+instantiated, and it does not prevent the execution of class-level lifecycle callbacks
+such as `@BeforeAll` methods, `@AfterAll` methods, and corresponding extension APIs.
+
 Here's a `@Disabled` test class.
 
 [source,java,indent=0]
@@ -393,17 +402,26 @@ superclass is `@Disabled`, you must redeclare `@Disabled` on the subclass.
 === Conditional Test Execution
 
 The <<extensions-conditions, `ExecutionCondition`>> extension API in JUnit Jupiter allows
-developers to either _enable_ or _disable_ a container or test based on certain
+developers to either _enable_ or _disable_ a test class or test method based on certain
 conditions _programmatically_. The simplest example of such a condition is the built-in
 `{DisabledCondition}` which supports the `{Disabled}` annotation (see
-<<writing-tests-disabling>>). In addition to `@Disabled`, JUnit Jupiter also supports
-several other annotation-based conditions in the `org.junit.jupiter.api.condition`
-package that allow developers to enable or disable containers and tests _declaratively_.
-When multiple `ExecutionCondition` extensions are registered, a container or test is
-disabled as soon as one of the conditions returns _disabled_. If you wish to provide
+<<writing-tests-disabling>>).
+
+In addition to `@Disabled`, JUnit Jupiter also supports several other annotation-based
+conditions in the `org.junit.jupiter.api.condition` package that allow developers to
+enable or disable test classes and test methods _declaratively_. If you wish to provide
 details about why they might be disabled, every annotation associated with these built-in
 conditions has a `disabledReason` attribute available for that purpose.
 
+When multiple `ExecutionCondition` extensions are registered, a test class or test method
+is disabled as soon as one of the conditions returns _disabled_. If a test class is
+disabled, all test methods within that class are automatically disabled as well. If a test
+method is disabled, that prevents execution of the test method and method-level lifecycle
+callbacks such as `@BeforeEach` methods, `@AfterEach` methods, and corresponding extension
+APIs. However, that does not prevent the test class from being instantiated, and it does
+not prevent the execution of class-level lifecycle callbacks such as `@BeforeAll` methods,
+`@AfterAll` methods, and corresponding extension APIs.
+
 See <<extensions-conditions, `ExecutionCondition`>> and the following sections for
 details.
 

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

@@ -34,11 +34,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>When applied at the method level, the presence of this annotation does not
- * prevent the test class from being instantiated. Rather, it prevents the
- * execution of the test method and method-level lifecycle callbacks such as
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
  * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
- * extension APIs.
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * @since 5.0
  * @see #value

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledForJreRange.java

@@ -33,10 +33,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>If a test method is disabled via this annotation, that does not prevent
- * the test class from being instantiated. Rather, it prevents the execution of
- * the test method and method-level lifecycle callbacks such as {@code @BeforeEach}
- * methods, {@code @AfterEach} methods, and corresponding extension APIs.
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
+ * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * <p>This annotation may be used as a meta-annotation in order to create a
  * custom <em>composed annotation</em> that inherits the semantics of this

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledIf.java

@@ -33,10 +33,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>If a test method is disabled via this annotation, that does not prevent
- * the test class from being instantiated. Rather, it prevents the execution of
- * the test method and method-level lifecycle callbacks such as {@code @BeforeEach}
- * methods, {@code @AfterEach} methods, and corresponding extension APIs.
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
+ * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * <p>This annotation may be used as a meta-annotation in order to create a
  * custom <em>composed annotation</em> that inherits the semantics of this

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledIfEnvironmentVariable.java

@@ -35,10 +35,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>If a test method is disabled via this annotation, that does not prevent
- * the test class from being instantiated. Rather, it prevents the execution of
- * the test method and method-level lifecycle callbacks such as {@code @BeforeEach}
- * methods, {@code @AfterEach} methods, and corresponding extension APIs.
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
+ * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * <p>If the specified environment variable is undefined, the presence of this
  * annotation will have no effect on whether or not the class or method

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledIfSystemProperty.java

@@ -35,10 +35,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>If a test method is disabled via this annotation, that does not prevent
- * the test class from being instantiated. Rather, it prevents the execution of
- * the test method and method-level lifecycle callbacks such as {@code @BeforeEach}
- * methods, {@code @AfterEach} methods, and corresponding extension APIs.
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
+ * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * <p>If the specified system property is undefined, the presence of this
  * annotation will have no effect on whether or not the class or method

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledInNativeImage.java

@@ -32,10 +32,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>If a test method is disabled via this annotation, that does not prevent
- * the test class from being instantiated. Rather, it prevents the execution of
- * the test method and method-level lifecycle callbacks such as {@code @BeforeEach}
- * methods, {@code @AfterEach} methods, and corresponding extension APIs.
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
+ * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * <p>This annotation may be used as a meta-annotation in order to create a
  * custom <em>composed annotation</em> that inherits the semantics of this

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledOnJre.java

@@ -33,10 +33,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>If a test method is disabled via this annotation, that does not prevent
- * the test class from being instantiated. Rather, it prevents the execution of
- * the test method and method-level lifecycle callbacks such as {@code @BeforeEach}
- * methods, {@code @AfterEach} methods, and corresponding extension APIs.
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
+ * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * <p>This annotation may be used as a meta-annotation in order to create a
  * custom <em>composed annotation</em> that inherits the semantics of this

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledOnOs.java

@@ -38,10 +38,13 @@
  * Consequently, if you wish to apply the same semantics to a subclass, this
  * annotation must be redeclared on the subclass.
  *
- * <p>If a test method is disabled via this annotation, that does not prevent
- * the test class from being instantiated. Rather, it prevents the execution of
- * the test method and method-level lifecycle callbacks such as {@code @BeforeEach}
- * methods, {@code @AfterEach} methods, and corresponding extension APIs.
+ * <p>If a test method is disabled via this annotation, that prevents execution
+ * of the test method and method-level lifecycle callbacks such as
+ * {@code @BeforeEach} methods, {@code @AfterEach} methods, and corresponding
+ * extension APIs. However, that does not prevent the test class from being
+ * instantiated, and it does not prevent the execution of class-level lifecycle
+ * callbacks such as {@code @BeforeAll} methods, {@code @AfterAll} methods, and
+ * corresponding extension APIs.
  *
  * <p>This annotation may be used as a meta-annotation in order to create a
  * custom <em>composed annotation</em> that inherits the semantics of this