Add unit test and docs for JUnitParams support (#69)

Author: sbabcoc

README.md

@@ -200,7 +200,7 @@ The hooks that enable **JUnit Foundation** test lifecycle notifications are inst
 ```
 
 #### Gradle Configuration for JUnit Foundation
-```
+```groovy
 // build.gradle
 ...
 apply plugin: 'maven'
@@ -325,7 +325,6 @@ public class LoggingWatcher implements MethodWatcher<FrameworkMethod> {
         }
     }
 }
-
 ```
 
 Note that the implementation in this method watcher uses the annotations attached to the method objects to determine the type of method they're intercepting. Because each test method can have multiple configuration methods (both before and after), you may need to define additional conditions to control when your implementation runs. Examples of additional conditions include method name, method annotation, or an execution flag.
@@ -355,7 +354,11 @@ The ability to run **JUnit** tests in parallel is provided by the JUnit 4 test r
 
 For lifecycle notification subscribers that need access to test invocation parameters, **JUnit Foundation** defines the [ArtifactParams](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/ArtifactParams.java) interface. This interface, along with the [AtomIdentity](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/AtomIdentity.java) test rule, enables test classes to publish their invocation parameters.
 
-###### Publishing and Accessing Invocation Parameters
+The following example demonstrates how to publish invocation parameters with the [Parameterized](https://junit.org/junit4/javadoc/4.12/org/junit/runners/Parameterized.html) runner. The implementation is relatively simple, due to the strategy used by the runner to inject parameters into the test methods.
+
+The `Parameterized` runner relies on instance fields to inject parameter values, and requires the test implementer to provide a constructor that initializes these fields. Alternatively, the implementer can mark the instance fields with the `@Parameter` annotation.
+
+###### Publishing Invocation Parameters - `Parameterized` Runner
 ```java
 package com.nordstrom.example;
 
@@ -364,17 +367,15 @@ import static org.junit.Assert.assertTrue;
 import static com.nordstrom.automation.junit.ArtifactParams.param;
 
 import java.util.Map;
-import java.util.Optional;
-
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.runner.Description;
 import org.junit.runner.RunWith;
 import org.junit.runners.Parameterized;
 import org.junit.runners.Parameterized.Parameters;
-
 import com.nordstrom.automation.junit.ArtifactParams;
 import com.nordstrom.automation.junit.AtomIdentity;
+import com.google.common.base.Optional;
 
 @RunWith(Parameterized.class)
 public class ExampleTest implements ArtifactParams {
@@ -405,7 +406,7 @@ public class ExampleTest implements ArtifactParams {
 
     @Override
     public Optional<Map<String, Object>> getParameters() {
-        return ArtifactParams.mapOf(param("input", input));
+        return Param.mapOf(Param.param("input", input));
     }
 
     @Test
@@ -419,6 +420,89 @@ public class ExampleTest implements ArtifactParams {
 }
 ```
 
+The following example demonstrates how to publish invocation parameters with the [JUnitParams](https://github.com/Pragmatists/JUnitParams) runner. The implementation is more complex than the `Parameterized` example above, due to the strategy used by the runner to inject parameters into the test methods.
+
+The `JUnitParams` runner injects parameters via test method arguments, with values provided by a `val$params` field in the "callable" closures associated with each test method invocation. Unlike the `Parameterized` runner, where all test methods in the class run with the same set of values, the `JUnitParams` runner allows each test method in the class to run with its own unique set of values. This variability must be accounted for in the implementation of the `getParameters()` method.
+
+The example below queries the method for its parameter types, then uses these to cast each injected value to its corresponding type. This implementation assigns generic ordinal names to the parameters, because Java 7 reflection doesn't expose the names of method arguments. These could be acquired via the Java 8 API, or explicit mappings between test method signatures and argument names could be provided.
+
+###### Publishing Invocation Parameters - `JUnitParams` Runner
+```java
+package com.nordstrom.example;
+
+import static org.junit.Assert.assertEquals;
+
+import java.util.Map;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.internal.runners.model.ReflectiveCallable;
+import org.junit.runners.model.FrameworkMethod;
+import junitparams.JUnitParamsRunner;
+import junitparams.Parameters;
+import com.nordstrom.automation.junit.ArtifactParams;
+import com.nordstrom.automation.junit.AtomIdentity;
+import com.google.common.base.Optional;
+
+@RunWith(JUnitParamsRunner.class)
+public class ArtifactCollectorJUnitParams implements ArtifactParams {
+    
+    @Rule
+    public final AtomIdentity identity = new AtomIdentity(this);
+    
+    @Override
+    public AtomIdentity getAtomIdentity() {
+        return identity;
+    }
+    
+    @Override
+    public Description getDescription() {
+        return identity.getDescription();
+    }
+    
+    @Override
+    public Optional<Map<String, Object>> getParameters() {
+        // get runner for this target
+        Object runner = LifecycleHooks.getRunnerForTarget(this);
+        // get atomic test of target runner
+        AtomicTest<FrameworkMethod> test = LifecycleHooks.getAtomicTestOf(runner);
+        // get "callable" closure of test method
+        ReflectiveCallable callable = LifecycleHooks.getCallableOf(runner, test.getIdentity());
+        // get test method parameters
+        Class<?>[] paramTypes = test.getIdentity().getMethod().getParameterTypes();
+
+        try {
+            // extract execution parameters from "callable" closure
+            Object[] params = LifecycleHooks.getFieldValue(callable, "val$params");
+
+            // NOTE: The "callable" closure also includes:
+            // * this$0 - test case FrameworkMethod object
+            // * val$target - test class instance ('this')
+            // Only 'val$params' is unavailable elsewhere.
+
+            // allocate named parameters array
+            Param[] namedParams = new Param[params.length];
+            // populate named parameters array
+            for (int i = 0; i < params.length; i++) {
+                // create array item with generic name
+                namedParams[i] = Param.param("param" + i, paramTypes[i].cast(params[i]));
+            }
+
+            // return params map as Optional
+            return Param.mapOf(namedParams);
+        } catch (IllegalAccessException | NoSuchFieldException e) {
+            return Optional.absent();
+        }
+    }
+    
+    @Test
+    @Parameters({ "first test", "second test" })
+    public void parameterized(String input) {
+        System.out.println("parameterized: input = [" + input + "]");
+        assertEquals("first test", input);
+    }
+}
+```
+
 #### Artifact capture for parameterized tests
 
 For scenarios that require artifact capture of parameterized tests, the [ArtifactCollector](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/ArtifactCollector.java) class extends the [AtomIdentity](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/AtomIdentity.java) test rule. This enables artifact type implementations to access invocation parameters and **Description** object for the current `atomic test`. For more details, see the [Artifact Capture](#artifact-capture) section below.

pom.xml

@@ -36,6 +36,7 @@
     <bytebuddy.version>1.10.3</bytebuddy.version>
     <logback.version>1.2.3</logback.version>
     <guava.version>28.1-android</guava.version>
+    <junitparams.version>1.1.1</junitparams.version>
     <toolchains-plugin.version>1.1</toolchains-plugin.version>
     <surefire-plugin.version>2.22.0</surefire-plugin.version>
     <source-plugin.version>3.2.0</source-plugin.version>
@@ -107,6 +108,11 @@
         <artifactId>guava</artifactId>
         <version>${guava.version}</version>
       </dependency>
+      <dependency>
+        <groupId>pl.pragmatists</groupId>
+        <artifactId>JUnitParams</artifactId>
+        <version>${junitparams.version}</version>
+      </dependency>
     </dependencies>
   </dependencyManagement>
 
@@ -145,6 +151,11 @@
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
     </dependency>
+    <dependency>
+      <groupId>pl.pragmatists</groupId>
+      <artifactId>JUnitParams</artifactId>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 
   <build>

src/test/java/com/nordstrom/automation/junit/ArtifactCollectorJUnitParams.java

@@ -0,0 +1,61 @@
+package com.nordstrom.automation.junit;
+
+import static org.junit.Assert.assertEquals;
+
+import java.util.Map;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.internal.runners.model.ReflectiveCallable;
+import org.junit.runners.model.FrameworkMethod;
+
+import junitparams.JUnitParamsRunner;
+import junitparams.Parameters;
+
+import com.google.common.base.Optional;
+
+@RunWith(JUnitParamsRunner.class)
+public class ArtifactCollectorJUnitParams extends TestBase {
+
+    @Override
+    public Optional<Map<String, Object>> getParameters() {
+        // get runner for this target
+        Object runner = LifecycleHooks.getRunnerForTarget(this);
+        // get atomic test of target runner
+        AtomicTest<FrameworkMethod> test = LifecycleHooks.getAtomicTestOf(runner);
+        // get "callable" closure of test method
+        ReflectiveCallable callable = LifecycleHooks.getCallableOf(runner, test.getIdentity());
+        // get test method parameters
+        Class<?>[] paramTypes = test.getIdentity().getMethod().getParameterTypes();
+
+        try {
+            // extract execution parameters from "callable" closure
+            Object[] params = LifecycleHooks.getFieldValue(callable, "val$params");
+
+            // NOTE: The "callable" closure also includes:
+            // * this$0 - test case FrameworkMethod object
+            // * val$target - test class instance ('this')
+            // Only 'val$params' is unavailable elsewhere.
+
+            // allocate named parameters array
+            Param[] namedParams = new Param[params.length];
+            // populate named parameters array
+            for (int i = 0; i < params.length; i++) {
+                // create array item with generic name
+                namedParams[i] = Param.param("param" + i, paramTypes[i].cast(params[i]));
+            }
+
+            // return params map as Optional
+            return Param.mapOf(namedParams);
+        } catch (IllegalAccessException | NoSuchFieldException e) {
+            return Optional.absent();
+        }
+    }
+    
+    @Test
+    @Parameters({ "first test", "second test" })
+    public void parameterized(String input) {
+        System.out.println("parameterized: input = [" + input + "]");
+        assertEquals("first test", input);
+    }
+}

src/test/java/com/nordstrom/automation/junit/ArtifactCollectorTest.java

@@ -127,4 +127,23 @@ public void verifyParameterizedCapture() {
         assertNull(watcher.getArtifactProvider().getCaptureState(), "Artifact provider capture state should be 'null'");
         assertNull(watcher.getArtifactPath(), "Artifact capture should not have been requested");
     }
+
+    @Test
+    public void verifyJUnitParamsCapture() {
+        RunListenerAdapter rla = new RunListenerAdapter();
+
+        JUnitCore runner = new JUnitCore();
+        runner.addListener(rla);
+        Result result = runner.run(ArtifactCollectorJUnitParams.class);
+        assertFalse(result.wasSuccessful());
+
+        assertEquals(rla.getPassedTests().size(), 1, "Incorrect passed test count");
+        assertEquals(rla.getFailedTests().size(), 1, "Incorrect failed test count");
+        assertEquals(rla.getIgnoredTests().size(), 0, "Incorrect ignored test count");
+
+        Description description = rla.getPassedTests().get(0);
+        UnitTestCapture watcher = ArtifactCollector.getWatcher(description, UnitTestCapture.class).get();
+        assertNull(watcher.getArtifactProvider().getCaptureState(), "Artifact provider capture state should be 'null'");
+        assertNull(watcher.getArtifactPath(), "Artifact capture should not have been requested");
+    }
 }