Update doc strings.

Author: Mike Davis

core-api/src/test/java/com/optimizely/ab/EventHandlerRule.java

@@ -25,24 +25,28 @@
 import java.util.*;
 import java.util.stream.Collectors;
 
+import static junit.framework.TestCase.assertTrue;
 import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.fail;
 
+/**
+ * EventHandlerRule is a JUnit rule that implements an Optimizely {@link EventHandler}.
+ *
+ * This implementation captures events being dispatched in a List.
+ *
+ * The List of "actual" events are compared, in order, against a list of "expected" events.
+ *
+ * Expected events are validated immediately against the head of actual events. If the queue is empty,
+ * then a failure is raised. This is to make it easy to map back to the failing test line number.
+ *
+ * A failure is raised if at the end of the test there remain non-validated actual events. This is by design
+ * to ensure that all outbound traffic is known and validated.
+ *
+ * TODO this rule does not yet support validation of event tags found in the {@link Event} payload.
+ */
 public class EventHandlerRule implements EventHandler, TestRule {
 
-    private List<CanonicalEvent> expectedEvents = new LinkedList<>();
-    private List<CanonicalEvent> actualEvents = new LinkedList<>();
-
-    public List<CanonicalEvent> getExpectedEvents() {
-        return expectedEvents;
-    }
-
-    public List<CanonicalEvent> getActualEvents() {
-        return actualEvents;
-    }
-
-    public boolean isEmpty() {
-        return actualEvents.isEmpty();
-    }
+    private LinkedList<CanonicalEvent> actualEvents;
 
     @Override
     public Statement apply(final Statement base, Description description) {
@@ -61,26 +65,14 @@ public void evaluate() throws Throwable {
     }
 
     private void before() {
-        expectedEvents = new LinkedList<>();
+        actualEvents = new LinkedList<>();
     }
 
     private void after() {
     }
 
     private void verify() {
-        assertEquals(expectedEvents.size(), actualEvents.size());
-
-        ListIterator<CanonicalEvent> expectedIterator = expectedEvents.listIterator();
-        ListIterator<CanonicalEvent> actualIterator = actualEvents.listIterator();
-
-        while (expectedIterator.hasNext()) {
-            CanonicalEvent expected = expectedIterator.next();
-            CanonicalEvent actual = actualIterator.next();
-
-            assertEquals(expected, actual);
-        }
-
-        // TODO make assertions when adding and verify that all actuals were exhausted.
+        assertTrue(actualEvents.isEmpty());
     }
 
     public void expectImpression(String experientId, String variationId, String userId) throws Exception {
@@ -89,7 +81,7 @@ public void expectImpression(String experientId, String variationId, String user
 
     public void expectImpression(String experientId, String variationId, String userId, Map<String, ?> attributes) throws Exception {
         CanonicalEvent expectedEvent = new CanonicalEvent(experientId, variationId, "campaign_activated", userId, attributes);
-        expectedEvents.add(expectedEvent);
+        verify(expectedEvent);
     }
 
     public void expectConversion(String eventName, String userId) throws Exception {
@@ -102,7 +94,16 @@ public void expectConversion(String eventName, String userId, Map<String, ?> att
 
     public void expectConversion(String experientId, String variationId, String eventName, String userId, Map<String, ?> attributes) throws Exception {
         CanonicalEvent expectedEvent = new CanonicalEvent(experientId, variationId, eventName, userId, attributes);
-        expectedEvents.add(expectedEvent);
+        verify(expectedEvent);
+    }
+
+    public void verify(CanonicalEvent expected) {
+        if (actualEvents.isEmpty()) {
+            fail(String.format("Expected: %s, but not events are queued", expected));
+        }
+
+        CanonicalEvent actual = actualEvents.removeFirst();
+        assertEquals(expected, actual);
     }
 
     @Override

core-api/src/test/java/com/optimizely/ab/OptimizelyTest.java

@@ -419,8 +419,6 @@ public void activateForNullVariation() throws Exception {
         Optimizely optimizely = optimizelyBuilder.withBucketing(mockBucketer).build();
         Variation actualVariation = optimizely.activate(activatedExperiment.getKey(), testUserId, testUserAttributes);
         assertNull(actualVariation);
-
-        assertTrue(eventHandler.isEmpty());
     }
 
     /**

core-api/src/test/java/com/optimizely/ab/internal/LogbackVerifier.java

@@ -32,6 +32,10 @@
 import static org.junit.Assert.fail;
 
 /**
+ * TODO As a usability improvement we should require expected messages be added after the message are expected to be
+ * logged. This will allow us to map the failure immediately back to the test line number as opposed to the async
+ * validation now that happens at the end of each individual test.
+ *
  * From http://techblog.kenshoo.com/2013/08/junit-rule-for-verifying-logback-logging.html
  */
 public class LogbackVerifier implements TestRule {