Merge branch 'master' into pr/add-watcher-finder

# Conflicts:
#	src/main/java/com/nordstrom/automation/junit/TestClassWatcher.java

Author: sbabcoc

README.md

@@ -109,7 +109,7 @@ The hooks that enable **JUnit Foundation** test lifecycle notifications are inst
     <dependency>
       <groupId>com.nordstrom.tools</groupId>
       <artifactId>junit-foundation</artifactId>
-      <version>6.2.0</version>
+      <version>9.0.4</version>
       <scope>test</scope>
     </dependency>
   </dependencies>
@@ -184,23 +184,21 @@ repositories {
     mavenCentral()
     ...
 }
-configurations {
+dependencies {
     ...
-    junitAgent
+    compile 'com.nordstrom.tools:junit-foundation:9.0.4'
+}
+ext {
+    junitFoundation = configurations.compile.resolvedConfiguration.resolvedArtifacts.find { it.name == 'junit-foundation' }
 }
 test.doFirst {
-    jvmArgs "-javaagent:${configurations.junitAgent.files.iterator().next()}"
+    jvmArgs "-javaagent:${junitFoundation.file}"
 }
 test {
 //  debug true
     // not required, but definitely useful
     testLogging.showStandardStreams = true
 }
-dependencies {
-    ...
-    compile 'com.nordstrom.tools:junit-foundation:6.2.0'
-    junitAgent 'com.nordstrom.tools:junit-foundation:6.2.0'
-}
 ```
 
 #### IDE Configuration for JUnit Foundation
@@ -234,12 +232,6 @@ The preceding **ServiceLoader** provider configuration files declare a **JUnit F
 **RunnerWatcher** provides callbacks for events in the lifecycle of **`ParentRunner`** objects. It receives the following notifications:
   * A **`ParentRunner`** object is about to run.
   * A **`ParentRunner`** object has finished running.
-* [TestClassWatcher](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/TestClassWatcher.java)  
-**TestClassWatcher** provides callbacks for events in the lifecycle of **`TestClass`** objects. It receives the following notifications:
-  * A **`TestClass`** object has been created to represent a JUnit test class or suite. Each **`TestClass`** has a one-to-one relationship with the JUnit runner that created it. (see **NOTE**)
-  * A **`TestClass`** object has been scheduled to run. This signals that the first child of the JUnit test class or suite is about start.
-  * A **`TestClass`** object has finished running. This signals that the last child of the JUnit test class or suite is done.
-  * **NOTE** - This interface supercedes a prior version, adding the runner object to start/finish notifications. Test executers like Maven Surefire create suite runners for their own purposes (e.g. - parallel execution context). This breaks the one-to-one relationship between **`TestClass`** objects and runners. Consequently, the **`TestClass`** object cannot be assumed to represent a unique context. 
 * [TestObjectWatcher](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/TestObjectWatcher.java)  
 **TestObjectWatcher** provides callbacks for events in the lifecycle of Java test class instances. It receives the following notification:
   * An instance of a JUnit test class has been created for the execution of a single `atomic test`.
@@ -309,7 +301,13 @@ Note that the implementation in this method watcher uses the annotations attache
 
 ### Support for Standard JUnit RunListener Providers
 
-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.
+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.
+
+**JUnit Foundation** uses this feature internally; notifications sent to **`RunWatcher`** service providers are published by an auto-attached **`RunListener`**. This notification-enhancing run listener, named [RunAnnouncer](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/RunAnnouncer.java), is registered via the aforementioned [**ServiceLoader** provider configuration file](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/resources/META-INF/services/org.junit.runner.notification.RunListener).
+
+### Support for Parallel Execution
+
+The ability to run **JUnit** tests in parallel is provided by the JUnit 4 test runner of the [Maven Surefire plugin](https://maven.apache.org/surefire/maven-surefire-plugin/examples/fork-options-and-parallel-execution.html). This feature utilizes private **JUnit** interfaces and undocuments behaviors, which greatly complicated the task of adding event notification hooks. As of version [9.0.3](https://github.com/Nordstrom/JUnit-Foundation/releases/tag/junit-foundation-9.0.3), **JUnit Foundation** supports parallel execution of both classes and methods.
 
 ### Support for Parameterized Tests
 

pom.xml

@@ -2,7 +2,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.nordstrom.tools</groupId>
   <artifactId>junit-foundation</artifactId>
-  <version>8.0.2-SNAPSHOT</version>
+  <version>9.0.5-SNAPSHOT</version>
   <packaging>jar</packaging>
 
   <name>JUnit Foundation</name>
@@ -29,14 +29,14 @@
     <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.3</java-utils.version>
+    <java-utils.version>1.8.0</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>
     <settings.version>2.2.2</settings.version>
     <junit.version>4.12</junit.version>
     <testng.version>6.10</testng.version>
-    <bytebuddy.version>1.9.3</bytebuddy.version>
+    <bytebuddy.version>1.9.5</bytebuddy.version>
     <logback.version>1.2.2</logback.version>
     <gpg-plugin.version>1.6</gpg-plugin.version>
     <staging-plugin.version>1.6.7</staging-plugin.version>
@@ -182,8 +182,6 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-plugin</artifactId>
         <configuration>
-          <parallel>classes</parallel>
-          <threadCount>5</threadCount>
           <argLine>-javaagent:src/test/resources/test-agent.jar</argLine>
         </configuration>
       </plugin>

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

@@ -1,16 +1,16 @@
 package com.nordstrom.automation.junit;
 
-import java.util.Collections;
-import java.util.HashMap;
 import java.util.Map;
 import java.util.Optional;
 
 import org.junit.runner.Description;
 
+import com.nordstrom.common.params.Params;
+
 /**
  * This interface enables implementers to provide method-related parameters to the artifact capture framework.
  */
-public interface ArtifactParams {
+public interface ArtifactParams extends Params {
 
     /**
      * Get the JUnit method description object for the current test class instance.
@@ -19,30 +19,14 @@ public interface ArtifactParams {
      */
     Description getDescription();
 
-    /**
-     * Get the parameters associated with this test class instance.
-     * 
-     * @return optional map of named test class parameters
-     */
-    default Optional<Map<String, Object>> getParameters() {
-        return Optional.empty();
-    }
-    
     /**
      * Assemble a map of test class instance parameters.
      * 
      * @param params array of {@link Param} objects; may be {@code null} or empty
      * @return optional map of parameters (may be empty)
      */
     public static Optional<Map<String, Object>> mapOf(Param... params) {
-        if ((params == null) || (params.length == 0)) {
-            return Optional.empty();
-        }
-        Map<String, Object> paramMap = new HashMap<>();
-        for (Param param : params) {
-            paramMap.put(param.key, param.val);
-        }
-        return Optional.of(Collections.unmodifiableMap(paramMap));
+        return Params.mapOf(params);
     }
 
     /**
@@ -53,30 +37,6 @@ public static Optional<Map<String, Object>> mapOf(Param... params) {
      * @return test parameter object
      */
     public static Param param(String key, Object val) {
-        return new Param(key, val);
+        return Params.param(key, val);
     }
-    
-    /**
-     * This class defines a test parameter object.
-     */
-    static class Param {
-        
-        private final String key;
-        private final Object val;
-        
-        /**
-         * Constructor for test parameter object.
-         * 
-         * @param key test parameter key
-         * @param val test parameter value
-         */
-        public Param(String key, Object val) {
-            if ((key == null) || key.isEmpty()) {
-                throw new IllegalArgumentException("[key] must be a non-empty string");
-            }
-            this.key = key;
-            this.val = val;
-        }
-    }
-
 }

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

@@ -0,0 +1,82 @@
+package com.nordstrom.automation.junit;
+
+import java.util.Map;
+import java.util.ServiceLoader;
+import java.util.concurrent.Callable;
+import java.util.concurrent.ConcurrentHashMap;
+
+import net.bytebuddy.implementation.bind.annotation.RuntimeType;
+import net.bytebuddy.implementation.bind.annotation.SuperCall;
+import net.bytebuddy.implementation.bind.annotation.This;
+
+/**
+ * This class declares the interceptor for the {@link org.junit.runners.BlockJUnit4ClassRunner#createTest
+ * createTest} method.
+ */
+@SuppressWarnings("squid:S1118")
+public class CreateTest {
+    
+    private static final ServiceLoader<TestObjectWatcher> objectWatcherLoader;
+    private static final Map<Object, Object> TARGET_TO_RUNNER = new ConcurrentHashMap<>();
+    private static final Map<Object, Object> RUNNER_TO_TARGET = new ConcurrentHashMap<>();
+    private static final ThreadLocal<DepthGauge> DEPTH = ThreadLocal.withInitial(DepthGauge::new);
+    
+    static {
+        objectWatcherLoader = ServiceLoader.load(TestObjectWatcher.class);
+    }
+    
+    /**
+     * Interceptor for the {@link org.junit.runners.BlockJUnit4ClassRunner#createTest createTest} method.
+     * 
+     * @param runner target {@link org.junit.runners.BlockJUnit4ClassRunner BlockJUnit4ClassRunner} object
+     * @param proxy callable proxy for the intercepted method
+     * @return {@code anything} - JUnit test class instance
+     * @throws Exception {@code anything} (exception thrown by the intercepted method)
+     */
+    @RuntimeType
+    public static Object intercept(@This final Object runner,
+                    @SuperCall final Callable<?> proxy) throws Exception {
+        
+        Object testObj;
+        try {
+            DEPTH.get().increaseDepth();
+            testObj = LifecycleHooks.callProxy(proxy);
+        } finally {
+            DEPTH.get().decreaseDepth();
+        }
+        
+        TARGET_TO_RUNNER.put(testObj, runner);
+        RUNNER_TO_TARGET.put(runner, testObj);
+        LifecycleHooks.applyTimeout(testObj);
+        
+        if (DEPTH.get().atGroundLevel()) {
+            synchronized(objectWatcherLoader) {
+                for (TestObjectWatcher watcher : objectWatcherLoader) {
+                    watcher.testObjectCreated(testObj, runner);
+                }
+            }
+        }
+        
+        return testObj;
+    }
+    
+    /**
+     * Get the class runner associated with the specified instance.
+     * 
+     * @param target instance of JUnit test class
+     * @return {@link org.junit.runners.BlockJUnit4ClassRunner BlockJUnit4ClassRunner} for specified instance
+     */
+    static Object getRunnerForTarget(Object target) {
+        return TARGET_TO_RUNNER.get(target);
+    }
+    
+    /**
+     * Get the JUnit test class instance for the specified class runner.
+     * 
+     * @param runner JUnit class runner
+     * @return JUnit test class instance for specified runner
+     */
+    static Object getTargetForRunner(Object runner) {
+        return RUNNER_TO_TARGET.get(runner);
+    }
+}