Polishing

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-5.9.0-RC1.adoc

@@ -30,6 +30,13 @@ on GitHub.
 [[release-notes-5.9.0-RC1-junit-jupiter]]
 === JUnit Jupiter
 
+==== Deprecations and Breaking Changes
+
+* Private lifecycle methods (annotated with `@BeforeAll`, `@AfterAll`, `@BeforeEach`, or
+  `@AfterEach`) now correctly lead to an exception. Although this is a bug fix, it is
+  technically also a breaking change since there might be existing user code with
+  `private` lifecycle methods which will now start to fail.
+
 ==== New Features and Improvements
 
 * Three new `abort` methods have been added to the `Assumptions` class. These are
@@ -48,11 +55,6 @@ on GitHub.
   executes the test code in the same thread as the calling code, and `SEPARATE_THREAD`
   which executes it in a separate thread.
 
-==== Deprecations and Breaking Changes
-
-* Private lifecycle methods now correctly lead to an exception. Despite being a bug fix,
-  this is technically a breaking change as there might be existing user code with private
-  lifecycle methods which will now start to fail.
 
 [[release-notes-5.9.0-RC1-junit-vintage]]
 === JUnit Vintage

documentation/src/docs/asciidoc/user-guide/extensions.adoc

@@ -799,14 +799,14 @@ callbacks implemented by `Extension2`. `Extension1` is therefore said to _wrap_
 JUnit Jupiter also guarantees _wrapping_ behavior within class and interface hierarchies
 for user-supplied _lifecycle methods_ (see <<writing-tests-classes-and-methods>>).
 
-* `@BeforeAll` methods are inherited from superclasses as long as they are not _hidden_, or
+* `@BeforeAll` methods are inherited from superclasses as long as they are not _hidden_,
   _overridden_, or _superseded_ (i.e., replaced based on signature only, irrespective of
   Java's visibility rules). Furthermore, `@BeforeAll` methods from superclasses will be
   executed **before** `@BeforeAll` methods in subclasses.
 ** Similarly, `@BeforeAll` methods declared in an interface are inherited as long as they
    are not _hidden_ or _overridden_, and `@BeforeAll` methods from an interface will be
    executed **before** `@BeforeAll` methods in the class that implements the interface.
-* `@AfterAll` methods are inherited from superclasses as long as they are not _hidden_, or
+* `@AfterAll` methods are inherited from superclasses as long as they are not _hidden_,
   _overridden_, or _superseded_ (i.e., replaced based on signature only, irrespective of
   Java's visibility rules). Furthermore, `@AfterAll` methods from superclasses will be
   executed **after** `@AfterAll` methods in subclasses.

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -34,10 +34,10 @@ in the `junit-jupiter-api` module.
 | `@TestInstance`          | Used to configure the <<writing-tests-test-instance-lifecycle, test instance lifecycle>> for the annotated test class. Such annotations are _inherited_.
 | `@DisplayName`           | Declares a custom <<writing-tests-display-names,display name>> for the test class or test method. Such annotations are not _inherited_.
 | `@DisplayNameGeneration` | Declares a custom <<writing-tests-display-name-generator,display name generator>> for the test class. Such annotations are _inherited_.
-| `@BeforeEach`            | Denotes that the annotated method should be executed _before_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@Before`. Such methods are _inherited_ unless they are _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules).
-| `@AfterEach`             | Denotes that the annotated method should be executed _after_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@After`. Such methods are _inherited_ unless they are _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules).
-| `@BeforeAll`             | Denotes that the annotated method should be executed _before_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@BeforeClass`. Such methods are _inherited_ (unless they are _hidden_, or _overridden_, or _superseded_, i.e., replaced based on signature only, irrespective of Java's visibility rules) and must be `static` (unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used).
-| `@AfterAll`              | Denotes that the annotated method should be executed _after_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@AfterClass`. Such methods are _inherited_ (unless they are _hidden_, or _overridden_, or _superseded_, i.e., replaced based on signature only, irrespective of Java's visibility rules) and must be `static` (unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used).
+| `@BeforeEach`            | Denotes that the annotated method should be executed _before_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@Before`. Such methods are _inherited_ – unless they are _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules).
+| `@AfterEach`             | Denotes that the annotated method should be executed _after_ *each* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, or `@TestFactory` method in the current class; analogous to JUnit 4's `@After`. Such methods are _inherited_ – unless they are _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of Java's visibility rules).
+| `@BeforeAll`             | Denotes that the annotated method should be executed _before_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@BeforeClass`. Such methods are _inherited_ – unless they are _hidden_, _overridden_, or _superseded_, (i.e., replaced based on signature only, irrespective of Java's visibility rules) – and must be `static` unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used.
+| `@AfterAll`              | Denotes that the annotated method should be executed _after_ *all* `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and `@TestFactory` methods in the current class; analogous to JUnit 4's `@AfterClass`. Such methods are _inherited_ – unless they are _hidden_, _overridden_, or _superseded_, (i.e., replaced based on signature only, irrespective of Java's visibility rules) – and must be `static` unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used.
 | `@Nested`                | Denotes that the annotated class is a non-static <<writing-tests-nested,nested test class>>. On Java 8 through Java 15, `@BeforeAll` and `@AfterAll` methods cannot be used directly in a `@Nested` test class unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used. Beginning with Java 16, `@BeforeAll` and `@AfterAll` methods can be declared as `static` in a `@Nested` test class with either test instance lifecycle mode. Such annotations are not _inherited_.
 | `@Tag`                   | Used to declare <<writing-tests-tagging-and-filtering,tags for filtering tests>>, either at the class or method level; analogous to test groups in TestNG or Categories in JUnit 4. Such annotations are _inherited_ at the class level but not at the method level.
 | `@Disabled`              | Used to <<writing-tests-disabling,disable>> a test class or test method; analogous to JUnit 4's `@Ignore`. Such annotations are not _inherited_.

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterAll.java

@@ -43,7 +43,7 @@
  * <h2>Inheritance and Execution Order</h2>
  *
  * <p>{@code @AfterAll} methods are inherited from superclasses as long as
- * they are not <em>hidden</em> (default mode with {@code static} modifier), or
+ * they are not <em>hidden</em> (default mode with {@code static} modifier),
  * <em>overridden</em>, or <em>superseded</em> (i.e., replaced based on
  * signature only, irrespective of Java's visibility rules). Furthermore,
  * {@code @AfterAll} methods from superclasses will be executed before

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterEach.java

@@ -35,8 +35,8 @@
  *
  * <h2>Inheritance and Execution Order</h2>
  *
- * <p>{@code @AfterEach} methods are inherited from superclasses as long as
- * they are not overridden or <em>superseded</em> (i.e., replaced based on
+ * <p>{@code @AfterEach} methods are inherited from superclasses as long as they
+ * are not <em>overridden</em> or <em>superseded</em> (i.e., replaced based on
  * signature only, irrespective of Java's visibility rules). Furthermore,
  * {@code @AfterEach} methods from superclasses will be executed after
  * {@code @AfterEach} methods in subclasses.

junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeAll.java

@@ -43,7 +43,7 @@
  * <h2>Inheritance and Execution Order</h2>
  *
  * <p>{@code @BeforeAll} methods are inherited from superclasses as long as
- * they are not <em>hidden</em> (default mode with {@code static} modifier), or
+ * they are not <em>hidden</em> (default mode with {@code static} modifier),
  * <em>overridden</em>, or <em>superseded</em> (i.e., replaced based on
  * signature only, irrespective of Java's visibility rules). Furthermore,
  * {@code @BeforeAll} methods from superclasses will be executed before

junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeEach.java

@@ -35,8 +35,8 @@
  *
  * <h2>Inheritance and Execution Order</h2>
  *
- * <p>{@code @BeforeEach} methods are inherited from superclasses as long as
- * they are not overridden or <em>superseded</em> (i.e., replaced based on
+ * <p>{@code @BeforeEach} methods are inherited from superclasses as long as they
+ * are not <em>overridden</em> or <em>superseded</em> (i.e., replaced based on
  * signature only, irrespective of Java's visibility rules). Furthermore,
  * {@code @BeforeEach} methods from superclasses will be executed before
  * {@code @BeforeEach} methods in subclasses.

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

@@ -54,6 +54,36 @@ static List<Method> findAfterEachMethods(Class<?> testClass) {
 		return findMethodsAndAssertNonStaticAndNonPrivate(testClass, AfterEach.class, HierarchyTraversalMode.BOTTOM_UP);
 	}
 
+	private static List<Method> findMethodsAndAssertStaticAndNonPrivate(Class<?> testClass, boolean requireStatic,
+			Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode) {
+
+		List<Method> methods = findMethodsAndCheckVoidReturnType(testClass, annotationType, traversalMode);
+		if (requireStatic) {
+			methods.forEach(method -> assertStatic(annotationType, method));
+		}
+		methods.forEach(method -> assertNonPrivate(annotationType, method));
+		return methods;
+	}
+
+	private static List<Method> findMethodsAndAssertNonStaticAndNonPrivate(Class<?> testClass,
+			Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode) {
+
+		List<Method> methods = findMethodsAndCheckVoidReturnType(testClass, annotationType, traversalMode);
+		methods.forEach(method -> {
+			assertNonStatic(annotationType, method);
+			assertNonPrivate(annotationType, method);
+		});
+		return methods;
+	}
+
+	private static List<Method> findMethodsAndCheckVoidReturnType(Class<?> testClass,
+			Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode) {
+
+		List<Method> methods = findAnnotatedMethods(testClass, annotationType, traversalMode);
+		methods.forEach(method -> assertVoid(annotationType, method));
+		return methods;
+	}
+
 	private static void assertStatic(Class<? extends Annotation> annotationType, Method method) {
 		if (ReflectionUtils.isNotStatic(method)) {
 			throw new JUnitException(String.format(
@@ -83,33 +113,4 @@ private static void assertVoid(Class<? extends Annotation> annotationType, Metho
 		}
 	}
 
-	private static List<Method> findMethodsAndAssertStaticAndNonPrivate(Class<?> testClass, boolean requireStatic,
-			Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode) {
-		List<Method> methods = findMethodsAndCheckVoidReturnType(testClass, annotationType, traversalMode);
-		if (requireStatic) {
-			methods.forEach(method -> assertStatic(annotationType, method));
-		}
-		methods.forEach(method -> assertNonPrivate(annotationType, method));
-
-		return methods;
-	}
-
-	private static List<Method> findMethodsAndAssertNonStaticAndNonPrivate(Class<?> testClass,
-			Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode) {
-		List<Method> methods = findMethodsAndCheckVoidReturnType(testClass, annotationType, traversalMode);
-		methods.forEach(method -> {
-			assertNonStatic(annotationType, method);
-			assertNonPrivate(annotationType, method);
-		});
-
-		return methods;
-	}
-
-	private static List<Method> findMethodsAndCheckVoidReturnType(Class<?> testClass,
-			Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode) {
-		List<Method> methods = findAnnotatedMethods(testClass, annotationType, traversalMode);
-		methods.forEach(method -> assertVoid(annotationType, method));
-		return methods;
-	}
-
 }

…ine/LifecycleMethodSupersedingTests.java …MethodOverridingAndSupersedingTests.javajunit-jupiter-engine/src/test/java/org/junit/jupiter/engine/LifecycleMethodSupersedingTests.java renamed to junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/LifecycleMethodOverridingAndSupersedingTests.java junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/LifecycleMethodSupersedingTests.java renamed to junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/LifecycleMethodOverridingAndSupersedingTests.java

@@ -26,24 +26,26 @@
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.engine.subpackage.SuperClassWithPackagePrivateLifecycleMethodInDifferentPackageTestCase;
 
 /**
- * Integration tests that explicitly demonstrate the shadowing/overriding
+ * Integration tests that explicitly demonstrate the overriding and superseding
  * rules for lifecycle methods in the {@link JupiterTestEngine}.
  *
  * @since 5.9
  */
-class LifecycleMethodSupersedingTests {
+class LifecycleMethodOverridingAndSupersedingTests {
 
 	@Nested
-	@DisplayName("A package-private lifecycle super-method can be superseded by")
+	@DisplayName("A package-private lifecycle super-method can be overridden by")
 	class PackagePrivateSuperClassTests {
 
 		@Nested
 		@DisplayName("a protected lifecycle method in the derived class")
 		class ProtectedExtendsPackagePrivateLifecycleMethod
 				extends SuperClassWithPackagePrivateLifecycleMethodTestCase {
 
+			@Override
 			@BeforeEach
 			protected void beforeEach() {
 			}
@@ -55,6 +57,7 @@ protected void beforeEach() {
 		class PackagePrivateExtendsPackagePrivateLifecycleMethod
 				extends SuperClassWithPackagePrivateLifecycleMethodTestCase {
 
+			@Override
 			@BeforeEach
 			void beforeEach() {
 			}
@@ -65,6 +68,7 @@ void beforeEach() {
 		@DisplayName("a public lifecycle method in the derived class")
 		class PublicExtendsPackagePrivateLifecycleMethod extends SuperClassWithPackagePrivateLifecycleMethodTestCase {
 
+			@Override
 			@BeforeEach
 			public void beforeEach() {
 			}
@@ -73,13 +77,55 @@ public void beforeEach() {
 	}
 
 	@Nested
-	@DisplayName("A protected lifecycle super-method can be superseded by")
+	@DisplayName("A package-private lifecycle super-method from a different package can be superseded by")
+	class PackagePrivateSuperClassInDifferentPackageTests {
+
+		@Nested
+		@DisplayName("a protected lifecycle method in the derived class")
+		class ProtectedExtendsPackagePrivateLifecycleMethod
+				extends SuperClassWithPackagePrivateLifecycleMethodInDifferentPackageTestCase {
+
+			// @Override
+			@BeforeEach
+			protected void beforeEach() {
+			}
+
+		}
+
+		@Nested
+		@DisplayName("a package-private lifecycle method in the derived class")
+		class PackagePrivateExtendsPackagePrivateLifecycleMethod
+				extends SuperClassWithPackagePrivateLifecycleMethodInDifferentPackageTestCase {
+
+			// @Override
+			@BeforeEach
+			void beforeEach() {
+			}
+
+		}
+
+		@Nested
+		@DisplayName("a public lifecycle method in the derived class")
+		class PublicExtendsPackagePrivateLifecycleMethod
+				extends SuperClassWithPackagePrivateLifecycleMethodInDifferentPackageTestCase {
+
+			// @Override
+			@BeforeEach
+			public void beforeEach() {
+			}
+
+		}
+	}
+
+	@Nested
+	@DisplayName("A protected lifecycle super-method can be overridden by")
 	class ProtectedSuperClassTests {
 
 		@Nested
 		@DisplayName("a protected lifecycle method in the derived class")
 		class ProtectedExtendsPackagePrivate extends SuperClassWithProtectedLifecycleMethodTestCase {
 
+			@Override
 			@BeforeEach
 			protected void beforeEach() {
 			}
@@ -90,6 +136,7 @@ protected void beforeEach() {
 		@DisplayName("a public lifecycle method in the derived class")
 		class PublicExtendsPackagePrivate extends SuperClassWithProtectedLifecycleMethodTestCase {
 
+			@Override
 			@BeforeEach
 			public void beforeEach() {
 			}
@@ -98,13 +145,14 @@ public void beforeEach() {
 	}
 
 	@Nested
-	@DisplayName("A public lifecycle super-method can be superseded by")
+	@DisplayName("A public lifecycle super-method can be overridden by")
 	class PublicSuperClassTests {
 
 		@Nested
 		@DisplayName("a public lifecycle method in the derived class")
 		class PublicExtendsPackagePrivate extends SuperClassWithPublicLifecycleMethodTestCase {
 
+			@Override
 			@BeforeEach
 			public void beforeEach() {
 			}

junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/subpackage/SuperClassWithPackagePrivateLifecycleMethodInDifferentPackageTestCase.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2015-2022 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.jupiter.engine.subpackage;
+
+import static org.junit.jupiter.api.Assertions.fail;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * @since 5.9
+ */
+public class SuperClassWithPackagePrivateLifecycleMethodInDifferentPackageTestCase {
+
+	@BeforeEach
+	void beforeEach() {
+		fail();
+	}
+
+	@Test
+	void test() {
+	}
+
+}