Update documentation regarding nested test class support

Closes gh-28579

Author: sbrannen

spring-test/src/main/java/org/springframework/test/annotation/Commit.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -34,8 +34,8 @@
  *
  * <p>When declared as a class-level annotation, {@code @Commit} defines
  * the default commit semantics for all test methods within the test class
- * hierarchy. When declared as a method-level annotation, {@code @Commit}
- * defines commit semantics for the specific test method, potentially
+ * hierarchy or nested class hierarchy. When declared as a method-level annotation,
+ * {@code @Commit} defines commit semantics for the specific test method, potentially
  * overriding class-level default commit or rollback semantics.
  *
  * <p><strong>Warning</strong>: {@code @Commit} can be used as direct

spring-test/src/main/java/org/springframework/test/annotation/Rollback.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -34,9 +34,9 @@
  *
  * <p>When declared as a class-level annotation, {@code @Rollback} defines
  * the default rollback semantics for all test methods within the test class
- * hierarchy. When declared as a method-level annotation, {@code @Rollback}
- * defines rollback semantics for the specific test method, potentially
- * overriding class-level default commit or rollback semantics.
+ * hierarchy or nested class hierarchy. When declared as a method-level annotation,
+ * {@code @Rollback} defines rollback semantics for the specific test method,
+ * potentially overriding class-level default commit or rollback semantics.
  *
  * <p>As of Spring Framework 4.2, {@code @Commit} can be used as direct
  * replacement for {@code @Rollback(false)}.

spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -78,17 +78,17 @@
 	Class<? extends ActiveProfilesResolver> resolver() default ActiveProfilesResolver.class;
 
 	/**
-	 * Whether or not bean definition profiles from superclasses should be
-	 * <em>inherited</em>.
-	 * <p>The default value is {@code true}, which means that a test
-	 * class will <em>inherit</em> bean definition profiles defined by a
-	 * test superclass. Specifically, the bean definition profiles for a test
-	 * class will be appended to the list of bean definition profiles
-	 * defined by a test superclass. Thus, subclasses have the option of
-	 * <em>extending</em> the list of bean definition profiles.
-	 * <p>If {@code inheritProfiles} is set to {@code false}, the bean
-	 * definition profiles for the test class will <em>shadow</em> and
-	 * effectively replace any bean definition profiles defined by a superclass.
+	 * Whether or not bean definition profiles from superclasses and enclosing
+	 * classes should be <em>inherited</em>.
+	 * <p>The default value is {@code true}, which means that a test class will
+	 * <em>inherit</em> bean definition profiles defined by a test superclass or
+	 * enclosing class. Specifically, the bean definition profiles for a test
+	 * class will be appended to the list of bean definition profiles defined by
+	 * a test superclass or enclosing class. Thus, subclasses and nested classes
+	 * have the option of <em>extending</em> the list of bean definition profiles.
+	 * <p>If {@code inheritProfiles} is set to {@code false}, the bean definition
+	 * profiles for the test class will <em>shadow</em> and effectively replace
+	 * any bean definition profiles defined by a superclass or enclosing class.
 	 * <p>In the following example, the {@code ApplicationContext} for
 	 * {@code BaseTest} will be loaded using only the &quot;base&quot;
 	 * bean definition profile; beans defined in the &quot;extended&quot; profile

spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -171,18 +171,19 @@
 	/**
 	 * Whether or not {@linkplain #locations resource locations} or
 	 * {@linkplain #classes <em>component classes</em>} from test superclasses
-	 * should be <em>inherited</em>.
+	 * and enclosing classes should be <em>inherited</em>.
 	 * <p>The default value is {@code true}. This means that an annotated test
 	 * class will <em>inherit</em> the resource locations or component classes
-	 * defined by test superclasses. Specifically, the resource locations or
-	 * component classes for a given test class will be appended to the list of
-	 * resource locations or component classes defined by test superclasses.
-	 * Thus, subclasses have the option of <em>extending</em> the list of resource
+	 * defined by test superclasses and enclosing classes. Specifically, the
+	 * resource locations or component classes for a given test class will be
+	 * appended to the list of resource locations or component classes defined
+	 * by test superclasses and enclosing classes. Thus, subclasses and nested
+	 * classes have the option of <em>extending</em> the list of resource
 	 * locations or component classes.
 	 * <p>If {@code inheritLocations} is set to {@code false}, the
 	 * resource locations or component classes for the annotated test class
 	 * will <em>shadow</em> and effectively replace any resource locations
-	 * or component classes defined by superclasses.
+	 * or component classes defined by superclasses and enclosing classes.
 	 * <p>In the following example that uses path-based resource locations, the
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}
 	 * for {@code ExtendedTest} will be loaded from
@@ -225,16 +226,16 @@
 
 	/**
 	 * Whether or not {@linkplain #initializers context initializers} from test
-	 * superclasses should be <em>inherited</em>.
+	 * superclasses and enclosing classes should be <em>inherited</em>.
 	 * <p>The default value is {@code true}. This means that an annotated test
 	 * class will <em>inherit</em> the application context initializers defined
-	 * by test superclasses. Specifically, the initializers for a given test
-	 * class will be added to the set of initializers defined by test
-	 * superclasses. Thus, subclasses have the option of <em>extending</em> the
-	 * set of initializers.
+	 * by test superclasses and enclosing classes. Specifically, the initializers
+	 * for a given test class will be added to the set of initializers defined by
+	 * test superclasses and enclosing classes. Thus, subclasses and nested classes
+	 * have the option of <em>extending</em> the set of initializers.
 	 * <p>If {@code inheritInitializers} is set to {@code false}, the initializers
 	 * for the annotated test class will <em>shadow</em> and effectively replace
-	 * any initializers defined by superclasses.
+	 * any initializers defined by superclasses and enclosing classes.
 	 * <p>In the following example, the
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}
 	 * for {@code ExtendedTest} will be initialized using
@@ -263,9 +264,10 @@
 	 * for loading an {@link org.springframework.context.ApplicationContext
 	 * ApplicationContext}.
 	 * <p>If not specified, the loader will be inherited from the first superclass
-	 * that is annotated or meta-annotated with {@code @ContextConfiguration} and
-	 * specifies an explicit loader. If no class in the hierarchy specifies an
-	 * explicit loader, a default loader will be used instead.
+	 * or enclosing class that is annotated or meta-annotated with
+	 * {@code @ContextConfiguration} and specifies an explicit loader. If no class
+	 * in the type hierarchy or enclosing class hierarchy specifies an explicit
+	 * loader, a default loader will be used instead.
 	 * <p>The default concrete implementation chosen at runtime will be either
 	 * {@link org.springframework.test.context.support.DelegatingSmartContextLoader
 	 * DelegatingSmartContextLoader} or
@@ -290,10 +292,12 @@
 	 * <p>If not specified the name will be inferred based on the numerical level
 	 * within all declared contexts within the hierarchy.
 	 * <p>This attribute is only applicable when used within a test class hierarchy
-	 * that is configured using {@code @ContextHierarchy}, in which case the name
-	 * can be used for <em>merging</em> or <em>overriding</em> this configuration
-	 * with configuration of the same name in hierarchy levels defined in superclasses.
-	 * See the Javadoc for {@link ContextHierarchy @ContextHierarchy} for details.
+	 * or enclosing class hierarchy that is configured using
+	 * {@code @ContextHierarchy}, in which case the name can be used for
+	 * <em>merging</em> or <em>overriding</em> this configuration with configuration
+	 * of the same name in hierarchy levels defined in superclasses or enclosing
+	 * classes. See the Javadoc for {@link ContextHierarchy @ContextHierarchy} for
+	 * details.
 	 * @since 3.2.2
 	 */
 	String name() default "";

spring-test/src/main/java/org/springframework/test/context/ContextCustomizerFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -46,7 +46,7 @@ public interface ContextCustomizerFactory {
 	 * @param testClass the test class
 	 * @param configAttributes the list of context configuration attributes for
 	 * the test class, ordered <em>bottom-up</em> (i.e., as if we were traversing
-	 * up the class hierarchy); never {@code null} or empty
+	 * up the class hierarchy or enclosing class hierarchy); never {@code null} or empty
 	 * @return a {@link ContextCustomizer} or {@code null} if no customizer should
 	 * be used
 	 */

spring-test/src/main/java/org/springframework/test/context/MergedContextConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,16 +31,16 @@
 import org.springframework.util.StringUtils;
 
 /**
- * {@code MergedContextConfiguration} encapsulates the <em>merged</em>
- * context configuration declared on a test class and all of its superclasses
- * via {@link ContextConfiguration @ContextConfiguration},
+ * {@code MergedContextConfiguration} encapsulates the <em>merged</em> context
+ * configuration declared on a test class and all of its superclasses and
+ * enclosing classes via {@link ContextConfiguration @ContextConfiguration},
  * {@link ActiveProfiles @ActiveProfiles}, and
  * {@link TestPropertySource @TestPropertySource}.
  *
  * <p>Merged context resource locations, annotated classes, active profiles,
  * property resource locations, and in-lined properties represent all declared
- * values in the test class hierarchy taking into consideration the semantics
- * of the {@link ContextConfiguration#inheritLocations},
+ * values in the test class hierarchy and enclosing class hierarchy taking into
+ * consideration the semantics of the {@link ContextConfiguration#inheritLocations},
  * {@link ActiveProfiles#inheritProfiles},
  * {@link TestPropertySource#inheritLocations}, and
  * {@link TestPropertySource#inheritProperties} flags.

spring-test/src/main/java/org/springframework/test/context/TestContextBootstrapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -126,7 +126,8 @@ public interface TestContextBootstrapper {
 	 * flag of {@link TestExecutionListeners @TestExecutionListeners} must be
 	 * taken into consideration. Specifically, if the {@code inheritListeners}
 	 * flag is set to {@code true}, listeners declared for a given test class must
-	 * be appended to the end of the list of listeners declared in superclasses.
+	 * be appended to the end of the list of listeners declared in superclasses
+	 * or enclosing classes.
 	 * @return a list of {@code TestExecutionListener} instances
 	 */
 	List<TestExecutionListener> getTestExecutionListeners();

spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -79,15 +79,16 @@
 
 	/**
 	 * Whether or not {@link #listeners TestExecutionListeners} from superclasses
-	 * should be <em>inherited</em>.
-	 * <p>The default value is {@code true}, which means that an annotated
-	 * class will <em>inherit</em> the listeners defined by an annotated
-	 * superclass. Specifically, the listeners for an annotated class will be
-	 * appended to the list of listeners defined by an annotated superclass.
-	 * Thus, subclasses have the option of <em>extending</em> the list of
-	 * listeners. In the following example, {@code AbstractBaseTest} will
-	 * be configured with {@code DependencyInjectionTestExecutionListener}
-	 * and {@code DirtiesContextTestExecutionListener}; whereas,
+	 * and enclosing classes should be <em>inherited</em>.
+	 * <p>The default value is {@code true}, which means that an annotated class
+	 * will <em>inherit</em> the listeners defined by an annotated superclass or
+	 * enclosing class. Specifically, the listeners for an annotated class will be
+	 * appended to the list of listeners defined by an annotated superclass or
+	 * enclosing class. Thus, subclasses and nested classes have the option of
+	 * <em>extending</em> the list of listeners. In the following example,
+	 * {@code AbstractBaseTest} will be configured with
+	 * {@code DependencyInjectionTestExecutionListener} and
+	 * {@code DirtiesContextTestExecutionListener}; whereas,
 	 * {@code TransactionalTest} will be configured with
 	 * {@code DependencyInjectionTestExecutionListener},
 	 * {@code DirtiesContextTestExecutionListener}, <strong>and</strong>
@@ -107,18 +108,19 @@
 	 * }</pre>
 	 * <p>If {@code inheritListeners} is set to {@code false}, the listeners for
 	 * the annotated class will <em>shadow</em> and effectively replace any
-	 * listeners defined by a superclass.
+	 * listeners defined by a superclass or enclosing class.
 	 */
 	boolean inheritListeners() default true;
 
 	/**
 	 * The <em>merge mode</em> to use when {@code @TestExecutionListeners} is
-	 * declared on a class that does <strong>not</strong> inherit listeners
-	 * from a superclass.
+	 * declared on a class that does <strong>not</strong> inherit listeners from
+	 * a superclass or enclosing class.
 	 * <p>Can be set to {@link MergeMode#MERGE_WITH_DEFAULTS MERGE_WITH_DEFAULTS}
 	 * to have locally declared listeners <em>merged</em> with the default
 	 * listeners.
-	 * <p>The mode is ignored if listeners are inherited from a superclass.
+	 * <p>The mode is ignored if listeners are inherited from a superclass or
+	 * enclosing class.
 	 * <p>Defaults to {@link MergeMode#REPLACE_DEFAULTS REPLACE_DEFAULTS}
 	 * for backwards compatibility.
 	 * @see MergeMode
@@ -131,7 +133,8 @@
 	 * Enumeration of <em>modes</em> that dictate whether or not explicitly
 	 * declared listeners are merged with the default listeners when
 	 * {@code @TestExecutionListeners} is declared on a class that does
-	 * <strong>not</strong> inherit listeners from a superclass.
+	 * <strong>not</strong> inherit listeners from a superclass or enclosing
+	 * class.
 	 * @since 4.1
 	 */
 	enum MergeMode {

spring-test/src/main/java/org/springframework/test/context/TestPropertySource.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -151,16 +151,18 @@
 
 	/**
 	 * Whether or not test property source {@link #locations} from superclasses
-	 * should be <em>inherited</em>.
+	 * and enclosing classes should be <em>inherited</em>.
 	 * <p>The default value is {@code true}, which means that a test class will
-	 * <em>inherit</em> property source locations defined by a superclass.
-	 * Specifically, the property source locations for a test class will be
-	 * appended to the list of property source locations defined by a superclass.
-	 * Thus, subclasses have the option of <em>extending</em> the list of test
-	 * property source locations.
+	 * <em>inherit</em> property source locations defined by a superclass or
+	 * enclosing class. Specifically, the property source locations for a test
+	 * class will be appended to the list of property source locations defined
+	 * by a superclass or enclosing class. Thus, subclasses and nested classes
+	 * have the option of <em>extending</em> the list of test property source
+	 * locations.
 	 * <p>If {@code inheritLocations} is set to {@code false}, the property
 	 * source locations for the test class will <em>shadow</em> and effectively
-	 * replace any property source locations defined by a superclass.
+	 * replace any property source locations defined by a superclass or
+	 * enclosing class.
 	 * <p>In the following example, the {@code ApplicationContext} for
 	 * {@code BaseTest} will be loaded using only the {@code "base.properties"}
 	 * file as a test property source. In contrast, the {@code ApplicationContext}
@@ -228,16 +230,17 @@
 	String[] properties() default {};
 
 	/**
-	 * Whether or not inlined test {@link #properties} from superclasses should
-	 * be <em>inherited</em>.
+	 * Whether or not inlined test {@link #properties} from superclasses and
+	 * enclosing classes should be <em>inherited</em>.
 	 * <p>The default value is {@code true}, which means that a test class will
-	 * <em>inherit</em> inlined properties defined by a superclass. Specifically,
-	 * the inlined properties for a test class will be appended to the list of
-	 * inlined properties defined by a superclass. Thus, subclasses have the
-	 * option of <em>extending</em> the list of inlined test properties.
+	 * <em>inherit</em> inlined properties defined by a superclass or enclosing
+	 * class. Specifically, the inlined properties for a test class will be
+	 * appended to the list of inlined properties defined by a superclass or
+	 * enclosing class. Thus, subclasses and nested classes have the option of
+	 * <em>extending</em> the list of inlined test properties.
 	 * <p>If {@code inheritProperties} is set to {@code false}, the inlined
 	 * properties for the test class will <em>shadow</em> and effectively
-	 * replace any inlined properties defined by a superclass.
+	 * replace any inlined properties defined by a superclass or enclosing class.
 	 * <p>In the following example, the {@code ApplicationContext} for
 	 * {@code BaseTest} will be loaded using only the inlined {@code key1}
 	 * property. In contrast, the {@code ApplicationContext} for
@@ -261,7 +264,7 @@
 	 * test class hierarchy (i.e., directly present or meta-present on a test
 	 * class) are considered to be <em>local</em> annotations, in contrast to
 	 * {@code @TestPropertySource} annotations that are inherited from a
-	 * superclass.</li>
+	 * superclass or enclosing class.</li>
 	 * <li>All local {@code @TestPropertySource} annotations must declare the
 	 * same value for the {@code inheritProperties} flag.</li>
 	 * <li>The {@code inheritProperties} flag is not taken into account between

spring-test/src/main/java/org/springframework/test/context/event/RecordApplicationEvents.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -36,6 +36,10 @@
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
+ * <p>This annotation will be inherited from an enclosing test class by default. See
+ * {@link org.springframework.test.context.NestedTestConfiguration @NestedTestConfiguration}
+ * for details.
+ *
  * @author Sam Brannen
  * @since 5.3.3
  * @see ApplicationEvents