Introduce ExtensionContext.getEnclosingTestClasses()

documentation/src/docs/asciidoc/release-notes/index.adoc

@@ -19,4 +19,6 @@ include::{includedir}/link-attributes.adoc[]
 
 include::{basedir}/release-notes-5.13.0-M1.adoc[]
 
+include::{basedir}/release-notes-5.12.1.adoc[]
+
 include::{basedir}/release-notes-5.12.0.adoc[]

documentation/src/docs/asciidoc/release-notes/release-notes-5.12.1.adoc

@@ -0,0 +1,69 @@
+[[release-notes-5.12.1]]
+== 5.12.1
+
+*Date of Release:* ❓
+
+*Scope:* ❓
+
+For a complete list of all _closed_ issues and pull requests for this release, consult the
+link:{junit5-repo}+/milestone/91?closed=1+[5.12.1] milestone page in the JUnit repository
+on GitHub.
+
+
+[[release-notes-5.12.1-junit-platform]]
+=== JUnit Platform
+
+[[release-notes-5.12.1-junit-platform-bug-fixes]]
+==== Bug Fixes
+
+* ❓
+
+[[release-notes-5.12.1-junit-platform-deprecations-and-breaking-changes]]
+==== Deprecations and Breaking Changes
+
+* ❓
+
+[[release-notes-5.12.1-junit-platform-new-features-and-improvements]]
+==== New Features and Improvements
+
+* ❓
+
+
+[[release-notes-5.12.1-junit-jupiter]]
+=== JUnit Jupiter
+
+[[release-notes-5.12.1-junit-jupiter-bug-fixes]]
+==== Bug Fixes
+
+* ❓
+
+[[release-notes-5.12.1-junit-jupiter-deprecations-and-breaking-changes]]
+==== Deprecations and Breaking Changes
+
+* ❓
+
+[[release-notes-5.12.1-junit-jupiter-new-features-and-improvements]]
+==== New Features and Improvements
+
+* New `ExtensionContext.getEnclosingTestClasses()` method to help with migration away from
+  `AnnotationSupport.findAnnotation(Class, Class, SearchOption)` (deprecated since 1.12.0)
+  to `AnnotationSupport.findAnnotation(Class, Class, List)`.
+
+
+[[release-notes-5.12.1-junit-vintage]]
+=== JUnit Vintage
+
+[[release-notes-5.12.1-junit-vintage-bug-fixes]]
+==== Bug Fixes
+
+* ❓
+
+[[release-notes-5.12.1-junit-vintage-deprecations-and-breaking-changes]]
+==== Deprecations and Breaking Changes
+
+* ❓
+
+[[release-notes-5.12.1-junit-vintage-new-features-and-improvements]]
+==== New Features and Improvements
+
+* ❓

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtensionContext.java

@@ -40,6 +40,8 @@
  * <p>{@link Extension Extensions} are provided an instance of
  * {@code ExtensionContext} to perform their work.
  *
+ * <p>This interface is not intended to be implemented by clients.
+ *
  * @since 5.0
  * @see Store
  * @see Namespace
@@ -129,6 +131,31 @@ public interface ExtensionContext {
 	 */
 	Optional<Class<?>> getTestClass();
 
+	/**
+	 * Get the enclosing test classes of the current test or container.
+	 *
+	 * <p>This method is useful to look up annotations on nested test classes
+	 * and their enclosing <em>runtime</em> types:
+	 *
+	 * <pre>{@code
+	 * AnnotationSupport.findAnnotation(
+	 *     extensionContext.getRequiredTestClass(),
+	 *     MyAnnotation.class,
+	 *     extensionContext.getEnclosingTestClasses()
+	 * );
+	 * }</pre>
+	 *
+	 * @return an empty list if there is no class associated with the current
+	 * test or container or when it is not nested; otherwise, a list containing
+	 * the enclosing test classes in order from outermost to innermost; never
+	 * {@code null}
+	 *
+	 * @since 5.12.1
+	 * @see org.junit.platform.commons.support.AnnotationSupport#findAnnotation(Class, Class, List)
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12.1")
+	List<Class<?>> getEnclosingTestClasses();
+
 	/**
 	 * Get the <em>required</em> {@link Class} associated with the current test
 	 * or container.

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/ClassExtensionContext.java

@@ -12,6 +12,7 @@
 
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
+import java.util.List;
 import java.util.Optional;
 
 import org.junit.jupiter.api.TestInstance.Lifecycle;
@@ -54,6 +55,11 @@ public Optional<Class<?>> getTestClass() {
 		return Optional.of(getTestDescriptor().getTestClass());
 	}
 
+	@Override
+	public List<Class<?>> getEnclosingTestClasses() {
+		return getTestDescriptor().getEnclosingTestClasses();
+	}
+
 	@Override
 	public Optional<Lifecycle> getTestInstanceLifecycle() {
 		return Optional.of(this.lifecycle);

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/ClassTemplateInvocationExtensionContext.java

@@ -12,6 +12,7 @@
 
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
+import java.util.List;
 import java.util.Optional;
 
 import org.junit.jupiter.api.TestInstance.Lifecycle;
@@ -44,6 +45,11 @@ public Optional<Class<?>> getTestClass() {
 		return Optional.of(getTestDescriptor().getTestClass());
 	}
 
+	@Override
+	public List<Class<?>> getEnclosingTestClasses() {
+		return getTestDescriptor().getEnclosingTestClasses();
+	}
+
 	@Override
 	public Optional<Lifecycle> getTestInstanceLifecycle() {
 		return getParent().flatMap(ExtensionContext::getTestInstanceLifecycle);

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/DynamicExtensionContext.java

@@ -10,8 +10,11 @@
 
 package org.junit.jupiter.engine.descriptor;
 
+import static java.util.Collections.emptyList;
+
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
+import java.util.List;
 import java.util.Optional;
 
 import org.junit.jupiter.api.TestInstance;
@@ -40,6 +43,11 @@ public Optional<Class<?>> getTestClass() {
 		return Optional.empty();
 	}
 
+	@Override
+	public List<Class<?>> getEnclosingTestClasses() {
+		return emptyList();
+	}
+
 	@Override
 	public Optional<TestInstance.Lifecycle> getTestInstanceLifecycle() {
 		return Optional.empty();

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/JupiterEngineExtensionContext.java

@@ -10,8 +10,11 @@
 
 package org.junit.jupiter.engine.descriptor;
 
+import static java.util.Collections.emptyList;
+
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
+import java.util.List;
 import java.util.Optional;
 
 import org.junit.jupiter.api.TestInstance.Lifecycle;
@@ -43,6 +46,11 @@ public Optional<Class<?>> getTestClass() {
 		return Optional.empty();
 	}
 
+	@Override
+	public List<Class<?>> getEnclosingTestClasses() {
+		return emptyList();
+	}
+
 	@Override
 	public Optional<Lifecycle> getTestInstanceLifecycle() {
 		return Optional.empty();

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/MethodBasedTestDescriptor.java

@@ -50,7 +50,8 @@
  * @since 5.0
  */
 @API(status = INTERNAL, since = "5.0")
-public abstract class MethodBasedTestDescriptor extends JupiterTestDescriptor implements ResourceLockAware {
+public abstract class MethodBasedTestDescriptor extends JupiterTestDescriptor
+		implements ResourceLockAware, TestClassAware {
 
 	private static final Logger logger = LoggerFactory.getLogger(MethodBasedTestDescriptor.class);
 
@@ -106,7 +107,8 @@ public Function<ResourceLocksProvider, Set<ResourceLocksProvider.Lock>> getResou
 				getTestMethod()));
 	}
 
-	private List<Class<?>> getEnclosingTestClasses() {
+	@Override
+	public List<Class<?>> getEnclosingTestClasses() {
 		return getParent() //
 				.filter(TestClassAware.class::isInstance) //
 				.map(TestClassAware.class::cast) //

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/MethodExtensionContext.java

@@ -12,6 +12,7 @@
 
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
+import java.util.List;
 import java.util.Optional;
 
 import org.junit.jupiter.api.TestInstance.Lifecycle;
@@ -51,6 +52,11 @@ public Optional<Class<?>> getTestClass() {
 		return Optional.of(getTestDescriptor().getTestClass());
 	}
 
+	@Override
+	public List<Class<?>> getEnclosingTestClasses() {
+		return getTestDescriptor().getEnclosingTestClasses();
+	}
+
 	@Override
 	public Optional<Lifecycle> getTestInstanceLifecycle() {
 		return getParent().flatMap(ExtensionContext::getTestInstanceLifecycle);

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/TestTemplateExtensionContext.java

@@ -12,6 +12,7 @@
 
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
+import java.util.List;
 import java.util.Optional;
 
 import org.junit.jupiter.api.TestInstance.Lifecycle;
@@ -47,6 +48,11 @@ public Optional<Class<?>> getTestClass() {
 		return Optional.of(getTestDescriptor().getTestClass());
 	}
 
+	@Override
+	public List<Class<?>> getEnclosingTestClasses() {
+		return getTestDescriptor().getEnclosingTestClasses();
+	}
+
 	@Override
 	public Optional<Lifecycle> getTestInstanceLifecycle() {
 		return getParent().flatMap(ExtensionContext::getTestInstanceLifecycle);

junit-platform-commons/src/main/java/org/junit/platform/commons/support/AnnotationSupport.java

@@ -165,7 +165,7 @@ public static <A extends Annotation> Optional<A> findAnnotation(AnnotatedElement
 	 * @since 1.8
 	 * @see SearchOption
 	 * @see #findAnnotation(AnnotatedElement, Class)
-	 * @deprecated Use {@link #findAnnotation(Class, Class, List)}
+	 * @deprecated Use {@link #findAnnotation(AnnotatedElement, Class)}
 	 * (for {@code SearchOption.DEFAULT}) or
 	 * {@link #findAnnotation(Class, Class, List)} (for
 	 * {@code SearchOption.INCLUDE_ENCLOSING_CLASSES}) instead