From 4a608e97dcadbe2a8f2767abb6a32eca5c051352 Mon Sep 17 00:00:00 2001
From: Sam Brannen <sbrannen@vmware.com>
Date: Tue, 13 Oct 2020 10:35:51 +0200
Subject: [PATCH] Cross reference @NestedTestConfiguration and supported
 annotations

See gh-19930
---
 .../test/annotation/Commit.java               |  7 +++++-
 .../test/annotation/DirtiesContext.java       |  7 +++++-
 .../test/annotation/Rollback.java             |  7 +++++-
 .../test/context/ActiveProfiles.java          |  6 ++++-
 .../test/context/BootstrapWith.java           |  6 ++++-
 .../test/context/ContextConfiguration.java    |  6 ++++-
 .../test/context/ContextHierarchy.java        |  6 ++++-
 .../test/context/NestedTestConfiguration.java | 22 +++++++++++++++----
 .../test/context/TestConstructor.java         |  4 ++++
 .../test/context/TestExecutionListeners.java  |  6 ++++-
 .../test/context/TestPropertySource.java      |  3 +++
 .../test/context/TestPropertySources.java     |  6 ++++-
 .../test/context/web/WebAppConfiguration.java |  7 +++++-
 13 files changed, 79 insertions(+), 14 deletions(-)

diff --git a/spring-test/src/main/java/org/springframework/test/annotation/Commit.java b/spring-test/src/main/java/org/springframework/test/annotation/Commit.java
index dae764b1f01..9e881a5de4d 100644
--- a/spring-test/src/main/java/org/springframework/test/annotation/Commit.java
+++ b/spring-test/src/main/java/org/springframework/test/annotation/Commit.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -44,6 +44,11 @@ import java.lang.annotation.Target;
  * {@code @Commit} and {@code @Rollback} on the same test method or on the
  * same test class is unsupported and may lead to unpredictable results.
  *
+ * <p>As of Spring Framework 5.3, 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 4.2
  * @see Rollback
diff --git a/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java b/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java
index 78f884b0b92..9441c9133d3 100644
--- a/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java
+++ b/spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -43,6 +43,11 @@ import java.lang.annotation.Target;
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link org.springframework.test.context.NestedTestConfiguration @NestedTestConfiguration}
+ * for details.
+ *
  * <h3>Supported Test Phases</h3>
  * <ul>
  * <li><strong>Before current test class</strong>: when declared at the class
diff --git a/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java b/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java
index 03156e9f271..a7bd5c06415 100644
--- a/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java
+++ b/spring-test/src/main/java/org/springframework/test/annotation/Rollback.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -49,6 +49,11 @@ import java.lang.annotation.Target;
  * custom <em>composed annotations</em>. Consult the source code for
  * {@link Commit @Commit} for a concrete example.
  *
+ * <p>As of Spring Framework 5.3, 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 2.5
  * @see Commit
diff --git a/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java b/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java
index 9ad1e3068aa..0bc4a2987d0 100644
--- a/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java
+++ b/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-2020 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,6 +34,10 @@ import org.springframework.core.annotation.AliasFor;
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
+ *
  * @author Sam Brannen
  * @since 3.1
  * @see SmartContextLoader
diff --git a/spring-test/src/main/java/org/springframework/test/context/BootstrapWith.java b/spring-test/src/main/java/org/springframework/test/context/BootstrapWith.java
index d85427a54ce..1a00c818d45 100644
--- a/spring-test/src/main/java/org/springframework/test/context/BootstrapWith.java
+++ b/spring-test/src/main/java/org/springframework/test/context/BootstrapWith.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -33,6 +33,10 @@ import java.lang.annotation.Target;
  * present</em> on the current test class) will override any meta-present
  * declarations of {@code @BootstrapWith}.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
+ *
  * @author Sam Brannen
  * @since 4.1
  * @see BootstrapContext
diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java
index e90c8d9be24..9eaabcb4f03 100644
--- a/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java
+++ b/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -75,6 +75,10 @@ import org.springframework.core.annotation.AliasFor;
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see org.springframework.test.context.junit.jupiter.SpringJUnitConfig @SpringJUnitConfig
diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java b/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java
index 1e49e9f1739..f4cee11b4b8 100644
--- a/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java
+++ b/spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -134,6 +134,10 @@ import java.lang.annotation.Target;
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
+ *
  * @author Sam Brannen
  * @since 3.2.2
  * @see ContextConfiguration
diff --git a/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java
index 8071d85a942..a1e3db386a7 100644
--- a/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java
+++ b/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java
@@ -60,14 +60,28 @@ import org.springframework.lang.Nullable;
  * classes in JUnit Jupiter; however, there may be other testing frameworks with
  * support for nested test classes that could also make use of this annotation.
  *
+ * <h3>Supported Annotations</h3>
+ * <p>The <em>Spring TestContext Framework</em> honors {@code @NestedTestConfiguration}
+ * semantics for the following annotations.
+ * <ul>
+ * <li>{@link BootstrapWith @BootstrapWith}</li>
+ * <li>{@link TestExecutionListeners @TestExecutionListeners}</li>
+ * <li>{@link ContextConfiguration @ContextConfiguration}</li>
+ * <li>{@link ContextHierarchy @ContextHierarchy}</li>
+ * <li>{@link org.springframework.test.context.web.WebAppConfiguration @WebAppConfiguration}</li>
+ * <li>{@link ActiveProfiles @ActiveProfiles}</li>
+ * <li>{@link TestPropertySource @TestPropertySource}</li>
+ * <li>{@link org.springframework.test.annotation.DirtiesContext @DirtiesContext}</li>
+ * <li>{@link org.springframework.transaction.annotation.Transactional @Transactional}</li>
+ * <li>{@link org.springframework.test.annotation.Rollback @Rollback}</li>
+ * <li>{@link org.springframework.test.annotation.Commit @Commit}</li>
+ * <li>{@link TestConstructor @TestConstructor}</li>
+ * </ul>
+ *
  * @author Sam Brannen
  * @since 5.3
  * @see EnclosingConfiguration#INHERIT
  * @see EnclosingConfiguration#OVERRIDE
- * @see ContextConfiguration @ContextConfiguration
- * @see ContextHierarchy @ContextHierarchy
- * @see ActiveProfiles @ActiveProfiles
- * @see TestPropertySource @TestPropertySource
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/spring-test/src/main/java/org/springframework/test/context/TestConstructor.java b/spring-test/src/main/java/org/springframework/test/context/TestConstructor.java
index 3956f6f585d..a2747456289 100644
--- a/spring-test/src/main/java/org/springframework/test/context/TestConstructor.java
+++ b/spring-test/src/main/java/org/springframework/test/context/TestConstructor.java
@@ -53,6 +53,10 @@ import org.springframework.lang.Nullable;
  * {@link org.springframework.test.context.junit.jupiter.web.SpringJUnitWebConfig @SpringJUnitWebConfig}
  * or various test-related annotations from Spring Boot Test.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
+ *
  * @author Sam Brannen
  * @since 5.2
  * @see org.springframework.beans.factory.annotation.Autowired @Autowired
diff --git a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java b/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java
index 4056cadeaa6..b1b38149d1d 100644
--- a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java
+++ b/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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 @@ import org.springframework.core.annotation.AliasFor;
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see TestExecutionListener
diff --git a/spring-test/src/main/java/org/springframework/test/context/TestPropertySource.java b/spring-test/src/main/java/org/springframework/test/context/TestPropertySource.java
index 6315da3851b..f74b9c5c626 100644
--- a/spring-test/src/main/java/org/springframework/test/context/TestPropertySource.java
+++ b/spring-test/src/main/java/org/springframework/test/context/TestPropertySource.java
@@ -78,6 +78,9 @@ import org.springframework.core.annotation.AliasFor;
  * annotation since the {@code locations} and {@code inheritLocations} attributes
  * of both annotations can lead to ambiguity during the attribute resolution
  * process.</li>
+ * <li>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.</li>
  * </ul>
  *
  * @author Sam Brannen
diff --git a/spring-test/src/main/java/org/springframework/test/context/TestPropertySources.java b/spring-test/src/main/java/org/springframework/test/context/TestPropertySources.java
index 486ea15cae1..8aee4028664 100644
--- a/spring-test/src/main/java/org/springframework/test/context/TestPropertySources.java
+++ b/spring-test/src/main/java/org/springframework/test/context/TestPropertySources.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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,6 +31,10 @@ import java.lang.annotation.Target;
  * completely optional since {@code @TestPropertySource} is a
  * {@linkplain java.lang.annotation.Repeatable repeatable} annotation.
  *
+ * <p>As of Spring Framework 5.3, this annotation will be inherited from an
+ * enclosing test class by default. See
+ * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
+ *
  * @author Anatoliy Korovin
  * @author Sam Brannen
  * @since 5.2
diff --git a/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java
index 4df60f17755..7b5e4520b1c 100644
--- a/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java
+++ b/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -41,6 +41,11 @@ import java.lang.annotation.Target;
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
+ * <p>As of Spring Framework 5.3, 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 3.2
  * @see org.springframework.web.context.WebApplicationContext