Merge pull request #25 from Nordstrom/pr/add-param-example

Refactor parameterized test support; add "DisplayName" annotation

Author: sbabcoc

README.md

@@ -325,6 +325,67 @@ Note that the implementation in this method watcher uses the annotations attache
 
 As indicated previously, **JUnit Foundation** will automatically attach standard JUnit **RunListener** providers that are declared in the associated **ServiceLoader** provider configuration file (i.e. - **_org.junit.runner.notification.RunListener_**). Declared run listeners are attached to the **RunNotifier** supplied to the `run()` method of JUnit runners. This feature eliminates behavioral differences between the various test execution environments like Maven, Gradle, and native IDE test runners.
 
+### Support for Parameterized Tests
+
+**JUnit** provides a custom [Parameterized](https://junit.org/junit4/javadoc/4.12/org/junit/runners/Parameterized.html) runner for executing parameterized tests. Third-party solutions are also available, such as [JUnitParams](https://github.com/Pragmatists/JUnitParams) and [ParameterizedSuite](https://github.com/PeterWippermann/parameterized-suite). Each of these solutions has its own implementation strategy, and no common interface is provided to access the parameters supplied to each invocation of the test methods in the parameterized class.
+
+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
+```java
+package com.nordstrom.example;
+
+import static org.junit.Assert.assertArrayEquals;
+
+import com.nordstrom.automation.junit.ArtifactParams;
+import com.nordstrom.automation.junit.AtomIdentity;
+
+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;
+
+@RunWith(Parameterized.class)
+public class ExampleTest implements ArtifactParams {
+    
+    private String input;
+    
+    public ExampleTest(String input) {
+        this.input = input;
+    }
+    
+    @Rule
+    public final AtomIdentity identity = new AtomIdentity(this);
+    
+    @Parameters
+    public static Object[] data() {
+        return new Object[] { "first test", "second test" };
+    }
+    
+    @Override
+    public Description getDescription() {
+        return identity.getDescription();
+    }
+    
+    @Override
+    public Object[] getParameters() {
+        return new Object[] { input };
+    }
+    
+    @Test
+    public void parameterized() {
+        System.out.println("invoking: " + getDescription().getMethodName());
+        assertArrayEquals(getParameters(), identity.getParameters());
+    }
+}
+```
+
+#### 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.
+
 ## Test Method Timeout Management
 
 **JUnit** provides test method timeout functionality via the `timeout` parameter of the **`@Test`** annotation. With this parameter, you can set an explicit timeout interval in milliseconds on an individual test method. If a test fails to complete within the specified interval, **JUnit** terminates the test and throws **TestTimedOutException**.
@@ -352,7 +413,6 @@ Failed attempts of tests that are selected for retry are tallied as ignored test
 
 * [ArtifactCollector](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/ArtifactCollector.java):  
 **ArtifactCollector** is a JUnit [test watcher](http://junit.org/junit4/javadoc/latest/org/junit/rules/TestWatcher.html) that serves as the foundation for artifact-capturing test watchers. This is a generic class, with the artifact-specific implementation provided by instances of the **ArtifactType** interface. For artifact capture scenarios where you need access to the current method description or the values provided to parameterized tests, the test class can implement the **ArtifactParams** interface.
-
 * [ArtifactParams](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/ArtifactParams.java):  
 By implementing the **ArtifactParams** interface in your test classes, you enable the artifact capture framework to access test method description objects and parameterized test values. These can be used for composing, naming, and storing artifacts. 
 * [ArtifactType](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/ArtifactType.java):  
@@ -385,8 +445,8 @@ public class MyArtifactType implements ArtifactType {
     @Override
     public byte[] getArtifact(Object instance, Throwable reason) {
         if (instance instanceof ArtifactParams) {
-            ArtifactParams params = (ArtifactParams) instance;
-            return String.format(ARTIFACT, params.getDescription().getMethodName()).getBytes().clone();
+            ArtifactParams publisher = (ArtifactParams) instance;
+            return String.format(ARTIFACT, publisher.getDescription().getMethodName()).getBytes().clone();
         } else {
             return new byte[0];
         }
@@ -422,17 +482,18 @@ public class MyArtifactCapture extends ArtifactCollector<MyArtifactType> {
     public MyArtifactCapture(Object instance) {
         super(instance, new MyArtifactType());
     }
-    
 }
 ```
 
 The preceding code is an example of how the artifact type definition can be assigned as the type parameter in a subclass of **ArtifactCollector**. This isn't strictly necessary, but will make your code more concise, as the next example demonstrates. This technique also provides the opportunity to extend or alter the basic artifact capture behavior.
 
 ###### Attaching artifact collectors to test classes
-
 ```java
 package com.nordstrom.example;
 
+import com.nordstrom.automation.junit.ArtifactCollector;
+import com.nordstrom.automation.junit.ArtifactParams;
+
 import org.junit.Rule;
 import org.junit.runner.Description;
 
@@ -448,9 +509,107 @@ public class ExampleTest implements ArtifactParams {
 
     @Override
     public Description getDescription() {
-        return watcher.getDescription();
+        return watcher1.getDescription();
     }
 }
 ```
 
-This example demonstrates two techniques for attaching artifact collectors to test classes. Either technique will activate basic artifact capture functionality. Of course, the first option is required to activate extended behavior implemented in a type-specific subclass of **ArtifactCapture**.
+This example demonstrates two techniques for attaching artifact collectors to test classes. Either technique will activate basic artifact capture functionality. Of course, the first option is required to activate extended behavior implemented in a type-specific subclass of **ArtifactCollector**.
+
+### Parameter-Aware Artifact Capture
+
+Although the **ExampleTest** class in the previous section implements the [ArtifactParams](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/ArtifactParams.java) interface, this non-parameterized example only shows half of the story. In addition to the **Description** objects of `atomic tests`, classes that implement parameterized tests are able to publish their invocation parameters, and the artifact capture feature is able to access them.
+
+The following example extends the previous artifact type to add parameter-awareness:
+
+###### Parameter-aware artifact type
+```java
+class MyParameterizedType extends MyArtifactType {
+
+    @Override
+    public byte[] getArtifact(Object instance, Throwable reason) {
+        if (instance instanceof ArtifactParams) {
+            ArtifactParams publisher = (ArtifactParams) instance;
+            StringBuilder artifact = new StringBuilder("method: ")
+                            .append(publisher.getDescription().getMethodName()).append("\n");
+            int i = 0;
+            for (Object param : publisher.getParameters()) {
+                "param" + i++ + ": [" + param + "]\n";
+            }
+            return artifact.toString().getBytes().clone();
+        } else {
+            return new byte[0];
+        }
+    }
+}
+```
+
+Notice the call to `getParameters()`, which retrieves the invocation parameters published by the test class instance. There's also a call to `getDescription()`, which returns the **Description** object for the current `atomic test`.
+
+The implementation below composes a type-specific subclass of **ArtifactCollector** to produce a parameter-aware artifact collector:
+
+###### Parameter-aware artifact collector
+```java
+package com.nordstrom.example;
+
+import com.nordstrom.automation.junit.ArtifactCollector;
+
+public class MyParameterizedCapture extends ArtifactCollector<MyParameterizedType> {
+    
+    public MyParameterizedCapture(Object instance) {
+        super(instance, new MyParameterizedType());
+    }
+}
+```
+
+The following example implements a parameterized test class that publishes its invocation parameters through the **ArtifactParams** interface. It uses the custom **Parameterized** runner to invoke the `parameterized()` test method twice - once with input "first test", and once with input "second test". The test class constructor accepts the invocation parameter as its argument and stores it in an instance field for use by the test.
+
+* The `getDescription()` method acquires the **Description** object for the current `atomic test` from the `watcher` test rule.
+* The `getParameters()` method assembles the array of invocation parameters from the `input` instance field populated by the constructor.
+
+###### Parameterized test class
+```java
+package com.nordstrom.example;
+
+import com.nordstrom.automation.junit.ArtifactParams;
+
+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;
+
+@RunWith(Parameterized.class)
+public class ParameterizedTest implements ArtifactParams {
+
+    @Rule
+    public final MyParameterizedCapture watcher = new MyParameterizedCapture(this);
+    
+    private String input;
+    
+    public ParameterizedTest(String input) {
+        this.input = input;
+    }
+    
+    @Parameters
+    public static Object[] data() {
+        return new Object[] { "first test", "second test" };
+    }
+    
+    @Override
+    public Description getDescription() {
+        return watcher.getDescription();
+    }
+    
+    @Override
+    public Object[] getParameters() {
+        return new Object[] { input };
+    }
+    
+    @Test
+    public void parameterized() {
+        assertArrayEquals(getParameters(), watcher.getParameters());
+    }
+}
+```

pom.xml

@@ -29,7 +29,7 @@
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
-    <java-utils.version>1.7.2</java-utils.version>
+    <java-utils.version>1.7.3</java-utils.version>
     <surefire-plugin.version>2.22.0</surefire-plugin.version>
     <source-plugin.version>3.0.1</source-plugin.version>
     <javadoc-plugin.version>2.10.4</javadoc-plugin.version>

src/main/java/com/nordstrom/automation/junit/ArtifactCollector.java

@@ -10,28 +10,24 @@
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 
-import org.junit.rules.TestWatcher;
 import org.junit.runner.Description;
-
 import com.nordstrom.common.file.PathUtils;
 
 /**
  * This is the base class for implementations of scenario-specific artifact collectors.
  * 
  * @param <T> scenario-specific artifact type
  */
-public class ArtifactCollector<T extends ArtifactType> extends TestWatcher {
+public class ArtifactCollector<T extends ArtifactType> extends AtomIdentity {
 
     private static final Map<Description, List<ArtifactCollector<? extends ArtifactType>>> watcherMap =
                     new ConcurrentHashMap<>();
 
     private final T provider;
-    private final Object instance;
-    private Description description;
     private final List<Path> artifactPaths = new ArrayList<>();
 
     public ArtifactCollector(Object instance, T provider) {
-        this.instance = instance;
+        super(instance);
         this.provider = provider;
     }
 
@@ -40,12 +36,9 @@ public ArtifactCollector(Object instance, T provider) {
      */
     @Override
     public void starting(Description description) {
-        this.description = description;
-        List<ArtifactCollector<? extends ArtifactType>> watcherList = watcherMap.get(description);
-        if (watcherList == null) {
-            watcherList = new ArrayList<>();
-            watcherMap.put(description, watcherList);
-        }
+        super.starting(description);
+        List<ArtifactCollector<? extends ArtifactType>> watcherList =
+                        watcherMap.computeIfAbsent(description, k -> new ArrayList<>());
         watcherList.add(this);
     }
 
@@ -64,11 +57,11 @@ public void failed(Throwable e, Description description) {
      * @return (optional) path at which the captured artifact was stored
      */
     public Optional<Path> captureArtifact(Throwable reason) {
-        if (! provider.canGetArtifact(instance)) {
+        if (! provider.canGetArtifact(getInstance())) {
             return Optional.empty();
         }
 
-        byte[] artifact = provider.getArtifact(instance, reason);
+        byte[] artifact = provider.getArtifact(getInstance(), reason);
         if ((artifact == null) || (artifact.length == 0)) {
             return Optional.empty();
         }
@@ -79,7 +72,7 @@ public Optional<Path> captureArtifact(Throwable reason) {
                 Files.createDirectories(collectionPath);
             } catch (IOException e) {
                 String messageTemplate = "Unable to create collection directory ({}); no artifact was captured";
-                provider.getLogger().warn(messageTemplate, collectionPath, e);
+                Optional.ofNullable(provider.getLogger()).ifPresent(l -> l.warn(messageTemplate, collectionPath, e));
                 return Optional.empty();
             }
         }
@@ -91,15 +84,18 @@ public Optional<Path> captureArtifact(Throwable reason) {
                             getArtifactBaseName(), 
                             provider.getArtifactExtension());
         } catch (IOException e) {
-            provider.getLogger().warn("Unable to get output path; no artifact was captured", e);
+            Optional.ofNullable(provider.getLogger()).ifPresent(
+                            l -> l.warn("Unable to get output path; no artifact was captured", e));
             return Optional.empty();
         }
 
         try {
-            provider.getLogger().info("Saving captured artifact to ({}).", artifactPath);
+            Optional.ofNullable(provider.getLogger()).ifPresent(
+                            l -> l.info("Saving captured artifact to ({}).", artifactPath));
             Files.write(artifactPath, artifact);
         } catch (IOException e) {
-            provider.getLogger().warn("I/O error saving to ({}); no artifact was captured", artifactPath, e);
+            Optional.ofNullable(provider.getLogger()).ifPresent(
+                            l -> l.warn("I/O error saving to ({}); no artifact was captured", artifactPath, e));
             return Optional.empty();
         }
 
@@ -113,8 +109,8 @@ public Optional<Path> captureArtifact(Throwable reason) {
      * @return path of artifact storage directory
      */
     private Path getCollectionPath() {
-        Path collectionPath = PathUtils.ReportsDirectory.getPathForObject(instance);
-        return collectionPath.resolve(provider.getArtifactPath(instance));
+        Path collectionPath = PathUtils.ReportsDirectory.getPathForObject(getInstance());
+        return collectionPath.resolve(provider.getArtifactPath(getInstance()));
     }
 
     /**
@@ -127,16 +123,12 @@ private Path getCollectionPath() {
      * @return artifact file base name
      */
     private String getArtifactBaseName() {
-        Object[] parameters = new Object[0];
-        if (instance instanceof ArtifactParams) {
-            parameters = ((ArtifactParams) instance).getParameters();
-        }
-        if (parameters.length == 0) {
-            return description.getMethodName();
+        if (getParameters().length == 0) {
+            return getDescription().getMethodName();
         } else {
-            int hashcode = Arrays.deepHashCode(parameters);
+            int hashcode = Arrays.deepHashCode(getParameters());
             String hashStr = String.format("%08X", hashcode);
-            return description.getMethodName() + "-" + hashStr;
+            return getDescription().getMethodName() + "-" + hashStr;
         }
     }
 
@@ -171,15 +163,6 @@ public T getArtifactProvider() {
         return provider;
     }
 
-    /**
-     * Get the JUnit {@link Description} object associated with this artifact collector.
-     * 
-     * @return JUnit method description object
-     */
-    public Description getDescription() {
-        return description;
-    }
-    
     /**
      * Get reference to an instance of the specified watcher type associated with the described method.
      * 

src/main/java/com/nordstrom/automation/junit/ArtifactParams.java

@@ -8,7 +8,7 @@
 public interface ArtifactParams {
 
     /**
-     * Get get JUnit method description object for the current test class instance.
+     * Get the JUnit method description object for the current test class instance.
      * 
      * @return JUnit method description object
      */