Polishing

Issue: #910

Author: sbrannen

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

@@ -176,7 +176,12 @@ private TestInstanceProvider testInstanceProvider(JupiterEngineExecutionContext
 		if (this.lifecycle == Lifecycle.PER_CLASS) {
 			// Eagerly load test instance for BeforeAllCallbacks, if necessary,
 			// and store the instance in the ExtensionContext.
+			// Note: as a side effect, instantiateAndPostProcessTestInstance() also stores
+			// the instance it creates in the "current" extension context.
 			Object instance = instantiateAndPostProcessTestInstance(parentExecutionContext, extensionContext, registry);
+
+			// Return a TestInstanceProvider that additionally sets the test instance
+			// in the supplied child extension context (e.g., a MethodExtensionContext).
 			return (childContext, childRegistry) -> {
 				childContext.setTestInstance(instance);
 				return instance;
@@ -188,6 +193,14 @@ private TestInstanceProvider testInstanceProvider(JupiterEngineExecutionContext
 			childContext, childRegistry.orElse(registry));
 	}
 
+	/**
+	 * Instantiate the test instance; set the test instance in the supplied
+	 * extension context; and post process the test instance.
+	 *
+	 * @see #instantiateTestClass
+	 * @see AbstractExtensionContext#setTestInstance
+	 * @see #invokeTestInstancePostProcessors
+	 */
 	private Object instantiateAndPostProcessTestInstance(JupiterEngineExecutionContext context,
 			AbstractExtensionContext<?> extensionContext, ExtensionRegistry registry) {
 

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

@@ -82,6 +82,11 @@ public JupiterEngineExecutionContext prepare(JupiterEngineExecutionContext conte
 		ThrowableCollector throwableCollector = new ThrowableCollector();
 		AbstractExtensionContext<?> extensionContext = new MethodExtensionContext(context.getExtensionContext(),
 			context.getExecutionListener(), this, throwableCollector);
+
+		// Even though we (intentionally) ignore the return value, the following line
+		// is required since the configured TestInstanceProvider is responsible for
+		// setting the test instance in the supplied extension context.
+		// See ClassTestDescriptor#testInstanceProvider(...) for details.
 		context.getTestInstanceProvider().getTestInstance(extensionContext, Optional.of(registry));
 
 		// @formatter:off
@@ -100,6 +105,7 @@ protected ExtensionRegistry populateNewExtensionRegistry(JupiterEngineExecutionC
 	@Override
 	public JupiterEngineExecutionContext execute(JupiterEngineExecutionContext context,
 			DynamicTestExecutor dynamicTestExecutor) throws Exception {
+
 		ThrowableCollector throwableCollector = context.getThrowableCollector();
 
 		// @formatter:off

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

@@ -61,8 +61,10 @@ public JupiterEngineExecutionContext prepare(JupiterEngineExecutionContext conte
 
 		AbstractExtensionContext<?> extensionContext = new TestTemplateExtensionContext(context.getExtensionContext(),
 			context.getExecutionListener(), this);
-		// We don't require a test instance here but provide it to extensions should the enclosing class's
-		// ExtensionContext already contain one.
+
+		// We don't require a test instance here, but we are responsible for providing it
+		// to extensions if the enclosing class's ExtensionContext already contains one.
+		// See ClassTestDescriptor#testInstanceProvider(...) for details.
 		extensionContext.setTestInstance(context.getExtensionContext().getTestInstance().orElse(null));
 
 		// @formatter:off

junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/TestInstanceLifecycleTests.java

@@ -912,7 +912,6 @@ public void postProcessTestInstance(ExtensionContext context) {
 			});
 			String key = postProcessTestInstanceKey(testInstance.getClass(), context.getTestClass().get(),
 				context.getTestMethod().map(Method::getName).orElse(null));
-			System.out.println(testInstance.getClass() + " : " + key);
 			instanceMap.put(key, testInstance);
 		}