Replace opt-in annotation with extension method

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -139,7 +139,6 @@ endif::[]
 :BeforeAllCallback:                          {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/BeforeAllCallback.html[BeforeAllCallback]
 :BeforeEachCallback:                         {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/BeforeEachCallback.html[BeforeEachCallback]
 :BeforeTestExecutionCallback:                {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.html[BeforeTestExecutionCallback]
-:EnableTestScopedConstructorContext:         {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/EnableTestScopedConstructorContext.html[@EnableTestScopedConstructorContext]
 :ExecutableInvoker:                          {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ExecutableInvoker.html[ExecutableInvoker]
 :ExecutionCondition:                         {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ExecutionCondition.html[ExecutionCondition]
 :ExtendWith:                                 {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/ExtendWith.html[@ExtendWith]

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

@@ -58,10 +58,11 @@ JUnit repository on GitHub.
   extensions.
 * Allow determining "shared resources" at runtime via the new `@ResourceLock#providers`
   attribute that accepts implementations of `ResourceLocksProvider`.
-* `@EnableTestScopedConstructorContext` has been added to enable the use of a test-scoped
-  `ExtensionContext` while instantiating the test instance.
-  The behavior enabled by the annotation is expected to eventually become the default in
-  future versions of JUnit Jupiter.
+* Extensions that implement `TestInstancePreConstructCallback`, `TestInstanceFactory`,
+  `TestInstancePostProcessor`, `ParameterResolver`, or `InvocationInterceptor` may
+  override the `getTestInstantiationExtensionContextScope()` method to enable receiving
+  a test-scoped `ExtensionContext` in `Extension` methods called during test class
+  instantiation. This behavior will become the default in future versions of JUnit.
 * `@TempDir` is now supported on test class constructors.
 
 

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

@@ -383,8 +383,9 @@ instances and their lifecycle.
 
 [NOTE]
 ====
-You may annotate your extension with `{EnableTestScopedConstructorContext}` for revised
-handling of `CloseableResource` and to make test-specific data available to your implementation.
+You may override the `getTestInstantiationExtensionContextScope(...)` method to return
+`TEST_SCOPED` for revised handling of `CloseableResource` and to make test-specific data
+available to your implementation.
 ====
 
 [[extensions-test-instance-factories]]
@@ -415,8 +416,9 @@ registered for any specific test class.
 
 [NOTE]
 ====
-You may annotate your extension with `{EnableTestScopedConstructorContext}` for revised
-handling of `CloseableResource` and to make test-specific data available to your implementation.
+You may override the `getTestInstantiationExtensionContextScope(...)` method to return
+`TEST_SCOPED` for revised handling of `CloseableResource` and to make test-specific data
+available to your implementation.
 ====
 
 [[extensions-test-instance-post-processing]]
@@ -433,8 +435,9 @@ For a concrete example, consult the source code for the `{MockitoExtension}` and
 
 [NOTE]
 ====
-You may annotate your extension with `{EnableTestScopedConstructorContext}` for revised
-handling of `CloseableResource` and to make test-specific data available to your implementation.
+You may override the `getTestInstantiationExtensionContextScope(...)` method to return
+`TEST_SCOPED` for revised handling of `CloseableResource` and to make test-specific data
+available to your implementation.
 ====
 
 [[extensions-test-instance-pre-destroy-callback]]
@@ -485,10 +488,11 @@ those provided in `java.lang.reflect.Parameter` in order to avoid this bug in th
 
 [NOTE]
 ====
-You may annotate your extension with `{EnableTestScopedConstructorContext}` to support
-injecting test specific data into constructor parameters of the test instance.
-The annotation makes JUnit use a test-specific `ExtensionContext` while resolving
-constructor parameters, unless the lifecycle is set to `TestInstance.Lifecycle.PER_CLASS`.
+You may override the `getTestInstantiationExtensionContextScope(...)` method to return
+`TEST_SCOPED` to support injecting test specific data into constructor parameters of the
+test class instance. Doing so causes a test-specific `{ExtensionContext}` to be used while
+resolving constructor parameters, unless the
+<<writing-tests-test-instance-lifecycle, test instance lifecycle>> is set to `PER_CLASS`.
 ====
 
 [NOTE]
@@ -723,9 +727,9 @@ include::{testDir}/example/interceptor/SwingEdtInterceptor.java[tags=user_guide]
 
 [NOTE]
 ====
-You may annotate your extension with `{EnableTestScopedConstructorContext}` to make
-test-specific data available to your implementation of `interceptTestClassConstructor` and
-for a revised scope of the provided `Store` instance.
+You may override the `getTestInstantiationExtensionContextScope(...)` method to return
+`TEST_SCOPED` to make test-specific data available to your implementation of
+`interceptTestClassConstructor` and for a revised scope of the provided `Store` instance.
 ====
 
 [[extensions-test-templates]]

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

@@ -25,6 +25,7 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestFactory;
 import org.junit.jupiter.api.TestTemplate;
+import org.junit.jupiter.api.extension.ExtensionContext.Store;
 
 /**
  * {@code InvocationInterceptor} defines the API for {@link Extension
@@ -50,17 +51,18 @@
  * @see ExtensionContext
  */
 @API(status = STABLE, since = "5.10")
-public interface InvocationInterceptor extends Extension {
+public interface InvocationInterceptor extends TestInstantiationAwareExtension {
 
 	/**
 	 * Intercept the invocation of a test class constructor.
 	 *
 	 * <p>Note that the test class may <em>not</em> have been initialized
 	 * (static initialization) when this method is invoked.
 	 *
-	 * <p>You may annotate your extension with {@link EnableTestScopedConstructorContext}
-	 * to make test-specific data available to your implementation of this method and
-	 * for a revised scope of the provided `Store` instance.
+	 * <p>Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} to
+	 * make test-specific data available to the implementation of this method
+	 * and for a revised scope of the provided {@link Store Store} instance.
 	 *
 	 * @param invocation the invocation that is being intercepted; never
 	 * {@code null}

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

@@ -31,11 +31,14 @@
  * an argument for the parameter must be resolved at runtime by a
  * {@code ParameterResolver}.
  *
- * <p>You may annotate your extension with {@link EnableTestScopedConstructorContext}
- * to support injecting test specific data into constructor parameters of the test instance.
- * The annotation makes JUnit use a test-specific `ExtensionContext` while resolving
- * constructor parameters, unless the test class is annotated with
- * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}.
+ * <p>Extensions may override
+ * {@link #getTestInstantiationExtensionContextScope} to
+ * support injecting test specific data into constructor parameters of the test
+ * class instance. Returning
+ * {@link ExtensionContextScope#TEST_METHOD TEST_SCOPED} from this method,
+ * causes a test-specific {@link ExtensionContext} to be used while resolving
+ * constructor parameters, unless the lifecycle is set to
+ * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS}.
  *
  * <h2>Constructor Requirements</h2>
  *
@@ -51,7 +54,7 @@
  * @see TestInstancePreDestroyCallback
  */
 @API(status = STABLE, since = "5.0")
-public interface ParameterResolver extends Extension {
+public interface ParameterResolver extends TestInstantiationAwareExtension {
 
 	/**
 	 * Determine if this resolver supports resolution of an argument for the

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

@@ -52,15 +52,15 @@
  */
 @FunctionalInterface
 @API(status = STABLE, since = "5.7")
-public interface TestInstanceFactory extends Extension {
+public interface TestInstanceFactory extends TestInstantiationAwareExtension {
 
 	/**
 	 * Callback for creating a test instance for the supplied context.
 	 *
-	 * <p>You may annotate your extension with
-	 * {@link EnableTestScopedConstructorContext @EnableTestScopedConstructorContext}
-	 * for revised handling of {@link CloseableResource CloseableResource} and
-	 * to make test-specific data available to your implementation.
+	 * <p>Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} for
+	 * revised handling of {@link CloseableResource CloseableResource} and to
+	 * make test-specific data available to your implementation.
 	 *
 	 * <p><strong>Note</strong>: the {@code ExtensionContext} supplied to a
 	 * {@code TestInstanceFactory} will always return an empty

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

@@ -41,15 +41,15 @@
  */
 @FunctionalInterface
 @API(status = STABLE, since = "5.0")
-public interface TestInstancePostProcessor extends Extension {
+public interface TestInstancePostProcessor extends TestInstantiationAwareExtension {
 
 	/**
 	 * Callback for post-processing the supplied test instance.
 	 *
-	 * <p>You may annotate your extension with
-	 * {@link EnableTestScopedConstructorContext @EnableTestScopedConstructorContext}
-	 * for revised handling of {@link CloseableResource CloseableResource} and
-	 * to make test-specific data available to your implementation.
+	 * <p>Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} for
+	 * revised handling of {@link CloseableResource CloseableResource} and to
+	 * make test-specific data available to your implementation.
 	 *
 	 * <p><strong>Note</strong>: the {@code ExtensionContext} supplied to a
 	 * {@code TestInstancePostProcessor} will always return an empty

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

@@ -14,7 +14,6 @@
 
 import org.apiguardian.api.API;
 import org.junit.jupiter.api.TestInstance.Lifecycle;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
 
 /**
  * {@code TestInstancePreConstructCallback} defines the API for {@link Extension
@@ -45,15 +44,16 @@
  */
 @FunctionalInterface
 @API(status = STABLE, since = "5.11")
-public interface TestInstancePreConstructCallback extends Extension {
+public interface TestInstancePreConstructCallback extends TestInstantiationAwareExtension {
 
 	/**
 	 * Callback invoked prior to test instances being constructed.
 	 *
-	 * <p>You may annotate your extension with
-	 * {@link EnableTestScopedConstructorContext @EnableTestScopedConstructorContext}
-	 * for revised handling of {@link CloseableResource CloseableResource} and
-	 * to make test-specific data available to your implementation.
+	 * <p>Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} to
+	 * make test-specific data available to the implementation of this method
+	 * and for a revised scope of the provided
+	 * {@link ExtensionContext.Store Store} instance.
 	 *
 	 * @param factoryContext the context for the test instance about to be instantiated;
 	 * never {@code null}