Update README to document the new TestClassWatcher2 interface

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`.