Polish documentation for test-scoped extension context opt-in

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

@@ -382,10 +382,11 @@ in combination with other extensions to prepare constructor parameters or keepin
 instances and their lifecycle.
 
 [NOTE]
+.Accessing the test-scoped `ExtensionContext`
 ====
 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.
+`TEST_METHOD` to make test-specific data available to your extension implementation or if
+you want to <<extensions-keeping-state, keep state>> on the test method level.
 ====
 
 [[extensions-test-instance-factories]]
@@ -415,10 +416,11 @@ registered for any specific test class.
 ====
 
 [NOTE]
+.Accessing the test-scoped `ExtensionContext`
 ====
 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.
+`TEST_METHOD` to make test-specific data available to your extension implementation or if
+you want to <<extensions-keeping-state, keep state>> on the test method level.
 ====
 
 [[extensions-test-instance-post-processing]]
@@ -434,10 +436,11 @@ For a concrete example, consult the source code for the `{MockitoExtension}` and
 `{SpringExtension}`.
 
 [NOTE]
+.Accessing the test-scoped `ExtensionContext`
 ====
 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.
+`TEST_METHOD` to make test-specific data available to your extension implementation or if
+you want to <<extensions-keeping-state, keep state>> on the test method level.
 ====
 
 [[extensions-test-instance-pre-destroy-callback]]
@@ -487,15 +490,17 @@ those provided in `java.lang.reflect.Parameter` in order to avoid this bug in th
 ====
 
 [NOTE]
+.Accessing the test-scoped `ExtensionContext`
 ====
 You may override the `getTestInstantiationExtensionContextScope(...)` method to return
-`TEST_SCOPED` to support injecting test specific data into constructor parameters of the
+`TEST_METHOD` 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]
+[TIP]
+.Parameter resolution for methods called from extensions
 ====
 Other extensions can also leverage registered `ParameterResolvers` for method and
 constructor invocations, using the `{ExecutableInvoker}` available via the
@@ -726,10 +731,12 @@ include::{testDir}/example/interceptor/SwingEdtInterceptor.java[tags=user_guide]
 ----
 
 [NOTE]
+.Accessing the test-scoped `ExtensionContext`
 ====
 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.
+`TEST_METHOD` to make test-specific data available to your extension implementation of
+`interceptTestClassConstructor` or if you want to <<extensions-keeping-state, keep state>>
+on the test method level.
 ====
 
 [[extensions-test-templates]]

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

@@ -24,8 +24,8 @@
 import org.junit.jupiter.api.DynamicTest;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestFactory;
+import org.junit.jupiter.api.TestInstance;
 import org.junit.jupiter.api.TestTemplate;
-import org.junit.jupiter.api.extension.ExtensionContext.Store;
 
 /**
  * {@code InvocationInterceptor} defines the API for {@link Extension
@@ -59,10 +59,15 @@ public interface InvocationInterceptor extends TestInstantiationAwareExtension {
 	 * <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 #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.
+	 * <p>By default, the supplied {@link ExtensionContext} represents the test
+	 * class that's about to be constructed. Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} to return
+	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} in order to change
+	 * the scope of the {@code ExtensionContext} to the test method, unless the
+	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.
+	 * Changing the scope makes test-specific data available to the
+	 * implementation of this method and allows keeping state on the test level
+	 * by using the provided {@link ExtensionContext.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,14 +31,16 @@
  * an argument for the parameter must be resolved at runtime by a
  * {@code ParameterResolver}.
  *
- * <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}.
+ * <p>By default, when the methods in this interface are called for a test class
+ * constructor, the supplied {@link ExtensionContext} represents the test
+ * class that's about to be instantiated. Extensions may override
+ * {@link #getTestInstantiationExtensionContextScope} to return
+ * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} in order to change
+ * the scope of the {@code ExtensionContext} to the test method, unless the
+ * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.
+ * Changing the scope makes test-specific data available to the
+ * implementation of this method and allows keeping state on the test level
+ * by using the provided {@link ExtensionContext.Store Store} instance.
  *
  * <h2>Constructor Requirements</h2>
  *

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

@@ -13,7 +13,7 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import org.apiguardian.api.API;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
+import org.junit.jupiter.api.TestInstance;
 
 /**
  * {@code TestInstanceFactory} defines the API for {@link Extension
@@ -57,10 +57,15 @@ public interface TestInstanceFactory extends TestInstantiationAwareExtension {
 	/**
 	 * Callback for creating a test instance for the supplied context.
 	 *
-	 * <p>Extensions may override
-	 * {@link #getTestInstantiationExtensionContextScope} for
-	 * revised handling of {@link CloseableResource CloseableResource} and to
-	 * make test-specific data available to your implementation.
+	 * <p>By default, the supplied {@link ExtensionContext} represents the test
+	 * class that's about to be instantiated. Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} to return
+	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} in order to change
+	 * the scope of the {@code ExtensionContext} to the test method, unless the
+	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.
+	 * Changing the scope makes test-specific data available to the
+	 * implementation of this method and allows keeping state on the test level
+	 * by using the provided {@link ExtensionContext.Store Store} instance.
 	 *
 	 * <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

@@ -13,7 +13,7 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import org.apiguardian.api.API;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
+import org.junit.jupiter.api.TestInstance;
 
 /**
  * {@code TestInstancePostProcessor} defines the API for {@link Extension
@@ -46,10 +46,15 @@ public interface TestInstancePostProcessor extends TestInstantiationAwareExtensi
 	/**
 	 * Callback for post-processing the supplied test instance.
 	 *
-	 * <p>Extensions may override
-	 * {@link #getTestInstantiationExtensionContextScope} for
-	 * revised handling of {@link CloseableResource CloseableResource} and to
-	 * make test-specific data available to your implementation.
+	 * <p>By default, the supplied {@link ExtensionContext} represents the test
+	 * class that's being post-processed. Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} to return
+	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} in order to change
+	 * the scope of the {@code ExtensionContext} to the test method, unless the
+	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.
+	 * Changing the scope makes test-specific data available to the
+	 * implementation of this method and allows keeping state on the test level
+	 * by using the provided {@link ExtensionContext.Store Store} instance.
 	 *
 	 * <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

@@ -13,6 +13,7 @@
 import static org.apiguardian.api.API.Status.STABLE;
 
 import org.apiguardian.api.API;
+import org.junit.jupiter.api.TestInstance;
 import org.junit.jupiter.api.TestInstance.Lifecycle;
 
 /**
@@ -49,11 +50,15 @@ public interface TestInstancePreConstructCallback extends TestInstantiationAware
 	/**
 	 * Callback invoked prior to test instances being constructed.
 	 *
-	 * <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.
+	 * <p>By default, the supplied {@link ExtensionContext} represents the test
+	 * class that's about to be constructed. Extensions may override
+	 * {@link #getTestInstantiationExtensionContextScope} to return
+	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} in order to change
+	 * the scope of the {@code ExtensionContext} to the test method, unless the
+	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.
+	 * Changing the scope makes test-specific data available to the
+	 * implementation of this method and allows keeping state on the test level
+	 * by using the provided {@link ExtensionContext.Store Store} instance.
 	 *
 	 * @param factoryContext the context for the test instance about to be instantiated;
 	 * never {@code null}