Return enum instead of boolean

This avoids being able to opt out should the default be changed to
test-scoped.

Author: marcphilipp

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

@@ -58,10 +58,9 @@ JUnit repository on GitHub.
   extensions.
 * Allow determining "shared resources" at runtime via the new `@ResourceLock#providers`
   attribute that accepts implementations of `ResourceLocksProvider`.
-* Overriding `Extension.isTestScopedConstructorContextEnabled()` enables using a
-  test-scoped `ExtensionContext` in `Extension` methods called during test class
-  instantiation.
-  This behavior will become the default in future versions of JUnit Jupiter.
+* Overriding `Extension.getExtensionContextScopeDuringTestInstanceConstruction()` enables
+  using a test-scoped `ExtensionContext` in `Extension` methods called during test class
+  construction. 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 override the `{Extension}.isTestScopedConstructorContextEnabled(...)` method to
-return `true` for revised handling of `CloseableResource` and to make test-specific data
+You may override the
+`{Extension}.getExtensionContextScopeDuringTestInstanceConstruction(...)` method to return
+`TEST_SCOPED` for revised handling of `CloseableResource` and to make test-specific data
 available to your implementation.
 ====
 
@@ -416,8 +417,9 @@ registered for any specific test class.
 
 [NOTE]
 ====
-You may override the `{Extension}.isTestScopedConstructorContextEnabled(...)` method to
-return `true` for revised handling of `CloseableResource` and to make test-specific data
+You may override the
+`{Extension}.getExtensionContextScopeDuringTestInstanceConstruction(...)` method to return
+`TEST_SCOPED` for revised handling of `CloseableResource` and to make test-specific data
 available to your implementation.
 ====
 
@@ -435,8 +437,9 @@ For a concrete example, consult the source code for the `{MockitoExtension}` and
 
 [NOTE]
 ====
-You may override the `{Extension}.isTestScopedConstructorContextEnabled(...)` method to
-return `true` for revised handling of `CloseableResource` and to make test-specific data
+You may override the
+`{Extension}.getExtensionContextScopeDuringTestInstanceConstruction(...)` method to return
+`TEST_SCOPED` for revised handling of `CloseableResource` and to make test-specific data
 available to your implementation.
 ====
 
@@ -488,8 +491,9 @@ those provided in `java.lang.reflect.Parameter` in order to avoid this bug in th
 
 [NOTE]
 ====
-You may override the `{Extension}.isTestScopedConstructorContextEnabled(...)` method to
-return `true` to support injecting test specific data into constructor parameters of the
+You may override the
+`{Extension}.getExtensionContextScopeDuringTestInstanceConstruction(...)` method to return
+`TEST_SCOPED` to support injecting test specific data into constructor parameters of the
 test 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`.
@@ -727,8 +731,9 @@ include::{testDir}/example/interceptor/SwingEdtInterceptor.java[tags=user_guide]
 
 [NOTE]
 ====
-You may override the `{Extension}.isTestScopedConstructorContextEnabled(...)` method to
-return `true` to make test-specific data available to your implementation of
+You may override the
+`{Extension}.getExtensionContextScopeDuringTestInstanceConstruction(...)` 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.
 ====
 

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

@@ -10,6 +10,7 @@
 
 package org.junit.jupiter.api.extension;
 
+import static org.apiguardian.api.API.Status.DEPRECATED;
 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
@@ -47,10 +48,11 @@ public interface Extension {
 	 * Whether this extension should receive a test-scoped
 	 * {@link ExtensionContext} during the creation of test instances.
 	 *
-	 * <p>If an extension returns {@code true} from this method, the following\
-	 * extension methods will be called with a test-scoped
-	 * {@link ExtensionContext}, unless the test class is annotated with
-	 * {@link TestInstance @TestInstance(Lifecycle.PER_CLASS)}:
+	 * <p>If an extension returns
+	 * {@link ExtensionContextScope#TEST_SCOPED TEST_SCOPED} from this method,
+	 * the following extension methods will be called with a test-scoped
+	 * {@link ExtensionContext} instead of a class-scoped one, unless the
+	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used:
 	 *
 	 * <ul>
 	 * <li>{@link InvocationInterceptor#interceptTestClassConstructor}</li>
@@ -60,8 +62,8 @@ public interface Extension {
 	 * <li>{@link TestInstanceFactory}</li>
 	 * </ul>
 	 *
-	 * <p>Implementations of these extension callbacks can observe the following
-	 * differences if they are returning {@code true} from this method:
+	 * <p>In such cases, implementations of these extension callbacks can
+	 * observe the following differences:
 	 *
 	 * <ul>
 	 * <li>{@link ExtensionContext#getElement() getElement()} may refer to the
@@ -81,16 +83,16 @@ public interface Extension {
 	 * </ul>
 	 *
 	 * <p><strong>Note</strong>: The behavior which is enabled by returning
-	 * {@code true} from this method will become the default in future versions
-	 * of JUnit Jupiter. To ensure future compatibility, extension implementors
-	 * are therefore advised to opt in, even if they don't require the new
-	 * functionality.
+	 * {@link ExtensionContextScope#TEST_SCOPED TEST_SCOPED} from this method
+	 * will become the default in future versions of JUnit. To ensure future
+	 * compatibility, extension implementors are therefore advised to opt in,
+	 * even if they don't require the new functionality.
 	 *
 	 * @implNote There are no guarantees about how often this method is called.
 	 *           Therefore, implementations should be idempotent and avoid side
 	 *           effects. They may, however, cache the result for performance in
 	 *           the {@link Store Store} of the supplied
-	 *           {@link ExtensionContext}.
+	 *           {@link ExtensionContext}, if necessary.
 	 * @param rootContext the root extension context to allow inspection of
 	 *                    configuration parameters; never {@code null}
 	 * @since 5.12
@@ -101,8 +103,37 @@ public interface Extension {
 	 * @see TestInstanceFactory
 	 */
 	@API(status = EXPERIMENTAL, since = "5.12")
-	default boolean isTestScopedConstructorContextEnabled(ExtensionContext rootContext) {
-		return false;
+	default ExtensionContextScope getExtensionContextScopeDuringTestInstanceConstruction(ExtensionContext rootContext) {
+		return ExtensionContextScope.DEFAULT;
+	}
+
+	/**
+	 * {@code ExtensionContextScope} is used to define the scope of the
+	 * {@link ExtensionContext} passed to an extension during the creation of
+	 * test instances.
+	 *
+	 * @since 5.12
+	 * @see org.junit.jupiter.api.extension.Extension#getExtensionContextScopeDuringTestInstanceConstruction
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	enum ExtensionContextScope {
+
+		/**
+		 * The extension should receive an {@link ExtensionContext} scoped to
+		 * the test class.
+		 *
+		 * @deprecated This behavior will be removed from future versions of
+		 * JUnit and {@link #TEST_SCOPED} will become the default.
+		 */
+		@API(status = DEPRECATED, since = "5.12") //
+		@Deprecated
+		DEFAULT,
+
+		/**
+		 * The extension should receive an {@link ExtensionContext} scoped to
+		 * the test instance.
+		 */
+		TEST_SCOPED
 	}
 
 }

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

@@ -59,9 +59,10 @@ public interface InvocationInterceptor extends Extension {
 	 * <p>Note that the test class may <em>not</em> have been initialized
 	 * (static initialization) when this method is invoked.
 	 *
-	 * <p>Extensions may override {@link #isTestScopedConstructorContextEnabled}
-	 * to make test-specific data available to the implementation of this method
-	 * and for a revised scope of the provided {@link Store} instance.
+	 * <p>Extensions may override
+	 * {@link #getExtensionContextScopeDuringTestInstanceConstruction} to make
+	 * test-specific data available to the implementation of this method and for
+	 * a revised scope of the provided {@link 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,13 @@
  * an argument for the parameter must be resolved at runtime by a
  * {@code ParameterResolver}.
  *
- * <p>Extensions may override {@link #isTestScopedConstructorContextEnabled}
- * to support injecting test specific data into constructor parameters of the
- * test instance. Returning {@code true} 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}.
+ * <p>Extensions may override
+ * {@link #getExtensionContextScopeDuringTestInstanceConstruction} to support
+ * injecting test specific data into constructor parameters of the test
+ * instance. Returning {@link ExtensionContextScope#TEST_SCOPED 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>
  *

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

@@ -57,9 +57,10 @@ public interface TestInstanceFactory extends Extension {
 	/**
 	 * Callback for creating a test instance for the supplied context.
 	 *
-	 * <p>Extensions may override {@link #isTestScopedConstructorContextEnabled}
-	 * for revised handling of {@link CloseableResource CloseableResource} and
-	 * to make test-specific data available to your implementation.
+	 * <p>Extensions may override
+	 * {@link #getExtensionContextScopeDuringTestInstanceConstruction} 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

@@ -46,9 +46,10 @@ public interface TestInstancePostProcessor extends Extension {
 	/**
 	 * Callback for post-processing the supplied test instance.
 	 *
-	 * <p>Extensions may override {@link #isTestScopedConstructorContextEnabled}
-	 * for revised handling of {@link CloseableResource CloseableResource} and
-	 * to make test-specific data available to your implementation.
+	 * <p>Extensions may override
+	 * {@link #getExtensionContextScopeDuringTestInstanceConstruction} 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

@@ -49,9 +49,11 @@ public interface TestInstancePreConstructCallback extends Extension {
 	/**
 	 * Callback invoked prior to test instances being constructed.
 	 *
-	 * <p>Extensions may override {@link #isTestScopedConstructorContextEnabled}
-	 * to make test-specific data available to the implementation of this method
-	 * and for a revised scope of the provided {@link ExtensionContext.Store} instance.
+	 * <p>Extensions may override
+	 * {@link #getExtensionContextScopeDuringTestInstanceConstruction} 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}

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/execution/ExtensionContextSupplier.java

@@ -11,6 +11,7 @@
 package org.junit.jupiter.engine.execution;
 
 import static org.apiguardian.api.API.Status.INTERNAL;
+import static org.junit.jupiter.api.extension.Extension.ExtensionContextScope.TEST_SCOPED;
 
 import org.apiguardian.api.API;
 import org.junit.jupiter.api.extension.Extension;
@@ -34,12 +35,16 @@ public ExtensionContextSupplier(ExtensionContext currentExtensionContext, Extens
 	}
 
 	public ExtensionContext get(Extension extension) {
-		if (currentExtensionContext == legacyExtensionContext
-				|| extension.isTestScopedConstructorContextEnabled(currentExtensionContext.getRoot())) {
+		if (currentExtensionContext == legacyExtensionContext || isTestScoped(extension)) {
 			return currentExtensionContext;
 		}
 		else {
 			return legacyExtensionContext;
 		}
 	}
+
+	private boolean isTestScoped(Extension extension) {
+		ExtensionContext rootContext = currentExtensionContext.getRoot();
+		return extension.getExtensionContextScopeDuringTestInstanceConstruction(rootContext) == TEST_SCOPED;
+	}
 }

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

@@ -12,6 +12,7 @@
 
 import static java.nio.file.FileVisitResult.CONTINUE;
 import static java.util.stream.Collectors.joining;
+import static org.junit.jupiter.api.extension.Extension.ExtensionContextScope.TEST_SCOPED;
 import static org.junit.jupiter.api.io.CleanupMode.DEFAULT;
 import static org.junit.jupiter.api.io.CleanupMode.NEVER;
 import static org.junit.jupiter.api.io.CleanupMode.ON_SUCCESS;
@@ -93,8 +94,8 @@ public TempDirectory(JupiterConfiguration configuration) {
 	}
 
 	@Override
-	public boolean isTestScopedConstructorContextEnabled(ExtensionContext rootContext) {
-		return true;
+	public ExtensionContextScope getExtensionContextScopeDuringTestInstanceConstruction(ExtensionContext rootContext) {
+		return TEST_SCOPED;
 	}
 
 	/**