Merge pull request #21 from Nordstrom/pr/use-runner-as-context

Pr/use runner as context

Author: sbabcoc

README.md

@@ -43,22 +43,28 @@ import com.nordstrom.automation.junit.AtomicTest;
 import com.nordstrom.automation.junit.LifecycleHooks;
 import com.nordstrom.automation.junit.MethodWatcher;
 import com.nordstrom.automation.junit.RunReflectiveCall;
-import com.nordstrom.automation.junit.TestClassWatcher;
+import com.nordstrom.automation.junit.TestClassWatcher2;
 import org.junit.runners.model.FrameworkMethod;
 import org.junit.runners.model.TestClass;
 
-public class ExploringWatcher implements TestClassWatcher, MethodWatcher {
+public class ExploringWatcher implements TestClassWatcher2, MethodWatcher {
 
     ...
 
     @Override
-    public void testClassStarted(TestClass testClass) {
-        // get the 'atomic test' for this runner
-        AtomicTest atomicTest = RunReflectiveCall.getAtomicTestFor(testClass);
-        // get the 'particle' methods of this 'atomic test'
-        List<FrameworkMethod> particles = atomicTest.getParticles();
-        // get the parent of this runner
-        TestClass parent = LifecycleHooks.getParentOf(testClass);
+    public void testClassStarted(TestClass testClass, Object runner) {
+        // if this is a Suite runner
+        if (runner instanceof org.junit.runners.Suite) {
+            // get the parent of this runner
+            Object parent = LifecycleHooks.getParentOf(runner);
+            ...
+        } else {
+            // get the 'atomic test' for this runner
+            AtomicTest atomicTest = RunReflectiveCall.getAtomicTestFor(testClass);
+            // get the 'particle' methods of this 'atomic test'
+            List<FrameworkMethod> particles = atomicTest.getParticles();
+            ...
+        }
         ...
     }
 
@@ -242,11 +248,12 @@ 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.
+* [TestClassWatcher2](https://github.com/Nordstrom/JUnit-Foundation/blob/master/src/main/java/com/nordstrom/automation/junit/TestClassWatcher2.java)  
+**TestClassWatcher2** 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`.

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

@@ -24,12 +24,14 @@
 @SuppressWarnings("squid:S1118")
 public class CreateTestClass {
     private static final ServiceLoader<TestClassWatcher> classWatcherLoader;
+    private static final ServiceLoader<TestClassWatcher2> classWatcher2Loader;
     private static final Logger LOGGER = LoggerFactory.getLogger(CreateTestClass.class);
     private static final Map<TestClass, Object> TESTCLASS_TO_RUNNER = new ConcurrentHashMap<>();
     private static final Map<Object, TestClass> METHOD_TO_TESTCLASS = new ConcurrentHashMap<>();
 
     static {
         classWatcherLoader = ServiceLoader.load(TestClassWatcher.class);
+        classWatcher2Loader = ServiceLoader.load(TestClassWatcher2.class);
     }
 
     /**
@@ -53,6 +55,9 @@ public static TestClass intercept(@This final Object runner, @SuperCall final Ca
         for (TestClassWatcher watcher : classWatcherLoader) {
             watcher.testClassCreated(testClass, runner);
         }
+        for (TestClassWatcher2 watcher : classWatcher2Loader) {
+            watcher.testClassCreated(testClass, runner);
+        }
 
         attachRunnerScheduler(testClass, runner);
         return testClass;
@@ -67,7 +72,7 @@ public static TestClass intercept(@This final Object runner, @SuperCall final Ca
     private static void attachRunnerScheduler(final TestClass testClass, final Object runner) {
         try {
             RunnerScheduler scheduler = getFieldValue(runner, "scheduler");
-            setFieldValue(runner, "scheduler", createRunnerScheduler(testClass, scheduler));
+            setFieldValue(runner, "scheduler", createRunnerScheduler(testClass, runner, scheduler));
         } catch (IllegalAccessException | NoSuchFieldException | SecurityException | IllegalArgumentException e) {
             LOGGER.warn("Unable to attach notifying runner scheduler", e);
         }
@@ -77,10 +82,12 @@ private static void attachRunnerScheduler(final TestClass testClass, final Objec
      * Create notifying runner scheduler, which forwards to the previous scheduler if specified.
      * 
      * @param testClass {@link TestClass} object that was just created
+     * @param runner {@link ParentRunner} for the specified test class
      * @param scheduler runner scheduler that's currently attached to the specified runner (may be {@code null})
      * @return new notifying runner scheduler
      */
-    private static RunnerScheduler createRunnerScheduler(final TestClass testClass, final RunnerScheduler scheduler) {
+    private static RunnerScheduler createRunnerScheduler(final TestClass testClass,
+                    final Object runner, final RunnerScheduler scheduler) {
         return new RunnerScheduler() {
             private AtomicBoolean scheduled = new AtomicBoolean(false);
 
@@ -89,6 +96,9 @@ public void schedule(Runnable childStatement) {
                     for (TestClassWatcher watcher : classWatcherLoader) {
                         watcher.testClassStarted(testClass);
                     }
+                    for (TestClassWatcher2 watcher : classWatcher2Loader) {
+                        watcher.testClassStarted(testClass, runner);
+                    }
                 }
 
                 RunReflectiveCall.fireTestStarted(testClass, childStatement);
@@ -106,6 +116,9 @@ public void finished() {
                 for (TestClassWatcher watcher : classWatcherLoader) {
                     watcher.testClassFinished(testClass);
                 }
+                for (TestClassWatcher2 watcher : classWatcher2Loader) {
+                    watcher.testClassFinished(testClass, runner);
+                }
             }
         };
     }

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

@@ -20,13 +20,15 @@ public interface TestClassWatcher {
      * Called when a runner (test class or suite) is about to be started.
      * 
      * @param testClass {@link TestClass} object for the parent runner
+     * @deprecated Use {@link TestClassWatcher2#testClassStarted(TestClass, Object)} instead
      */
     void testClassStarted(TestClass testClass);
 
     /**
      * Called when a runner (test class or suite) has finished.
      * 
      * @param testClass {@link TestClass} object for the parent runner
+     * @deprecated Use {@link TestClassWatcher2#testClassFinished(TestClass, Object)} instead
      */
     void testClassFinished(TestClass testClass);
 }

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

@@ -0,0 +1,26 @@
+package com.nordstrom.automation.junit;
+
+import org.junit.runners.model.TestClass;
+
+/**
+ * This interface defines the methods implemented by JUnit TestClass watchers. These watchers are registered via a
+ * ServiceLoader provider configuration file.
+ */
+public interface TestClassWatcher2 extends TestClassWatcher {
+    
+    /**
+     * Called when a runner (test class or suite) is about to be started.
+     * 
+     * @param testClass {@link TestClass} object for the parent runner
+     * @param runner JUnit test runner
+     */
+    void testClassStarted(TestClass testClass, Object runner);
+    
+    /**
+     * Called when a runner (test class or suite) has finished.
+     * 
+     * @param testClass {@link TestClass} object for the parent runner
+     * @param runner JUnit test runner
+     */
+    void testClassFinished(TestClass testClass, Object runner);
+}