Introduce ExtensionContext.getEnclosingTestClasses()

Resolves #4375.

Author: marcphilipp

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

@@ -45,7 +45,9 @@ on GitHub.
 [[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-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;
@@ -68,6 +69,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/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

@@ -106,7 +106,7 @@ public Function<ResourceLocksProvider, Set<ResourceLocksProvider.Lock>> getResou
 getTestMethod()));
 }
 
-private List<Class<?>> getEnclosingTestClasses() {
+List<Class<?>> getEnclosingTestClasses() {
 return getParent() //
 .filter(ClassBasedTestDescriptor.class::isInstance) //
 .map(ClassBasedTestDescriptor.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);

jupiter-tests/src/test/java/org/junit/jupiter/engine/descriptor/ExtensionContextTests.java

@@ -39,6 +39,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayNameGenerator;
 import org.junit.jupiter.api.Named;
+import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.Extension;
@@ -111,33 +112,63 @@ void fromJupiterEngineDescriptor() {
 }
 
 @Test
-@SuppressWarnings("resource")
 void fromClassTestDescriptor() {
 var nestedClassDescriptor = nestedClassDescriptor();
 var outerClassDescriptor = outerClassDescriptor(nestedClassDescriptor);
+var doublyNestedClassDescriptor = doublyNestedClassDescriptor();
+var methodTestDescriptor = nestedMethodDescriptor();
+nestedClassDescriptor.addChild(doublyNestedClassDescriptor);
+nestedClassDescriptor.addChild(methodTestDescriptor);
 
 var outerExtensionContext = new ClassExtensionContext(null, null, outerClassDescriptor, configuration,
 extensionRegistry, null);
 
 // @formatter:off
 assertAll("outerContext",
-() -> assertThat(outerExtensionContext.getElement()).contains(OuterClass.class),
-() -> assertThat(outerExtensionContext.getTestClass()).contains(OuterClass.class),
+() -> assertThat(outerExtensionContext.getElement()).contains(OuterClassTestCase.class),
+() -> assertThat(outerExtensionContext.getTestClass()).contains(OuterClassTestCase.class),
 () -> assertThat(outerExtensionContext.getTestInstance()).isEmpty(),
 () -> assertThat(outerExtensionContext.getTestMethod()).isEmpty(),
-() -> assertThat(outerExtensionContext.getRequiredTestClass()).isEqualTo(OuterClass.class),
+() -> assertThat(outerExtensionContext.getRequiredTestClass()).isEqualTo(OuterClassTestCase.class),
 () -> assertThrows(PreconditionViolationException.class, outerExtensionContext::getRequiredTestInstance),
 () -> assertThrows(PreconditionViolationException.class, outerExtensionContext::getRequiredTestMethod),
 () -> assertThat(outerExtensionContext.getDisplayName()).isEqualTo(outerClassDescriptor.getDisplayName()),
 () -> assertThat(outerExtensionContext.getParent()).isEmpty(),
 () -> assertThat(outerExtensionContext.getExecutionMode()).isEqualTo(ExecutionMode.SAME_THREAD),
-() -> assertThat(outerExtensionContext.getExtensions(PreInterruptCallback.class)).isEmpty()
+() -> assertThat(outerExtensionContext.getExtensions(PreInterruptCallback.class)).isEmpty(),
+() -> assertThat(outerExtensionContext.getEnclosingTestClasses()).isEmpty()
 );
 // @formatter:on
 
 var nestedExtensionContext = new ClassExtensionContext(outerExtensionContext, null, nestedClassDescriptor,
 configuration, extensionRegistry, null);
-assertThat(nestedExtensionContext.getParent()).containsSame(outerExtensionContext);
+// @formatter:off
+assertAll("nestedContext",
+() -> assertThat(nestedExtensionContext.getParent()).containsSame(outerExtensionContext),
+() -> assertThat(nestedExtensionContext.getTestClass()).contains(OuterClassTestCase.NestedClass.class),
+() -> assertThat(nestedExtensionContext.getEnclosingTestClasses()).containsExactly(OuterClassTestCase.class)
+);
+// @formatter:on
+
+var doublyNestedExtensionContext = new ClassExtensionContext(nestedExtensionContext, null,
+doublyNestedClassDescriptor, configuration, extensionRegistry, null);
+// @formatter:off
+assertAll("doublyNestedContext",
+() -> assertThat(doublyNestedExtensionContext.getParent()).containsSame(nestedExtensionContext),
+() -> assertThat(doublyNestedExtensionContext.getTestClass()).contains(OuterClassTestCase.NestedClass.DoublyNestedClass.class),
+() -> assertThat(doublyNestedExtensionContext.getEnclosingTestClasses()).containsExactly(OuterClassTestCase.class, OuterClassTestCase.NestedClass.class)
+);
+// @formatter:on
+
+var methodExtensionContext = new MethodExtensionContext(nestedExtensionContext, null, methodTestDescriptor,
+configuration, extensionRegistry, new OpenTest4JAwareThrowableCollector());
+// @formatter:off
+assertAll("methodContext",
+() -> assertThat(methodExtensionContext.getParent()).containsSame(nestedExtensionContext),
+() -> assertThat(methodExtensionContext.getTestClass()).contains(OuterClassTestCase.NestedClass.class),
+() -> assertThat(methodExtensionContext.getEnclosingTestClasses()).containsExactly(OuterClassTestCase.class)
+);
+// @formatter:on
 }
 
 @Test
@@ -154,7 +185,6 @@ void ExtensionContext_With_ExtensionRegistry_getExtensions() {
 }
 
 @Test
-@SuppressWarnings("resource")
 void tagsCanBeRetrievedInExtensionContext() {
 var nestedClassDescriptor = nestedClassDescriptor();
 var outerClassDescriptor = outerClassDescriptor(nestedClassDescriptor);
@@ -174,20 +204,19 @@ void tagsCanBeRetrievedInExtensionContext() {
 
 var methodExtensionContext = new MethodExtensionContext(outerExtensionContext, null, methodTestDescriptor,
 configuration, extensionRegistry, new OpenTest4JAwareThrowableCollector());
-methodExtensionContext.setTestInstances(DefaultTestInstances.of(new OuterClass()));
+methodExtensionContext.setTestInstances(DefaultTestInstances.of(new OuterClassTestCase()));
 assertThat(methodExtensionContext.getTags()).containsExactlyInAnyOrder("outer-tag", "method-tag");
 assertThat(methodExtensionContext.getRoot()).isSameAs(outerExtensionContext);
 }
 
 @Test
-@SuppressWarnings("resource")
 void fromMethodTestDescriptor() {
 var methodTestDescriptor = methodDescriptor();
 var classTestDescriptor = outerClassDescriptor(methodTestDescriptor);
 var engineDescriptor = new JupiterEngineDescriptor(UniqueId.forEngine("junit-jupiter"), configuration);
 engineDescriptor.addChild(classTestDescriptor);
 
-Object testInstance = new OuterClass();
+Object testInstance = new OuterClassTestCase();
 var testMethod = methodTestDescriptor.getTestMethod();
 
 var engineExtensionContext = new JupiterEngineExtensionContext(null, engineDescriptor, configuration,
@@ -201,10 +230,11 @@ void fromMethodTestDescriptor() {
 // @formatter:off
 assertAll("methodContext",
 () -> assertThat(methodExtensionContext.getElement()).contains(testMethod),
-() -> assertThat(methodExtensionContext.getTestClass()).contains(OuterClass.class),
+() -> assertThat(methodExtensionContext.getTestClass()).contains(OuterClassTestCase.class),
+() -> assertThat(methodExtensionContext.getEnclosingTestClasses()).isEmpty(),
 () -> assertThat(methodExtensionContext.getTestInstance()).contains(testInstance),
 () -> assertThat(methodExtensionContext.getTestMethod()).contains(testMethod),
-() -> assertThat(methodExtensionContext.getRequiredTestClass()).isEqualTo(OuterClass.class),
+() -> assertThat(methodExtensionContext.getRequiredTestClass()).isEqualTo(OuterClassTestCase.class),
 () -> assertThat(methodExtensionContext.getRequiredTestInstance()).isEqualTo(testInstance),
 () -> assertThat(methodExtensionContext.getRequiredTestMethod()).isEqualTo(testMethod),
 () -> assertThat(methodExtensionContext.getDisplayName()).isEqualTo(methodTestDescriptor.getDisplayName()),
@@ -359,7 +389,7 @@ void usingStore() {
 extensionRegistry, null);
 var childContext = new MethodExtensionContext(parentContext, null, methodTestDescriptor, configuration,
 extensionRegistry, new OpenTest4JAwareThrowableCollector());
-childContext.setTestInstances(DefaultTestInstances.of(new OuterClass()));
+childContext.setTestInstances(DefaultTestInstances.of(new OuterClassTestCase()));
 
 var childStore = childContext.getStore(Namespace.GLOBAL);
 var parentStore = parentContext.getStore(Namespace.GLOBAL);
@@ -430,13 +460,18 @@ void configurationParameter(Function<JupiterConfiguration, ? extends ExtensionCo
 }
 
 private NestedClassTestDescriptor nestedClassDescriptor() {
-return new NestedClassTestDescriptor(UniqueId.root("nested-class", "NestedClass"), OuterClass.NestedClass.class,
-List::of, configuration);
+return new NestedClassTestDescriptor(UniqueId.root("nested-class", "NestedClass"),
+OuterClassTestCase.NestedClass.class, List::of, configuration);
+}
+
+private NestedClassTestDescriptor doublyNestedClassDescriptor() {
+return new NestedClassTestDescriptor(UniqueId.root("nested-class", "DoublyNestedClass"),
+OuterClassTestCase.NestedClass.DoublyNestedClass.class, List::of, configuration);
 }
 
 private ClassTestDescriptor outerClassDescriptor(TestDescriptor child) {
-var classTestDescriptor = new ClassTestDescriptor(UniqueId.root("class", "OuterClass"), OuterClass.class,
-configuration);
+var classTestDescriptor = new ClassTestDescriptor(UniqueId.root("class", "OuterClass"),
+OuterClassTestCase.class, configuration);
 if (child != null) {
 classTestDescriptor.addChild(child);
 }
@@ -445,19 +480,41 @@ private ClassTestDescriptor outerClassDescriptor(TestDescriptor child) {
 
 private TestMethodTestDescriptor methodDescriptor() {
 try {
-return new TestMethodTestDescriptor(UniqueId.root("method", "aMethod"), OuterClass.class,
-OuterClass.class.getDeclaredMethod("aMethod"), List::of, configuration);
+return new TestMethodTestDescriptor(UniqueId.root("method", "aMethod"), OuterClassTestCase.class,
+OuterClassTestCase.class.getDeclaredMethod("aMethod"), List::of, configuration);
 }
 catch (NoSuchMethodException e) {
 throw new RuntimeException(e);
 }
 }
 
+private TestMethodTestDescriptor nestedMethodDescriptor() {
+try {
+return new TestMethodTestDescriptor(UniqueId.root("method", "nestedMethod"),
+OuterClassTestCase.NestedClass.class, BaseNestedTestCase.class.getDeclaredMethod("nestedMethod"),
+List::of, configuration);
+}
+catch (NoSuchMethodException e) {
+throw new RuntimeException(e);
+}
+}
+
+static abstract class BaseNestedTestCase {
+@Test
+void nestedMethod() {
+}
+
+@Nested
+class DoublyNestedClass {
+}
+}
+
 @Tag("outer-tag")
-static class OuterClass {
+static class OuterClassTestCase {
 
 @Tag("nested-tag")
-static class NestedClass {
+@Nested
+class NestedClass extends BaseNestedTestCase {
 }
 
 @Tag("method-tag")

jupiter-tests/src/test/java/org/junit/jupiter/params/ParameterizedTestExtensionTests.java

@@ -23,6 +23,7 @@
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Method;
 import java.nio.file.Path;
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
@@ -251,6 +252,11 @@ public Optional<Class<?>> getTestClass() {
 return Optional.empty();
 }
 
+@Override
+public List<Class<?>> getEnclosingTestClasses() {
+return List.of();
+}
+
 @Override
 public Optional<Lifecycle> getTestInstanceLifecycle() {
 return Optional.empty();