diff --git a/documentation/src/docs/asciidoc/release-notes/release-notes-5.11.0-M1.adoc b/documentation/src/docs/asciidoc/release-notes/release-notes-5.11.0-M1.adoc index 1fe2a55ce3da..873c15d7c895 100644 --- a/documentation/src/docs/asciidoc/release-notes/release-notes-5.11.0-M1.adoc +++ b/documentation/src/docs/asciidoc/release-notes/release-notes-5.11.0-M1.adoc @@ -16,6 +16,11 @@ repository on GitHub. [[release-notes-5.11.0-M1-junit-platform-bug-fixes]] ==== Bug Fixes +* Field and method search algorithms now adhere to standard Java semantics regarding + whether a given field or method is visible or overridden according to the rules of the + Java language. See the new + <<../user-guide/index.adoc#extensions-supported-utilities-search-semantics, Field and + Method Search Semantics>> section of the User Guide for details. * `ReflectionSupport.findFields(...)` now returns a distinct set of fields. * Fixed parsing of recursive jar URIs which allows the JUnit Platform Launcher to be used inside Spring Boot executable jars for Spring Boot 3.2 and later. @@ -25,7 +30,13 @@ repository on GitHub. [[release-notes-5.11.0-M1-junit-platform-deprecations-and-breaking-changes]] ==== Deprecations and Breaking Changes -* ❓ +* As mentioned in the _Bug Fixes_ section above, field and method search algorithms now + adhere to standard Java semantics regarding whether a given field or method is visible + or overridden according to the rules of the Java language. The changes in the search + algorithms may, however, result in breaking changes for some use cases. In light of + that, it is possible to revert to the previous "legacy semantics". See the new + <<../user-guide/index.adoc#extensions-supported-utilities-search-semantics, Field and + Method Search Semantics>> section of the User Guide for details. [[release-notes-5.11.0-M1-junit-platform-new-features-and-improvements]] ==== New Features and Improvements @@ -43,7 +54,19 @@ repository on GitHub. [[release-notes-5.11.0-M1-junit-jupiter-bug-fixes]] ==== Bug Fixes -* ❓ +* Due to changes in the JUnit Platform regarding field and method search algorithms (see + <> above), numerous bugs have been + addressed within JUnit Jupiter, including but not limited to the following. + ** Two `@TempDir` fields with the same name in a superclass and subclass will now both + be injected. + ** Two `@Test` methods with the same signature in a superclass and subclass will now + both be invoked, as long as the `@Test` method in the subclass does not override the + `@Test` method in the superclass, which can occur if the superclass method is `private` + or if the superclass method is package-private and resides in a different package than + the subclass. + *** The same applies to other types of test methods (`@TestFactory`, + `@ParameterizedTest`, etc.) as well as lifecycle methods (`@BeforeAll`, + `@AfterAll`, `@BeforeEach`, and `@AfterEach`). [[release-notes-5.11.0-M1-junit-jupiter-deprecations-and-breaking-changes]] ==== Deprecations and Breaking Changes diff --git a/documentation/src/docs/asciidoc/user-guide/extensions.adoc b/documentation/src/docs/asciidoc/user-guide/extensions.adoc index 893787408b33..4d7c5020d6ad 100644 --- a/documentation/src/docs/asciidoc/user-guide/extensions.adoc +++ b/documentation/src/docs/asciidoc/user-guide/extensions.adoc @@ -156,6 +156,15 @@ using the `@Order` annotation. See the <> tip for `@RegisterExtension` fields for details. ==== +[TIP] +.Extension Inheritance +==== +Extensions registered declaratively via `@ExtendWith` on fields in superclasses will be +inherited. + +See <> for details. +==== + NOTE: `@ExtendWith` fields may be either `static` or non-static. The documentation on <> and <> for @@ -196,6 +205,15 @@ extensions to be registered last and _after_ callback extensions to be registere relative to other programmatically registered extensions. ==== +[TIP] +.Extension Inheritance +==== +Extensions registered via `@RegisterExtension` or `@ExtendWith` on fields in superclasses +will be inherited. + +See <> for details. +==== + NOTE: `@RegisterExtension` fields must not be `null` (at evaluation time) but may be either `static` or non-static. @@ -304,11 +322,23 @@ support for `TestInfo`, `TestReporter`, etc.). [[extensions-registration-inheritance]] ==== Extension Inheritance -Registered extensions are inherited within test class hierarchies with top-down -semantics. Similarly, extensions registered at the class-level are inherited at the -method-level. Furthermore, a specific extension implementation can only be registered -once for a given extension context and its parent contexts. Consequently, any attempt to -register a duplicate extension implementation will be ignored. +Registered extensions are inherited within test class hierarchies with top-down semantics. +Similarly, extensions registered at the class-level are inherited at the method-level. +This applies to all extensions, independent of how they are registered (declaratively or +programmatically). + +This means that extensions registered declaratively via `@ExtendWith` on a superclass will +be registered before extensions registered declaratively via `@ExtendWith` on a subclass. + +Similarly, extensions registered programmatically via `@RegisterExtension` or +`@ExtendWith` on fields in a superclass will be registered before extensions registered +programmatically via `@RegisterExtension` or `@ExtendWith` on fields in a subclass, unless +`@Order` is used to alter that behavior (see <> for details). + +NOTE: A specific extension implementation can only be registered once for a given +extension context and its parent contexts. Consequently, any attempt to register a +duplicate extension implementation will be ignored. [[extensions-conditions]] === Conditional Test Execution @@ -704,6 +734,8 @@ and fields in a class or interface. Some of these methods search on implemented interfaces and within class hierarchies to find annotations. Consult the Javadoc for `{AnnotationSupport}` for further details. +NOTE: See also: <> + [[extensions-supported-utilities-classes]] ==== Class Support @@ -720,6 +752,8 @@ class, and to find and invoke methods. Some of these methods traverse class hier to locate matching methods. Consult the Javadoc for `{ReflectionSupport}` for further details. +NOTE: See also: <> + [[extensions-supported-utilities-modifier]] ==== Modifier Support @@ -737,6 +771,37 @@ wrapper types, date and time types from the `java.time package`, and some additi common Java types such as `File`, `BigDecimal`, `BigInteger`, `Currency`, `Locale`, `URI`, `URL`, `UUID`, etc. Consult the Javadoc for `{ConversionSupport}` for further details. +[[extensions-supported-utilities-search-semantics]] +==== Field and Method Search Semantics + +Various methods in `AnnotationSupport` and `ReflectionSupport` use search algorithms that +traverse type hierarchies to locate matching fields and methods – for example, +`AnnotationSupport.findAnnotatedFields(...)`, `ReflectionSupport.findMethods(...)`, etc. + +As of JUnit 5.11 (JUnit Platform 1.11), field and method search algorithms adhere to +standard Java semantics regarding whether a given field or method is visible or overridden +according to the rules of the Java language. + +Prior to JUnit 5.11, the field and method search algorithms applied what we now refer to +as "legacy semantics". Legacy semantics consider fields and methods to be _hidden_, +_shadowed_, or _superseded_ by fields and methods in super types (superclasses or +interfaces) based solely on the field's name or the method's signature, disregarding the +actual Java language semantics for visibility and the rules that determine if one method +overrides another method. + +Although the JUnit team recommends the use of the standard search semantics, developers +may optionally revert to the legacy semantics via the +`junit.platform.reflection.search.useLegacySemantics` JVM system property. + +For example, to enable legacy search semantics for fields and methods, you can start your +JVM with the following system property. + +`-Djunit.platform.reflection.search.useLegacySemantics=true` + +NOTE: Due to the low-level nature of the feature, the +`junit.platform.reflection.search.useLegacySemantics` flag can only be set via a JVM +system property. It cannot be set via a <>. [[extensions-execution-order]] === Relative Execution Order of User Code and Extensions @@ -863,31 +928,27 @@ 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 <>). -* `@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. +* `@BeforeAll` methods are inherited from superclasses as long as they are not + _overridden_. 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_, - _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. + are not _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 + _overridden_. Furthermore, `@AfterAll` methods from superclasses will be executed + **after** `@AfterAll` methods in subclasses. ** Similarly, `@AfterAll` methods declared in an interface are inherited as long as they - are not _hidden_ or _overridden_, and `@AfterAll` methods from an interface will be - executed **after** `@AfterAll` methods in the class that implements the interface. + are not _overridden_, and `@AfterAll` methods from an interface will be executed + **after** `@AfterAll` methods in the class that implements the interface. * `@BeforeEach` methods are inherited from superclasses as long as they are not - _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of - Java's visibility rules). Furthermore, `@BeforeEach` methods from superclasses will be - executed **before** `@BeforeEach` methods in subclasses. + _overridden_. Furthermore, `@BeforeEach` methods from superclasses will be executed + **before** `@BeforeEach` methods in subclasses. ** Similarly, `@BeforeEach` methods declared as interface default methods are inherited as long as they are not _overridden_, and `@BeforeEach` default methods will be executed **before** `@BeforeEach` methods in the class that implements the interface. * `@AfterEach` methods are inherited from superclasses as long as they are not - _overridden_ or _superseded_ (i.e., replaced based on signature only, irrespective of - Java's visibility rules). Furthermore, `@AfterEach` methods from superclasses will be - executed **after** `@AfterEach` methods in subclasses. + _overridden_. Furthermore, `@AfterEach` methods from superclasses will be executed + **after** `@AfterEach` methods in subclasses. ** Similarly, `@AfterEach` methods declared as interface default methods are inherited as long as they are not _overridden_, and `@AfterEach` default methods will be executed **after** `@AfterEach` methods in the class that implements the interface. diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index ef7de8718a73..cebb42c8d4df 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -24,28 +24,28 @@ in the `junit-jupiter-api` module. |=== | Annotation | Description -| `@Test` | Denotes that a method is a test method. Unlike JUnit 4's `@Test` annotation, this annotation does not declare any attributes, since test extensions in JUnit Jupiter operate based on their own dedicated annotations. Such methods are _inherited_ unless they are _overridden_. -| `@ParameterizedTest` | Denotes that a method is a <>. Such methods are _inherited_ unless they are _overridden_. -| `@RepeatedTest` | Denotes that a method is a test template for a <>. Such methods are _inherited_ unless they are _overridden_. -| `@TestFactory` | Denotes that a method is a test factory for <>. Such methods are _inherited_ unless they are _overridden_. -| `@TestTemplate` | Denotes that a method is a <> designed to be invoked multiple times depending on the number of invocation contexts returned by the registered <>. Such methods are _inherited_ unless they are _overridden_. -| `@TestClassOrder` | Used to configure the <> for `@Nested` test classes in the annotated test class. Such annotations are _inherited_. -| `@TestMethodOrder` | Used to configure the <> for the annotated test class; similar to JUnit 4's `@FixMethodOrder`. Such annotations are _inherited_. -| `@TestInstance` | Used to configure the <> for the annotated test class. Such annotations are _inherited_. -| `@DisplayName` | Declares a custom <> for the test class or test method. Such annotations are not _inherited_. -| `@DisplayNameGeneration` | Declares a custom <> 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_, _overridden_, or _superseded_, (i.e., replaced based on signature only, irrespective of Java's visibility rules) – and must be `static` unless the "per-class" <> 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" <> is used. -| `@Nested` | Denotes that the annotated class is a non-static <>. On Java 8 through Java 15, `@BeforeAll` and `@AfterAll` methods cannot be used directly in a `@Nested` test class unless the "per-class" <> 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 <>, 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 <> a test class or test method; analogous to JUnit 4's `@Ignore`. Such annotations are not _inherited_. +| `@Test` | Denotes that a method is a test method. Unlike JUnit 4's `@Test` annotation, this annotation does not declare any attributes, since test extensions in JUnit Jupiter operate based on their own dedicated annotations. Such methods are inherited unless they are overridden. +| `@ParameterizedTest` | Denotes that a method is a <>. Such methods are inherited unless they are overridden. +| `@RepeatedTest` | Denotes that a method is a test template for a <>. Such methods are inherited unless they are overridden. +| `@TestFactory` | Denotes that a method is a test factory for <>. Such methods are inherited unless they are overridden. +| `@TestTemplate` | Denotes that a method is a <> designed to be invoked multiple times depending on the number of invocation contexts returned by the registered <>. Such methods are inherited unless they are overridden. +| `@TestClassOrder` | Used to configure the <> for `@Nested` test classes in the annotated test class. Such annotations are inherited. +| `@TestMethodOrder` | Used to configure the <> for the annotated test class; similar to JUnit 4's `@FixMethodOrder`. Such annotations are inherited. +| `@TestInstance` | Used to configure the <> for the annotated test class. Such annotations are inherited. +| `@DisplayName` | Declares a custom <> for the test class or test method. Such annotations are not inherited. +| `@DisplayNameGeneration` | Declares a custom <> 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. +| `@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. +| `@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 overridden and must be `static` unless the "per-class" <> 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 overridden and must be `static` unless the "per-class" <> is used. +| `@Nested` | Denotes that the annotated class is a non-static <>. On Java 8 through Java 15, `@BeforeAll` and `@AfterAll` methods cannot be used directly in a `@Nested` test class unless the "per-class" <> 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 <>, 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 <> a test class or test method; analogous to JUnit 4's `@Ignore`. Such annotations are not inherited. | `@AutoClose` | Denotes that the annotated field represents a resource that will be <> after test execution. -| `@Timeout` | Used to fail a test, test factory, test template, or lifecycle method if its execution exceeds a given duration. Such annotations are _inherited_. -| `@TempDir` | Used to supply a <> via field injection or parameter injection in a lifecycle method or test method; located in the `org.junit.jupiter.api.io` package. -| `@ExtendWith` | Used to <>. Such annotations are _inherited_. -| `@RegisterExtension` | Used to <> via fields. Such fields are _inherited_ unless they are _shadowed_. +| `@Timeout` | Used to fail a test, test factory, test template, or lifecycle method if its execution exceeds a given duration. Such annotations are inherited. +| `@TempDir` | Used to supply a <> via field injection or parameter injection in a lifecycle method or test method; located in the `org.junit.jupiter.api.io` package. Such fields are inherited. +| `@ExtendWith` | Used to <>. Such annotations are inherited. +| `@RegisterExtension` | Used to <> via fields. Such fields are inherited. |=== WARNING: Some annotations may currently be _experimental_. Consult the table in @@ -150,6 +150,22 @@ making classes and methods `public` is to simplify testing on the module path wh the Java Module System. ==== +[NOTE] +.Field and method inheritance +==== +Fields in test classes are inherited. For example, a `@TempDir` field from a superclass +will always be applied in a subclass. + +Test methods and lifecycle methods are inherited unless they are overridden according to +the visibility rules of the Java language. For example, a `@Test` method from a superclass +will always be applied in a subclass unless the subclass explicitly overrides the method. +Similarly, if a `@Test` method is declared in a superclass that resides in a different +package than the subclass, that `@Test` method will always be applied in the subclass +since the subclass cannot override a package-private method from a superclass. + +See also: <> +==== + The following test class demonstrates the use of `@Test` methods and all supported lifecycle methods. For further information on runtime semantics, see <> and @@ -2748,9 +2764,8 @@ method that will be invoked to close the resource. However, developers can custo name of the close method via the `value` attribute. For example, `@AutoClose("shutdown")` instructs JUnit to look for a `shutdown()` method to close the resource. -`@AutoClose` fields are inherited from superclasses as long as they are not hidden. -Furthermore, `@AutoClose` fields from subclasses will be closed before `@AutoClose` fields -in superclasses. +`@AutoClose` fields are inherited from superclasses. Furthermore, `@AutoClose` fields from +subclasses will be closed before `@AutoClose` fields in superclasses. When multiple `@AutoClose` fields exist within a given test class, the order in which the resources are closed depends on an algorithm that is deterministic but intentionally diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterAll.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterAll.java index 2a70a83623c0..7cbbfd7b0f15 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterAll.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterAll.java @@ -45,17 +45,15 @@ * *

Inheritance and Execution Order

* - *

{@code @AfterAll} methods are inherited from superclasses as long as - * they are not hidden (default mode with {@code static} modifier), - * overridden, or superseded (i.e., replaced based on - * signature only, irrespective of Java's visibility rules). Furthermore, - * {@code @AfterAll} methods from superclasses will be executed before - * {@code @AfterAll} methods in subclasses. + *

{@code @AfterAll} methods are inherited from superclasses as long as they + * are not overridden according to the visibility rules of the Java + * language. Furthermore, {@code @AfterAll} methods from superclasses will be + * executed after {@code @AfterAll} methods in subclasses. * - *

Similarly, {@code @AfterAll} methods declared in an interface are - * inherited as long as they are not hidden or overridden, - * and {@code @AfterAll} methods from an interface will be executed after - * {@code @AfterAll} methods in the class that implements the interface. + *

Similarly, {@code @AfterAll} methods declared in an interface are inherited + * as long as they are not overridden, and {@code @AfterAll} methods from an + * interface will be executed after {@code @AfterAll} methods in the class that + * implements the interface. * *

JUnit Jupiter does not guarantee the execution order of multiple * {@code @AfterAll} methods that are declared within a single test class or diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterEach.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterEach.java index 707fd439ffa6..bf1d90853f33 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterEach.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AfterEach.java @@ -39,10 +39,9 @@ *

Inheritance and Execution Order

* *

{@code @AfterEach} methods are inherited from superclasses as long as they - * are not overridden or superseded (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. + * are not overridden according to the visibility rules of the Java + * language. Furthermore, {@code @AfterEach} methods from superclasses will be + * executed after {@code @AfterEach} methods in subclasses. * *

Similarly, {@code @AfterEach} methods declared as interface default * methods are inherited as long as they are not overridden, and diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AutoClose.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AutoClose.java index ea858baceee9..0a29faba7a95 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AutoClose.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/AutoClose.java @@ -40,9 +40,9 @@ * *

Inheritance

* - *

{@code @AutoClose} fields are inherited from superclasses as long as they - * are not hidden. Furthermore, {@code @AutoClose} fields from subclasses - * will be closed before {@code @AutoClose} fields in superclasses. + *

{@code @AutoClose} fields are inherited from superclasses. Furthermore, + * {@code @AutoClose} fields from subclasses will be closed before + * {@code @AutoClose} fields in superclasses. * *

Evaluation Order

* diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeAll.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeAll.java index f58a68dad2d7..197556e7ad3b 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeAll.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeAll.java @@ -45,17 +45,15 @@ * *

Inheritance and Execution Order

* - *

{@code @BeforeAll} methods are inherited from superclasses as long as - * they are not hidden (default mode with {@code static} modifier), - * overridden, or superseded (i.e., replaced based on - * signature only, irrespective of Java's visibility rules). Furthermore, - * {@code @BeforeAll} methods from superclasses will be executed before - * {@code @BeforeAll} methods in subclasses. + *

{@code @BeforeAll} methods are inherited from superclasses as long as they + * are not overridden according to the visibility rules of the Java + * language. Furthermore, {@code @BeforeAll} methods from superclasses will be + * executed before {@code @BeforeAll} methods in subclasses. * - *

Similarly, {@code @BeforeAll} methods declared in an interface are - * inherited as long as they are not hidden or overridden, - * and {@code @BeforeAll} methods from an interface will be executed before - * {@code @BeforeAll} methods in the class that implements the interface. + *

Similarly, {@code @BeforeAll} methods declared in an interface are inherited + * as long as they are not overridden, and {@code @BeforeAll} methods from an + * interface will be executed before {@code @BeforeAll} methods in the class that + * implements the interface. * *

JUnit Jupiter does not guarantee the execution order of multiple * {@code @BeforeAll} methods that are declared within a single test class or diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeEach.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeEach.java index 608ccd1f7cd5..7aee562c0ac8 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeEach.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/BeforeEach.java @@ -39,10 +39,9 @@ *

Inheritance and Execution Order

* *

{@code @BeforeEach} methods are inherited from superclasses as long as they - * are not overridden or superseded (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. + * are not overridden according to the visibility rules of the Java + * language. Furthermore, {@code @BeforeEach} methods from superclasses will be + * executed before {@code @BeforeEach} methods in subclasses. * *

Similarly, {@code @BeforeEach} methods declared as interface default * methods are inherited as long as they are not overridden, and diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/RepeatedTest.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/RepeatedTest.java index a15eaff2b756..063228c97486 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/RepeatedTest.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/RepeatedTest.java @@ -44,6 +44,13 @@ * create a custom composed annotation that inherits the semantics * of {@code @RepeatedTest}. * + *

Inheritance

+ * + *

{@code @RepeatedTest} methods are inherited from superclasses as long as + * they are not overridden according to the visibility rules of the Java + * language. Similarly, {@code @RepeatedTest} methods declared as interface + * default methods are inherited as long as they are not overridden. + * *

Test Execution Order

* *

By default, test methods will be ordered using an algorithm that is diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java index c8d08176c45d..f17d735904a4 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/Test.java @@ -34,6 +34,13 @@ *

{@code @Test} may also be used as a meta-annotation in order to create a * custom composed annotation that inherits the semantics of {@code @Test}. * + *

Inheritance

+ * + *

{@code @Test} methods are inherited from superclasses as long as they are + * not overridden according to the visibility rules of the Java language. + * Similarly, {@code @Test} methods declared as interface default methods + * are inherited as long as they are not overridden. + * *

Test Execution Order

* *

By default, test methods will be ordered using an algorithm that is diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java index 4f5c9921d768..dd17d2647186 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestFactory.java @@ -43,6 +43,13 @@ * resolved by {@link org.junit.jupiter.api.extension.ParameterResolver * ParameterResolvers}. * + *

Inheritance

+ * + *

{@code @TestFactory} methods are inherited from superclasses as long as + * they are not overridden according to the visibility rules of the Java + * language. Similarly, {@code @TestFactory} methods declared as interface + * default methods are inherited as long as they are not overridden. + * *

Test Execution Order

* *

By default, test methods will be ordered using an algorithm that is diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java index fccc258b8ef4..c9d337108405 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/TestTemplate.java @@ -49,6 +49,13 @@ * create a custom composed annotation that inherits the semantics * of {@code @TestTemplate}. * + *

Inheritance

+ * + *

{@code @TestTemplate} methods are inherited from superclasses as long as + * they are not overridden according to the visibility rules of the Java + * language. Similarly, {@code @TestTemplate} methods declared as interface + * default methods are inherited as long as they are not overridden. + * *

Test Execution Order

* *

By default, test methods will be ordered using an algorithm that is diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtendWith.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtendWith.java index 2c0c079ea007..036e7eb90396 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtendWith.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ExtendWith.java @@ -35,10 +35,10 @@ * *

Inheritance

* - *

{@code @ExtendWith} fields are inherited from superclasses as long as they - * are not hidden or overridden. Furthermore, {@code @ExtendWith} - * fields from superclasses will be registered before {@code @ExtendWith} fields - * in subclasses. + *

{@code @ExtendWith} fields are inherited from superclasses. Furthermore, + * {@code @ExtendWith} fields from superclasses will be registered before + * {@code @ExtendWith} fields in subclasses unless {@code @Order} is used to + * alter that behavior (see below). * *

Registration Order

* diff --git a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/RegisterExtension.java b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/RegisterExtension.java index 9c107b06f459..eb84ab641a8f 100644 --- a/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/RegisterExtension.java +++ b/junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/RegisterExtension.java @@ -65,10 +65,10 @@ * *

Inheritance

* - *

{@code @RegisterExtension} fields are inherited from superclasses as long - * as they are not hidden or overridden. Furthermore, - * {@code @RegisterExtension} fields from superclasses will be registered before - * {@code @RegisterExtension} fields in subclasses. + *

{@code @RegisterExtension} fields are inherited from superclasses. + * Furthermore, {@code @RegisterExtension} fields from superclasses will be + * registered before {@code @RegisterExtension} fields in subclasses unless + * {@code @Order} is used to alter that behavior (see below). * *

Registration Order

* diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java index 164eaa30fb42..ac4fd760523b 100644 --- a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java +++ b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java @@ -79,6 +79,14 @@ * to create a custom composed annotation that inherits the semantics * of {@code @ParameterizedTest}. * + *

Inheritance

+ * + *

{@code @ParameterizedTest} methods are inherited from superclasses as long + * as they are not overridden according to the visibility rules of the + * Java language. Similarly, {@code @ParameterizedTest} methods declared as + * interface default methods are inherited as long as they are not + * overridden. + * *

Test Execution Order

* *

By default, test methods will be ordered using an algorithm that is diff --git a/junit-platform-commons/src/main/java/org/junit/platform/commons/support/ReflectionSupport.java b/junit-platform-commons/src/main/java/org/junit/platform/commons/support/ReflectionSupport.java index 99e6ec7601ec..ab7c194fe35a 100644 --- a/junit-platform-commons/src/main/java/org/junit/platform/commons/support/ReflectionSupport.java +++ b/junit-platform-commons/src/main/java/org/junit/platform/commons/support/ReflectionSupport.java @@ -304,7 +304,7 @@ public static Object invokeMethod(Method method, Object target, Object... args) *

Fields declared in the same class or interface will be ordered using * an algorithm that is deterministic but intentionally nonobvious. * - *

The results will not contain fields that are hidden or + *

The results will not contain fields that are * {@linkplain Field#isSynthetic() synthetic}. * * @param clazz the class or interface in which to find the fields; never {@code null} @@ -331,7 +331,7 @@ public static List findFields(Class clazz, Predicate predicate, *

Fields declared in the same class or interface will be ordered using * an algorithm that is deterministic but intentionally nonobvious. * - *

The results will not contain fields that are hidden or + *

The results will not contain fields that are * {@linkplain Field#isSynthetic() synthetic}. * * @param clazz the class or interface in which to find the fields; never {@code null} @@ -416,8 +416,7 @@ public static Optional findMethod(Class clazz, String methodName, Cla * Find all distinct {@linkplain Method methods} of the supplied class or * interface that match the specified {@code predicate}. * - *

The results will not contain instance methods that are overridden - * or {@code static} methods that are hidden. + *

The results will not contain methods that are overridden. * *

If you are looking for methods annotated with a certain annotation * type, consider using @@ -442,8 +441,7 @@ public static List findMethods(Class clazz, Predicate predica * Find all distinct {@linkplain Method methods} of the supplied class or * interface that match the specified {@code predicate}. * - *

The results will not contain instance methods that are overridden - * or {@code static} methods that are hidden. + *

The results will not contain methods that are overridden. * *

If you are looking for methods annotated with a certain annotation * type, consider using diff --git a/junit-platform-commons/src/main/java/org/junit/platform/commons/util/ReflectionUtils.java b/junit-platform-commons/src/main/java/org/junit/platform/commons/util/ReflectionUtils.java index 248779d1f7f2..d448b96a12f9 100644 --- a/junit-platform-commons/src/main/java/org/junit/platform/commons/util/ReflectionUtils.java +++ b/junit-platform-commons/src/main/java/org/junit/platform/commons/util/ReflectionUtils.java @@ -87,7 +87,7 @@ public final class ReflectionUtils { * *

When set to {@code false} (either explicitly or implicitly), field and * method searches will adhere to Java semantics regarding whether a given - * field or method is visible or overridable, where the latter only applies + * field or method is visible or overridden, where the latter only applies * to methods. When set to {@code true}, the semantics used in JUnit 5 prior * to JUnit 5.11 (JUnit Platform 1.11) will be used, which means that fields * and methods can hide, shadow, or supersede fields and methods in supertypes @@ -1494,8 +1494,7 @@ public static Method getRequiredMethod(Class clazz, String methodName, Class< * that match the specified {@code predicate}, using top-down search semantics * within the type hierarchy. * - *

The results will not contain instance methods that are overridden - * or {@code static} methods that are hidden. + *

The results will not contain instance methods that are overridden. * * @param clazz the class or interface in which to find the methods; never {@code null} * @param predicate the method filter; never {@code null}