Return Optional from ExtensionContext.getElement()

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

@@ -8,13 +8,12 @@
 
 ===== JUnit Platform
 
-- *TODO*
-- `ConsoleRunner` has been renamed to `ConsoleLauncher`
+- `org.junit.platform.console.ConsoleRunner` has been renamed to `ConsoleLauncher`
 
 ===== JUnit Jupiter
 
-- *TODO*
+- `ExtensionContext.getElement()` now returns `Optional<AnnotatedElement>`.
 
 ===== JUnit Vintage
 
-- *TODO*
+- ???

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

@@ -80,6 +80,25 @@ public interface ExtensionContext {
 	 */
 	Set<String> getTags();
 
+	/**
+	 * Get the {@link AnnotatedElement} corresponding to the current extension
+	 * context, if available.
+	 *
+	 * <p>For example, if the current extension context encapsulates a test
+	 * class or test method, the annotated element will be the corresponding
+	 * {@link Class} or {@link Method} reference.
+	 *
+	 * <p>Favor this method over more specific methods whenever the
+	 * {@code AnnotatedElement} API suits the task at hand &mdash; for example,
+	 * when looking up annotations regardless of concrete element type.
+	 *
+	 * @return an {@code Optional} containing the {@code AnnotatedElement};
+	 * never {@code null} but potentially empty
+	 * @see #getTestClass()
+	 * @see #getTestMethod()
+	 */
+	Optional<AnnotatedElement> getElement();
+
 	/**
 	 * Get the {@link Class} associated with the current test or container,
 	 * if available.
@@ -97,25 +116,6 @@ public interface ExtensionContext {
 	 */
 	Optional<Method> getTestMethod();
 
-	/**
-	 * Get the {@link AnnotatedElement} corresponding to the current extension
-	 * context.
-	 *
-	 * <p>For example, if the current extension context encapsulates a test
-	 * class or test method, the annotated element will be the corresponding
-	 * {@link #getTestClass() Class} or {@link #getTestMethod() Method}
-	 * reference.
-	 *
-	 * <p>Favor this method over more specific methods whenever the
-	 * {@link AnnotatedElement} API suits the task at hand &mdash; for example,
-	 * when looking up annotations regardless of concrete element type.
-	 *
-	 * @return the {@code AnnotatedElement}; never {@code null}
-	 * @see #getTestClass()
-	 * @see #getTestMethod()
-	 */
-	AnnotatedElement getElement();
-
 	/**
 	 * Publish a map of key-value pairs to be consumed by an
 	 * {@code org.junit.platform.engine.EngineExecutionListener}.

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

@@ -44,8 +44,8 @@ public String getDisplayName() {
 	}
 
 	@Override
-	public AnnotatedElement getElement() {
-		return getTestClass().get();
+	public Optional<AnnotatedElement> getElement() {
+		return Optional.of(getTestDescriptor().getTestClass());
 	}
 
 	@Override

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

@@ -47,8 +47,8 @@ public String getDisplayName() {
 	}
 
 	@Override
-	public AnnotatedElement getElement() {
-		return getTestMethod().get();
+	public Optional<AnnotatedElement> getElement() {
+		return Optional.of(getTestDescriptor().getTestMethod());
 	}
 
 	@Override

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/DisabledCondition.java

@@ -53,7 +53,7 @@ public ConditionEvaluationResult evaluate(TestExtensionContext context) {
 		return evaluate(context.getElement());
 	}
 
-	private ConditionEvaluationResult evaluate(AnnotatedElement element) {
+	private ConditionEvaluationResult evaluate(Optional<AnnotatedElement> element) {
 		Optional<Disabled> disabled = findAnnotation(element, Disabled.class);
 		if (disabled.isPresent()) {
 			String reason = disabled.map(Disabled::value).filter(StringUtils::isNotBlank).orElseGet(

junit-platform-commons/src/main/java/org/junit/platform/commons/util/AnnotationUtils.java

@@ -68,6 +68,22 @@ public static boolean isAnnotated(AnnotatedElement element, Class<? extends Anno
 		return findAnnotation(element, annotationType).isPresent();
 	}
 
+	/**
+	 * Find the first annotation of {@code annotationType} that is either <em>present</em> or <em>meta-present</em> on
+	 * the supplied optional {@code element}.
+	 *
+	 * @see #findAnnotation(AnnotatedElement, Class)
+	 */
+	public static <A extends Annotation> Optional<A> findAnnotation(Optional<? extends AnnotatedElement> element,
+			Class<A> annotationType) {
+
+		if (element == null || !element.isPresent()) {
+			return Optional.empty();
+		}
+
+		return findAnnotation(element.get(), annotationType, new HashSet<Annotation>());
+	}
+
 	/**
 	 * Find the first annotation of {@code annotationType} that is either <em>present</em> or <em>meta-present</em> on
 	 * the supplied {@code element}.

platform-tests/src/test/java/org/junit/platform/commons/util/AnnotationUtilsTests.java

@@ -31,6 +31,7 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Method;
 import java.util.List;
 import java.util.Optional;
@@ -44,9 +45,19 @@
  */
 class AnnotationUtilsTests {
 
+	@Test
+	void findAnnotationForNullOptional() {
+		assertThat(findAnnotation((Optional<AnnotatedElement>) null, Annotation1.class)).isEmpty();
+	}
+
+	@Test
+	void findAnnotationForEmptyOptional() {
+		assertThat(findAnnotation(Optional.empty(), Annotation1.class)).isEmpty();
+	}
+
 	@Test
 	void findAnnotationForNullAnnotatedElement() {
-		assertThat(findAnnotation(null, Annotation1.class)).isEmpty();
+		assertThat(findAnnotation((AnnotatedElement) null, Annotation1.class)).isEmpty();
 	}
 
 	@Test
@@ -56,6 +67,14 @@ void findAnnotationOnClassWithoutAnnotation() {
 		assertFalse(optionalAnnotation.isPresent());
 	}
 
+	@Test
+	void findAnnotationIndirectlyPresentOnOptionalClass() {
+		Optional<InheritedAnnotation> optionalAnnotation = findAnnotation(
+			Optional.of(SubInheritedAnnotationClass.class), InheritedAnnotation.class);
+		assertNotNull(optionalAnnotation);
+		assertTrue(optionalAnnotation.isPresent());
+	}
+
 	@Test
 	void findAnnotationIndirectlyPresentOnClass() {
 		Optional<InheritedAnnotation> optionalAnnotation = findAnnotation(SubInheritedAnnotationClass.class,
@@ -105,6 +124,14 @@ void findAnnotationMetaPresentOnMethod() throws Exception {
 		assertTrue(optionalAnnotation.isPresent());
 	}
 
+	@Test
+	void findAnnotationMetaPresentOnOptionalMethod() throws Exception {
+		Optional<Annotation1> optionalAnnotation = findAnnotation(
+			Optional.of(ComposedAnnotationClass.class.getDeclaredMethod("method")), Annotation1.class);
+		assertNotNull(optionalAnnotation);
+		assertTrue(optionalAnnotation.isPresent());
+	}
+
 	@Test
 	void isAnnotatedForClassWithoutAnnotation() {
 		assertFalse(isAnnotated(Annotation1Class.class, Annotation2.class));