Convert MethodParameterResolver to generic ParameterResolver API

Prior to this commit, the MethodParameterResolver API could only be
applied to methods. In addition, the MethodInvocationContext API
needlessly stored the method which could be retrieved directly from the
supplied Parameter.

This commit addresses these issues by converting the
MethodParameterResolver into a generic ParameterResolver API that can
be used to resolve parameters for both methods and constructors. At the
moment, however, there is no first-class support for resolving
constructor parameters in the JUnit 5 TestEngine.

Specifically, this commit includes the following changes.

 - Renamed MethodParameterResolver to ParameterResolver
 - Replaced MethodInvocationContext arguments in ParameterResolver with
   Optional<Object> for the target of method invocations
 - Moved MethodInvocationContext to the junit5-engine module for
   internal use

In addition, this commit introduces a proof of concept implementation
for constructor injection in the form of a ConstructorInvoker which is
tested in ParameterResolverTests.constructorInjectionProofOfConcept().

Closes: #267

documentation/src/docs/asciidoc/extensions.adoc

@@ -124,12 +124,12 @@ For concrete examples, consult the source code for the `{MockitoExtension}` and
 
 === Parameter Resolution
 
-`{MethodParameterResolver}` is an `Extension` strategy for dynamically resolving
-method parameters at runtime.
+`{ParameterResolver}` defines the `Extension` API for dynamically resolving
+parameters at runtime.
 
 If a `@Test`, `@BeforeEach`, `@AfterEach` , `@BeforeAll` or `@AfterAll` method accepts a
-parameter, the parameter must be _resolved_ at runtime by a `MethodParameterResolver`. A
-`MethodParameterResolver` can either be built-in (see `{TestInfoParameterResolver}`) or
+parameter, the parameter must be _resolved_ at runtime by a `ParameterResolver`. A
+`ParameterResolver` can either be built-in (see `{TestInfoParameterResolver}`) or
 <<extension-registration,registered by the user>>. Generally speaking, parameters may be
 resolved by _name_, _type_, _annotation_, or any combination thereof. For concrete examples,
 consult the source code for `{CustomTypeParameterResolver}` and

documentation/src/docs/asciidoc/index.adoc

@@ -33,7 +33,7 @@ Stefan Bechtold; Sam Brannen; Johannes Link; Matthias Merdes; Marc Philipp
 :ExtensionRegistrar:                {master-branch}/junit5-api/src/main/java/org/junit/gen5/api/extension/ExtensionRegistrar.java[ExtensionRegistrar]
 :TestInstancePostProcessor:         {master-branch}/junit5-api/src/main/java/org/junit/gen5/api/extension/TestInstancePostProcessor.java[TestInstancePostProcessor]
 :JUnit5-Runner:                     {master-branch}/junit4-runner/src/main/java/org/junit/gen5/junit4/runner/JUnit5.java[JUnit5]
-:MethodParameterResolver:           {master-branch}/junit5-api/src/main/java/org/junit/gen5/api/extension/MethodParameterResolver.java[MethodParameterResolver]
+:ParameterResolver:                 {master-branch}/junit5-api/src/main/java/org/junit/gen5/api/extension/ParameterResolver.java[ParameterResolver]
 :MockitoExtension:                  {junit5-samples-repo}/blob/master/junit5-mockito-extension/src/main/java/com/example/mockito/MockitoExtension.java[MockitoExtension]
 :SpringExtension:                   https://github.com/sbrannen/spring-test-junit5/blob/master/src/main/java/org/springframework/test/context/junit5/SpringExtension.java[SpringExtension]
 :SummaryGeneratingListener:         {master-branch}/junit-launcher/src/main/java/org/junit/gen5/launcher/listeners/SummaryGeneratingListener.java[SummaryGeneratingListener]

documentation/src/docs/asciidoc/writing-tests.adoc

@@ -156,10 +156,10 @@ with the standard `Runner` implementations). As one of the major changes in JUni
 methods are now permitted to have parameters. This allows for greater flexibility and
 enables method-level _Dependency Injection_.
 
-`{MethodParameterResolver}` defines the API for test extensions that wish to
-_dynamically_ resolve method parameters at runtime. If a `@Test`, `@BeforeEach`,
-`@AfterEach`, `@BeforeAll`, or `@AfterAll` method accepts a parameter, the parameter must
-be resolved at runtime by a registered `MethodParameterResolver`.
+`{ParameterResolver}` defines the API for test extensions that wish to _dynamically_
+resolve parameters at runtime. If a `@Test`, `@BeforeEach`, `@AfterEach`, `@BeforeAll`,
+or `@AfterAll` method accepts a parameter, the parameter must be resolved at runtime by
+a registered `ParameterResolver`.
 
 There are currently two built-in resolvers that are registered automatically.
 
@@ -199,7 +199,7 @@ include::{testDir}/example/TestReporterDemo.java[tags=user_guide]
 Other parameter resolvers must be explicitly enabled by registering a <<extension-model,
 test extension>> via `@ExtendWith`.
 
-* Check out the `{MockitoExtension}` for an example of a `{MethodParameterResolver}`. While not
+* Check out the `{MockitoExtension}` for an example of a `{ParameterResolver}`. While not
   intended to be production-ready, it demonstrates the simplicity and expressiveness of
   both the extension model and the parameter resolution process. `MyMockitoTest`
   demonstrates how to inject Mockito mocks into `@BeforeEach` and `@Test` methods.

junit-tests/src/test/java/org/junit/gen5/console/tasks/TempDirectory.java

@@ -22,19 +22,19 @@
 import java.nio.file.Path;
 import java.nio.file.SimpleFileVisitor;
 import java.nio.file.attribute.BasicFileAttributes;
+import java.util.Optional;
 
 import org.junit.gen5.api.extension.AfterEachCallback;
 import org.junit.gen5.api.extension.ExtensionContext;
 import org.junit.gen5.api.extension.ExtensionContext.Namespace;
-import org.junit.gen5.api.extension.MethodInvocationContext;
-import org.junit.gen5.api.extension.MethodParameterResolver;
 import org.junit.gen5.api.extension.ParameterResolutionException;
+import org.junit.gen5.api.extension.ParameterResolver;
 import org.junit.gen5.api.extension.TestExtensionContext;
 
 /**
  * @since 5.0
  */
-public class TempDirectory implements AfterEachCallback, MethodParameterResolver {
+public class TempDirectory implements AfterEachCallback, ParameterResolver {
 
 	@Target(ElementType.PARAMETER)
 	@Retention(RetentionPolicy.RUNTIME)
@@ -45,16 +45,12 @@ public class TempDirectory implements AfterEachCallback, MethodParameterResolver
 	private static final String KEY = "tempDirectory";
 
 	@Override
-	public boolean supports(Parameter parameter, MethodInvocationContext methodInvocationContext,
-			ExtensionContext extensionContext) throws ParameterResolutionException {
-
+	public boolean supports(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext) {
 		return parameter.isAnnotationPresent(Root.class) && parameter.getType() == Path.class;
 	}
 
 	@Override
-	public Object resolve(Parameter parameter, MethodInvocationContext methodInvocationContext,
-			ExtensionContext context) throws ParameterResolutionException {
-
+	public Object resolve(Parameter parameter, Optional<Object> target, ExtensionContext context) {
 		return getLocalStore(context).getOrComputeIfAbsent(KEY, key -> createTempDirectory(context));
 	}
 

junit-tests/src/test/java/org/junit/gen5/engine/junit5/execution/MethodInvokerTests.java

@@ -19,13 +19,13 @@
 import java.lang.reflect.Method;
 import java.lang.reflect.Parameter;
 import java.math.BigDecimal;
+import java.util.Optional;
 import java.util.function.Function;
 
 import org.junit.gen5.api.Test;
 import org.junit.gen5.api.extension.ExtensionContext;
-import org.junit.gen5.api.extension.MethodInvocationContext;
-import org.junit.gen5.api.extension.MethodParameterResolver;
 import org.junit.gen5.api.extension.ParameterResolutionException;
+import org.junit.gen5.api.extension.ParameterResolver;
 import org.junit.gen5.engine.junit5.extension.ExtensionRegistry;
 
 /**
@@ -52,7 +52,7 @@ void invokingMethodsWithoutParameterDoesNotDependOnExtensions() throws Exception
 	}
 
 	@Test
-	void resolveArgumentsViaMethodParameterResolver() {
+	void resolveArgumentsViaParameterResolver() {
 		testMethodWithASingleStringParameter();
 		thereIsAParameterResolverThatResolvesTheParameterTo("argument");
 
@@ -64,15 +64,15 @@ void resolveArgumentsViaMethodParameterResolver() {
 	@Test
 	void resolveMultipleArguments() {
 		testMethodWith("multipleParameters", String.class, String.class, String.class);
-		register(ConfigurableMethodParameterResolver.supportsAndResolvesTo(Parameter::getName));
+		register(ConfigurableParameterResolver.supportsAndResolvesTo(Parameter::getName));
 
 		invokeMethod();
 
 		verify(instance).multipleParameters("arg0", "arg1", "arg2");
 	}
 
 	@Test
-	void onlyConsiderMethodParameterResolversThatSupportAParticularParameter() {
+	void onlyConsiderParameterResolversThatSupportAParticularParameter() {
 		testMethodWithASingleStringParameter();
 		thereIsAParameterResolverThatDoesNotSupportThisParameter();
 		thereIsAParameterResolverThatResolvesTheParameterTo("something");
@@ -83,18 +83,18 @@ void onlyConsiderMethodParameterResolversThatSupportAParticularParameter() {
 	}
 
 	@Test
-	void passContextInformationToMethodParameterResolverMethods() {
+	void passContextInformationToParameterResolverMethods() {
 		anyTestMethodWithAtLeasOneParameter();
 		this.extensionContext = mock(ExtensionContext.class);
-		ArgumentRecordingMethodParameterResolver extension = new ArgumentRecordingMethodParameterResolver();
+		ArgumentRecordingParameterResolver extension = new ArgumentRecordingParameterResolver();
 		register(extension);
 
 		invokeMethod();
 
 		assertSame(extensionContext, extension.supportsArguments.extensionContext);
-		assertSame(methodInvocationContext, extension.supportsArguments.methodInvocationContext);
+		assertSame(instance, extension.supportsArguments.target.get());
 		assertSame(extensionContext, extension.resolveArguments.extensionContext);
-		assertSame(methodInvocationContext, extension.resolveArguments.methodInvocationContext);
+		assertSame(instance, extension.resolveArguments.target.get());
 	}
 
 	@Test
@@ -132,7 +132,7 @@ void reportThatNullIsNotAViableArgumentIfAPrimitiveTypeIsExpected() {
 	}
 
 	@Test
-	void reportIfThereIsNoMethodParameterResolverThatSupportsTheParameter() {
+	void reportIfThereIsNoParameterResolverThatSupportsTheParameter() {
 		testMethodWithASingleStringParameter();
 
 		ParameterResolutionException caught = expectThrows(ParameterResolutionException.class, this::invokeMethod);
@@ -141,7 +141,7 @@ void reportIfThereIsNoMethodParameterResolverThatSupportsTheParameter() {
 	}
 
 	@Test
-	void reportIfThereAreMultipleMethodParameterResolversThatSupportTheParameter() {
+	void reportIfThereAreMultipleParameterResolversThatSupportTheParameter() {
 		testMethodWithASingleStringParameter();
 		thereIsAParameterResolverThatResolvesTheParameterTo("one");
 		thereIsAParameterResolverThatResolvesTheParameterTo("two");
@@ -151,7 +151,7 @@ void reportIfThereAreMultipleMethodParameterResolversThatSupportTheParameter() {
 		// @formatter:off
 		assertThat(caught.getMessage())
 				.contains("parameter [java.lang.String arg0]")
-				.contains(ConfigurableMethodParameterResolver.class.getName() + ", " + ConfigurableMethodParameterResolver.class.getName());
+				.contains(ConfigurableParameterResolver.class.getName() + ", " + ConfigurableParameterResolver.class.getName());
 		// @formatter:on
 	}
 
@@ -197,18 +197,18 @@ private IllegalArgumentException anyExceptionButParameterResolutionException() {
 	}
 
 	private void throwDuringParameterResolution(RuntimeException parameterResolutionException) {
-		register(ConfigurableMethodParameterResolver.onAnyCallThrow(parameterResolutionException));
+		register(ConfigurableParameterResolver.onAnyCallThrow(parameterResolutionException));
 	}
 
 	private void thereIsAParameterResolverThatResolvesTheParameterTo(Object argument) {
-		register(ConfigurableMethodParameterResolver.supportsAndResolvesTo(parameter -> argument));
+		register(ConfigurableParameterResolver.supportsAndResolvesTo(parameter -> argument));
 	}
 
 	private void thereIsAParameterResolverThatDoesNotSupportThisParameter() {
-		register(ConfigurableMethodParameterResolver.withoutSupport());
+		register(ConfigurableParameterResolver.withoutSupport());
 	}
 
-	private void register(MethodParameterResolver extension) {
+	private void register(ParameterResolver extension) {
 		extensionRegistry.registerExtension(extension, this);
 	}
 
@@ -254,75 +254,73 @@ public Method getMethod() {
 
 	// -------------------------------------------------------------------------
 
-	static class ArgumentRecordingMethodParameterResolver implements MethodParameterResolver {
+	static class ArgumentRecordingParameterResolver implements ParameterResolver {
 
 		Arguments supportsArguments;
 		Arguments resolveArguments;
 
 		static class Arguments {
 
-			final MethodInvocationContext methodInvocationContext;
+			final Optional<Object> target;
 			final ExtensionContext extensionContext;
 
-			Arguments(MethodInvocationContext methodInvocationContext, ExtensionContext extensionContext) {
-				this.methodInvocationContext = methodInvocationContext;
+			Arguments(Optional<Object> target, ExtensionContext extensionContext) {
+				this.target = target;
 				this.extensionContext = extensionContext;
 			}
 		}
 
 		@Override
-		public boolean supports(Parameter parameter, MethodInvocationContext methodInvocationContext,
-				ExtensionContext extensionContext) throws ParameterResolutionException {
-			supportsArguments = new Arguments(methodInvocationContext, extensionContext);
+		public boolean supports(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext) {
+			supportsArguments = new Arguments(target, extensionContext);
 			return true;
 		}
 
 		@Override
-		public Object resolve(Parameter parameter, MethodInvocationContext methodInvocationContext,
-				ExtensionContext extensionContext) throws ParameterResolutionException {
-			resolveArguments = new Arguments(methodInvocationContext, extensionContext);
+		public Object resolve(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext) {
+			resolveArguments = new Arguments(target, extensionContext);
 			return null;
 		}
 	}
 
-	static class ConfigurableMethodParameterResolver implements MethodParameterResolver {
+	static class ConfigurableParameterResolver implements ParameterResolver {
 
-		static MethodParameterResolver onAnyCallThrow(RuntimeException runtimeException) {
-			return new ConfigurableMethodParameterResolver(parameter -> {
+		static ParameterResolver onAnyCallThrow(RuntimeException runtimeException) {
+			return new ConfigurableParameterResolver(parameter -> {
 				throw runtimeException;
 			}, parameter -> {
 				throw runtimeException;
 			});
 		}
 
-		static MethodParameterResolver supportsAndResolvesTo(Function<Parameter, Object> resolve) {
-			return new ConfigurableMethodParameterResolver(parameter -> true, resolve);
+		static ParameterResolver supportsAndResolvesTo(Function<Parameter, Object> resolve) {
+			return new ConfigurableParameterResolver(parameter -> true, resolve);
 		}
 
-		static MethodParameterResolver withoutSupport() {
-			return new ConfigurableMethodParameterResolver(parameter -> false, parameter -> {
+		static ParameterResolver withoutSupport() {
+			return new ConfigurableParameterResolver(parameter -> false, parameter -> {
 				throw new UnsupportedOperationException();
 			});
 		}
 
 		private final Function<Parameter, Boolean> supports;
 		private final Function<Parameter, Object> resolve;
 
-		private ConfigurableMethodParameterResolver(Function<Parameter, Boolean> supports,
+		private ConfigurableParameterResolver(Function<Parameter, Boolean> supports,
 				Function<Parameter, Object> resolve) {
 			this.supports = supports;
 			this.resolve = resolve;
 		}
 
 		@Override
-		public boolean supports(Parameter parameter, MethodInvocationContext methodInvocationContext,
-				ExtensionContext extensionContext) throws ParameterResolutionException {
+		public boolean supports(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext)
+				throws ParameterResolutionException {
 			return supports.apply(parameter);
 		}
 
 		@Override
-		public Object resolve(Parameter parameter, MethodInvocationContext methodInvocationContext,
-				ExtensionContext extensionContext) throws ParameterResolutionException {
+		public Object resolve(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext)
+				throws ParameterResolutionException {
 			return resolve.apply(parameter);
 		}
 	}

junit-tests/src/test/java/org/junit/gen5/engine/junit5/execution/injection/sample/CustomAnnotationParameterResolver.java

@@ -11,28 +11,24 @@
 package org.junit.gen5.engine.junit5.execution.injection.sample;
 
 import java.lang.reflect.Parameter;
+import java.util.Optional;
 
 import org.junit.gen5.api.extension.ExtensionContext;
-import org.junit.gen5.api.extension.MethodInvocationContext;
-import org.junit.gen5.api.extension.MethodParameterResolver;
+import org.junit.gen5.api.extension.ParameterResolver;
 import org.junit.gen5.commons.util.ReflectionUtils;
 
 /**
  * @since 5.0
  */
-public class CustomAnnotationParameterResolver implements MethodParameterResolver {
+public class CustomAnnotationParameterResolver implements ParameterResolver {
 
 	@Override
-	public boolean supports(Parameter parameter, MethodInvocationContext methodInvocationContext,
-			ExtensionContext extensionContext) {
-
+	public boolean supports(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext) {
 		return parameter.isAnnotationPresent(CustomAnnotation.class);
 	}
 
 	@Override
-	public Object resolve(Parameter parameter, MethodInvocationContext methodInvocationContext,
-			ExtensionContext extensionContext) {
-
+	public Object resolve(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext) {
 		return ReflectionUtils.newInstance(parameter.getType());
 	}
 

junit-tests/src/test/java/org/junit/gen5/engine/junit5/execution/injection/sample/CustomTypeParameterResolver.java

@@ -11,27 +11,23 @@
 package org.junit.gen5.engine.junit5.execution.injection.sample;
 
 import java.lang.reflect.Parameter;
+import java.util.Optional;
 
 import org.junit.gen5.api.extension.ExtensionContext;
-import org.junit.gen5.api.extension.MethodInvocationContext;
-import org.junit.gen5.api.extension.MethodParameterResolver;
+import org.junit.gen5.api.extension.ParameterResolver;
 
 /**
  * @since 5.0
  */
-public class CustomTypeParameterResolver implements MethodParameterResolver {
+public class CustomTypeParameterResolver implements ParameterResolver {
 
 	@Override
-	public boolean supports(Parameter parameter, MethodInvocationContext methodInvocationContext,
-			ExtensionContext extensionContext) {
-
+	public boolean supports(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext) {
 		return parameter.getType().equals(CustomType.class);
 	}
 
 	@Override
-	public Object resolve(Parameter parameter, MethodInvocationContext methodInvocationContext,
-			ExtensionContext extensionContext) {
-
+	public Object resolve(Parameter parameter, Optional<Object> target, ExtensionContext extensionContext) {
 		return new CustomType();
 	}