Temporal assertion support.

lib/unittest/mock.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * The error formatter for mocking is a bit different from the default one
  * for unit testing; instead of the third argument being a 'reason'
  * it is instead a [signature] describing the method signature filter
  * that was used to select the logs that were verified.
  */
@@ skipping 23 matching lines @@
 }
 
 _MockFailureHandler _mockFailureHandler = null;
 
 /**
  * [_noArg] is a sentinel value representing no argument.
  */
 final _noArg = const _Sentinel();
 
 /** The ways in which a call to a mock method can be handled. */
-class _Action {
+class Action {
   /** Do nothing (void method) */
-  static final IGNORE = const _Action._('IGNORE');
+  static final IGNORE = const Action._('IGNORE');
 
   /** Return a supplied value. */
-  static final RETURN = const _Action._('RETURN');
+  static final RETURN = const Action._('RETURN');
 
   /** Throw a supplied value. */
-  static final THROW = const _Action._('THROW');
+  static final THROW = const Action._('THROW');
 
   /** Call a supplied function. */
-  static final PROXY = const _Action._('PROXY');
+  static final PROXY = const Action._('PROXY');
 
-  const _Action._(this.name);
+  const Action._(this.name);
 
   final String name;
 }
 
 /**
  * The behavior of a method call in the mock library is specified
  * with [Responder]s. A [Responder] has a [value] to throw
  * or return (depending on whether [isThrow] is true or not, respectively),
  * and can either be one-shot, multi-shot, or infinitely repeating,
  * depending on the value of [count (1, greater than 1, or 0 respectively).
  */
 class Responder {
   var value;
-  _Action action;
+  Action action;
   int count;
-  Responder(this.value, [this.count = 1, this.action = _Action.RETURN]);
+  Responder(this.value, [this.count = 1, this.action = Action.RETURN]);
 }
 
 /**
  * A [CallMatcher] is a special matcher used to match method calls (i.e.
  * a method name and set of arguments). It is not a [Matcher] like the
  * unit test [Matcher], but instead represents a method name and a
  * collection of [Matcher]s, one per argument, that will be applied
  * to the parameters to decide if the method call is a match.
  */
 class CallMatcher {
@@ skipping 118 matching lines @@
 
   Behavior (this.matcher) {
     actions = new List<Responder>();
   }
 
   /**
    * Adds a [Responder] that returns a [value] for [count] calls
    * (1 by default).
    */
   Behavior thenReturn(value, [count = 1]) {
-    actions.add(new Responder(value, count, _Action.RETURN));
+    actions.add(new Responder(value, count, Action.RETURN));
     return this; // For chaining calls.
   }
 
   /** Adds a [Responder] that repeatedly returns a [value]. */
   Behavior alwaysReturn(value) {
     return thenReturn(value, 0);
   }
 
   /**
    * Adds a [Responder] that throws [value] [count]
    * times (1 by default).
    */
   Behavior thenThrow(value, [count = 1]) {
-    actions.add(new Responder(value, count, _Action.THROW));
+    actions.add(new Responder(value, count, Action.THROW));
     return this; // For chaining calls.
   }
 
   /** Adds a [Responder] that throws [value] endlessly. */
   Behavior alwaysThrow(value) {
     return thenThrow(value, 0);
   }
 
   /**
    * [thenCall] creates a proxy Responder, that is called [count]
    * times (1 by default; 0 is used for unlimited calls, and is
    * exposed as [alwaysCall]). [value] is the function that will
    * be called with the same arguments that were passed to the
    * mock. Proxies can be used to wrap real objects or to define
    * more complex return/throw behavior. You could even (if you
    * wanted) use proxies to emulate the behavior of thenReturn;
    * e.g.:
    *
    *     m.when(callsTo('foo')).thenReturn(0)
    *
    * is equivalent to:
    *
    *     m.when(callsTo('foo')).thenCall(() => 0)
    */
   Behavior thenCall(value, [count = 1]) {
-    actions.add(new Responder(value, count, _Action.PROXY));
+    actions.add(new Responder(value, count, Action.PROXY));
     return this; // For chaining calls.
   }
 
   /** Creates a repeating proxy call. */
   Behavior alwaysCall(value) {
     return thenCall(value, 0);
   }
 
   /** Returns true if a method call matches the [Behavior]. */
   bool matches(String method, List args) => matcher.matches(method, args);
@@ skipping 13 matching lines @@
   /** The mock object name, if any. */
   final String mockName;
 
   /** The method name. */
   final String methodName;
 
   /** The parameters. */
   final List args;
 
   /** The behavior that resulted. */
-  final _Action action;
+  final Action action;
 
   /** The value that was returned (if no throw). */
   final value;
 
   LogEntry(this.mockName, this.methodName,
       this.args, this.action, [this.value]) {
     time = new Date.now();
   }
 
   String _pad2(int val) => (val >= 10 ? '$val' : '0$val');
 
   String toString([Date baseTime]) {
     Description d = new StringDescription();
     if (baseTime == null) {
       // Show absolute time.
       d.add('${time.hour}:${_pad2(time.minute)}:'
           '${_pad2(time.second)}.${time.millisecond}>  ');
     } else {
       // Show relative time.
       int delta = time.millisecondsSinceEpoch - baseTime.millisecondsSinceEpoch;
       int secs = delta ~/ 1000;
       int msecs = delta % 1000;
       d.add('$secs.$msecs>  ');
     }
     d.add('${_qualifiedName(mockName, methodName)}(');
     for (var i = 0; i < args.length; i++) {
       if (i != 0) d.add(', ');
       d.addDescriptionOf(args[i]);
     }
-    d.add(') ${action == _Action.THROW ? "threw" : "returned"} ');
+    d.add(') ${action == Action.THROW ? "threw" : "returned"} ');
     d.addDescriptionOf(value);
     return d.toString();
   }
 }
 
 /** Utility function for optionally qualified method names */
 String _qualifiedName(owner, String method) {
   if (owner == null || owner === anything) {
     return method;
   } else if (owner is Matcher) {
     Description d = new StringDescription();
     d.addDescriptionOf(owner);
     d.add('.');
     d.add(method);
     return d.toString();
   } else {
     return '$owner.$method';
   }
 }
 
 /**
  * We do verification on a list of [LogEntry]s. To allow chaining
  * of calls to verify, we encapsulate such a list in the [LogEntryList]
  * class.
  */
 class LogEntryList {
-  final String filter;
+  String filter;
   List<LogEntry> logs;
   LogEntryList([this.filter]) {
     logs = new List<LogEntry>();
   }
 
   /** Add a [LogEntry] to the log. */
   add(LogEntry entry) => logs.add(entry);
 
+  /** Get the first entry, or null if no entries. */
+  get first() {

[Siggi Cherem (dart-lang), 2012/07/19 18:05:00]

we might fit this in a one liner :)
get first() => (logs == null || logs.length == 0) ? null : logs[0];

[gram, 2012/07/19 18:52:19]

Done.

+    if (logs == null || logs.length == 0) {
+      return null;
+    }
+    return logs[0];
+  }
+
+  /** Get the last entry, or null if no entries. */
+  get last() {

[Siggi Cherem (dart-lang), 2012/07/19 18:05:00]

ditto

[gram, 2012/07/19 18:52:19]

Done.

+    if (logs == null || logs.length == 0) {
+      return null;
+    }
+    return logs[logs.length-1];

[Siggi Cherem (dart-lang), 2012/07/19 18:05:00]

use logs.last() instead?

[gram, 2012/07/19 18:52:19]

Done.

+  }
+
+  /** Creates a LogEntry predicate function from the argument. */
+  Function _makePredicate(arg) {
+    if (arg == null) {
+      return (e) => true;
+    } else if (arg is CallMatcher) {
+      return (e) => arg.matches(e.methodName, e.args);
+    } else if (arg is Function) {
+      return arg;
+    } else {
+      throw new Exception("Invalid argument to _makePredicate.");
+    }
+  }
+
   /**
    * Create a new [LogEntryList] consisting of [LogEntry]s from
    * this list that match the specified [mockNameFilter] and [logFilter].
    * [mockNameFilter] can be null, a [String], a predicate [Function],
    * or a [Matcher]. If [mockNameFilter] is null, this is the same as
    * [anything].
    * If [logFilter] is null, all entries in the log will be returned.
+   * Otherwise [logFilter] should be a [CallMatcher] or  predicate function
+   * that takes a [LogEntry] and returns a bool.
    * If [destructive] is true, the log entries are removed from the
    * original list.
    */
   LogEntryList getMatches([mockNameFilter,
-                          CallMatcher logFilter,
+                          logFilter,
                           Matcher actionMatcher,
                           bool destructive = false]) {
     if (mockNameFilter == null) {
       mockNameFilter = anything;
     } else {
       mockNameFilter = wrapMatcher(mockNameFilter);
     }
-    if (logFilter == null) {
-      logFilter = new CallMatcher();
-    }
+    Function entryFilter = _makePredicate(logFilter);
     String filterName = _qualifiedName(mockNameFilter, logFilter.toString());
     LogEntryList rtn = new LogEntryList(filterName);
     for (var i = 0; i < logs.length; i++) {
       LogEntry entry = logs[i];
-      if (!mockNameFilter.matches(entry.mockName)) {
-        continue;
-      }
-      if (logFilter.matches(entry.methodName, entry.args)) {
+      if (mockNameFilter.matches(entry.mockName) && entryFilter(entry)) {
         if (actionMatcher == null || actionMatcher.matches(entry)) {
           rtn.add(entry);
           if (destructive) {
             logs.removeRange(i--, 1);
           }
         }
       }
     }
     return rtn;
   }
 
   /** Apply a unit test [Matcher] to the [LogEntryList]. */
   LogEntryList verify(Matcher matcher) {
     if (_mockFailureHandler == null) {
       _mockFailureHandler =
           new _MockFailureHandler(getOrCreateExpectFailureHandler());
     }
     expect(logs, matcher, filter, _mockFailureHandler);
     return this;
   }
 
+  /**
+   * Turn the logs into human-readable text. If [baseTime] is specified
+   * then each entry is prefixed with the offset from that time in
+   * milliseconds; otherwise the time of day is used.
+   */
   String toString([Date baseTime]) {
     String s = '';
     for (var e in logs) {
       s = '$s${e.toString(baseTime)}\n';
     }
     return s;
   }
+
+  /**
+   *  Find the first log entry that satisfies [logFilter] and
+   *  return its position. A search [start] position can be provided
+   *  to allow for repeated searches. [logFilter] can be a [CallMatcher],
+   *  or a predicate function that takes a [LogEntry] argument and returns
+   *  a bool. If [logFilter] is null, it will match any [LogEntry].
+   *  If no entry is found, then [failureReturnValue] is returned.
+   */
+  int findLogEntry(logFilter, [int start = 0, int failureReturnValue = -1]) {
+    logFilter = _makePredicate(logFilter);
+    int pos = start;
+    while (pos < logs.length) {
+      if (logFilter(logs[pos])) {
+        return pos;
+      }
+      ++pos;
+    }
+    return failureReturnValue;
+  }
+
+  /**
+   * Returns log events that happened up to the first one that
+   * satisfies [logFilter]. If [inPlace] is true, then returns
+   * this LogEntryList after removing the from the first satisfier;
+   * onwards otherwise a new list is created. [description]
+   * is used to create a new name for the resulting list.
+   * [defaultPosition] is used as the index of the matching item in
+   * the case that no match is found.
+   */
+  LogEntryList _head(logFilter, bool inPlace,
+                     String description, int defaultPosition) {
+    if (filter != null) {
+      description = '$filter $description';
+    }
+    int pos = findLogEntry(logFilter, 0, defaultPosition);
+    if (inPlace) {
+      if (pos < logs.length) {
+        logs.removeRange(pos, logs.length - pos);
+      }
+      filter = description;
+      return this;
+    } else {
+      LogEntryList newList = new LogEntryList(description);
+      for (var i = 0; i < pos; i++) {
+        newList.logs.add(logs[i]);
+      }
+      return newList;
+    }
+  }
+
+  /**
+   * Returns log events that happened from the first one that
+   * satisfies [logFilter]. If [inPlace] is true, then returns
+   * this LogEntryList after removing the entries up to the first
+   * satisfier; otherwise a new list is created. [description]
+   * is used to create a new name for the resulting list.
+   * [defaultPosition] is used as the index of the matching item in
+   * the case that no match is found.
+   */
+  LogEntryList _tail(logFilter, bool inPlace,
+                     String description, int defaultPosition) {
+    if (filter != null) {
+      description = '$filter $description';
+    }
+    int pos = findLogEntry(logFilter, 0, defaultPosition);
+    if (inPlace) {
+      if (pos > 0) {
+        logs.removeRange(0, pos);
+      }
+      filter = description;
+      return this;
+    } else {
+      LogEntryList newList = new LogEntryList(description);
+      while (pos < logs.length) {
+        newList.logs.add(logs[pos++]);
+      }
+      return newList;
+    }
+  }
+
+  /**
+   * Returns log events that happened after [when]. If [inPlace]
+   * is true, then it returns this LogEntryList after removing
+   * the entries that happened up to [when]; otherwise a new
+   * list is created.
+   */
+  LogEntryList after(Date when, [bool inPlace = false]) =>
+      _tail((e) => e.time > when, inPlace, 'after $when', logs.length);
+
+  /**
+   * Returns log events that happened from [when] onwards. If
+   * [inPlace] is true, then it returns this LogEntryList after
+   * removing the entries that happened before [when]; otherwise
+   * a new list is created.
+   */
+  LogEntryList from(Date when, [bool inPlace = false]) =>
+      _tail((e) => e.time >= when, inPlace, 'from $when', logs.length);
+
+  /**
+   * Returns log events that happened until [when]. If [inPlace]
+   * is true, then it returns this LogEntryList after removing
+   * the entries that happened after [when]; otherwise a new
+   * list is created.
+   */
+  LogEntryList until(Date when, [bool inPlace = false]) =>
+      _head((e) => e.time > when, inPlace, 'until $when', logs.length);
+
+  /**
+   * Returns log events that happened before [when]. If [inPlace]
+   * is true, then it returns this LogEntryList after removing
+   * the entries that happened from [when] onwards; otherwise a new
+   * list is created.
+   */
+  LogEntryList before(Date when, [bool inPlace = false]) =>
+      _head((e) => e.time >= when, inPlace, 'before $when', logs.length);
+
+  /**
+   * Returns log events that happened after [logEntry]'s time.
+   * If [inPlace] is true, then it returns this LogEntryList after
+   * removing the entries that happened up to [when]; otherwise a new
+   * list is created. If [logEntry] is null the current time is used.
+   */
+  LogEntryList afterEntry(LogEntry logEntry, [bool inPlace = false]) =>
+      after(logEntry == null ? new Date.now() : logEntry.time);
+
+  /**
+   * Returns log events that happened from [logEntry]'s time onwards.
+   * If [inPlace] is true, then it returns this LogEntryList after
+   * removing the entries that happened before [when]; otherwise
+   * a new list is created. If [logEntry] is null the current time is used.
+   */
+  LogEntryList fromEntry(LogEntry logEntry, [bool inPlace = false]) =>
+      from(logEntry == null ? new Date.now() : logEntry.time);
+
+  /**
+   * Returns log events that happened until [logEntry]'s time. If
+   * [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened after [when]; otherwise a new
+   * list is created. If [logEntry] is null the epoch time is used.
+   */
+  LogEntryList untilEntry(LogEntry logEntry, [bool inPlace = false]) =>
+      until(logEntry == null ?
+          new Date.fromMillisecondsSinceEpoch(0) : logEntry.time);
+
+  /**
+   * Returns log events that happened before [logEntry]'s time. If
+   * [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened from [when] onwards; otherwise a new
+   * list is created. If [logEntry] is null the epoch time is used.
+   */
+  LogEntryList beforeEntry(LogEntry logEntry, [bool inPlace = false]) =>
+      before(logEntry == null ?
+          new Date.fromMillisecondsSinceEpoch(0) : logEntry.time);
+
+  /**
+   * Returns log events that happened after the first event in [segment].
+   * If [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened earlier; otherwise a new list is created.
+   */
+  LogEntryList afterFirst(LogEntryList segment, [bool inPlace = false]) =>
+      afterEntry(segment.first, inPlace);
+
+  /**
+   * Returns log events that happened after the last event in [segment].
+   * If [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened earlier; otherwise a new list is created.
+   */
+  LogEntryList afterLast(LogEntryList segment, [bool inPlace = false]) =>
+      afterEntry(segment.last, inPlace);
+
+  /**
+   * Returns log events that happened from the time of the first event in
+   * [segment] onwards. If [inPlace] is true, then it returns this
+   * LogEntryList after removing the earlier entries; otherwise a new list
+   * is created.
+   */
+  LogEntryList fromFirst(LogEntryList segment, [bool inPlace = false]) =>
+      fromEntry(segment.first, inPlace);
+
+  /**
+   * Returns log events that happened from the time of the last event in
+   * [segment] onwards. If [inPlace] is true, then it returns this
+   * LogEntryList after removing the earlier entries; otherwise a new list
+   * is created.
+   */
+  LogEntryList fromLast(LogEntryList segment, [bool inPlace = false]) =>

[Siggi Cherem (dart-lang), 2012/07/19 18:05:00]

we should clarify on these comments the edge conditions. E.g. does this include
segment.last? Can we select the behaviour (e.g. a boolean argument to specify
whether to include it or not?)

[gram, 2012/07/19 18:52:19]

segment here need not have any elements in common with the logs being inspected;
we are using it just to get a timestamp. So it doesn't make sense to include
that element in the output as it may or may not exist.

The comment is unambiguous, I think:

Returns log events that happened from the TIME of the last event in [segment]
onwards.

These are just versions of before/after/until/from (which all take Dates) but we
are getting the date from a log which was most likely the result of some prior
filtering step.

A typical use case might be finding the calls to some error function in the logs
from one mock, and then finding the calls to some related method that preceded
these in a different mock (where each mock has its own log).

I do plan on expanding the mock article next week with some info on these with
use cases so that should make things more clear. 

[Siggi Cherem (dart-lang), 2012/07/19 20:02:25]

Thanks for the clarification, it makes a lot of sense

+      fromEntry(segment.last, inPlace);
+
+  /**
+   * Returns log events that happened until the first event in [segment].
+   * If [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened later; otherwise a new list is created.
+   */
+  LogEntryList untilFirst(LogEntryList segment, [bool inPlace = false]) =>
+      untilEntry(segment.first, inPlace);
+
+  /**
+   * Returns log events that happened until the last event in [segment].
+   * If [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened later; otherwise a new list is created.
+   */
+  LogEntryList untilLast(LogEntryList segment, [bool inPlace = false]) =>
+      untilEntry(segment.last, inPlace);
+
+  /**
+   * Returns log events that happened before the first event in [segment].
+   * If [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened later; otherwise a new list is created.
+   */
+  LogEntryList beforeFirst(LogEntryList segment, [bool inPlace = false]) =>
+      beforeEntry(segment.first, inPlace);
+
+  /**
+   * Returns log events that happened before the last event in [segment].
+   * If [inPlace] is true, then it returns this LogEntryList after removing
+   * the entries that happened later; otherwise a new list is created.
+   */
+  LogEntryList beforeLast(LogEntryList segment, [bool inPlace = false]) =>
+      beforeEntry(segment.last, inPlace);
+
+  /**
+   * Iterate through the LogEntryList looking for matches to the entries
+   * in [keys]; for each match found the closest [distance] neighboring log
+   * entries that match [mocknameFilter] and [logFilter] will be included in

[Siggi Cherem (dart-lang), 2012/07/19 18:05:00]

mockname -> mockName (capital N)

[gram, 2012/07/19 18:52:19]

Done.

+   * the result. If [isPreceding] is true we use the neighbors that precede
+   * the matched entry; else we use the neighbors that followed.
+   * If [includeKeys] is true then the entries in [keys] that resulted in
+   * entries in the output list are themselves included in the output list. If
+   * [distance] is zero then all matches are included.
+   */
+  LogEntryList _neighboring(bool isPreceding,
+                            LogEntryList keys,
+                            mockNameFilter,
+                            logFilter,
+                            int distance,
+                            bool includeKeys) {
+    LogEntryList rtn = new LogEntryList();
+
+    // Deal with the trivial case.
+    if (logs.length == 0 || keys.logs.length == 0) {
+      return rtn;
+    }
+
+    // Normalize the mockNameFilter and logFilter values.
+    if (mockNameFilter == null) {
+      mockNameFilter = anything;
+    } else {
+      mockNameFilter = wrapMatcher(mockNameFilter);
+    }
+    logFilter = _makePredicate(logFilter);
+
+    var keyIterator = keys.logs.iterator();
+    var logIterator = logs.iterator();
+    // The scratch list is used to hold matching entries when we
+    // are doing preceding neighbors. The remainingCount is used to
+    // keep track of how many matching entries we can still add in the
+    // current segment (0 if we are doing doing following neighbors, until
+    // we get our first key match).
+    List scratch = null;
+    int remainingCount = 0;
+    if (isPreceding) {
+      scratch = new List();
+      remainingCount = logs.length;
+    }
+
+    bool gotEntryMatches = false;
+    LogEntry keyEntry = keyIterator.next();
+
+    while (logIterator.hasNext()) {
+      LogEntry logEntry = logIterator.next();

[Siggi Cherem (dart-lang), 2012/07/19 18:05:00]

I don't see why you need to use the iterator explicitly for logs. Change to:
for (var logEntry in logs) {
 ...
?

[gram, 2012/07/19 18:52:19]

You're right - I iterated on a few versions of this code and it made sense in an
earlier version where I buffered both preceders and followers in scratch, but it
is unncessary now. Fixed.

+
+      // If we have a log entry match, copy the saved matches from the
+      // scratch buffer into the return list, as well as the matching entry,
+      // if appropriate, and reset the scratch buffer. Continue processing
+      // from the next key entry.
+      if (keyEntry == logEntry) {
+        if (scratch != null) {
+          int numToCopy = scratch.length;
+          if (distance > 0 && distance < numToCopy) {
+            numToCopy = distance;
+          }
+          for (var i = scratch.length - numToCopy; i < scratch.length; i++) {
+            rtn.logs.add(scratch[i]);
+          }
+          scratch.clear();
+        } else {
+          remainingCount = distance > 0 ? distance : logs.length;
+        }
+        if (includeKeys) {
+          rtn.logs.add(keyEntry);
+        }
+        if (keyIterator.hasNext()) {
+          keyEntry = keyIterator.next();
+        } else if (isPreceding) { // We're done.
+          break;
+        }
+      } else if (remainingCount > 0 &&
+                 mockNameFilter.matches(logEntry.mockName) &&
+                 logFilter(logEntry)) {
+        if (scratch != null) {
+          scratch.add(logEntry);
+        } else {
+          rtn.logs.add(logEntry);
+          --remainingCount;
+        }
+      }
+    }
+    return rtn;
+  }
+
+  /**
+   * Iterate through the LogEntryList looking for matches to the entries
+   * in [keys]; for each match found the closest [distance] prior log entries
+   * that match [mocknameFilter] and [logFilter] will be included in the result.
+   * If [includeKeys] is true then the entries in [keys] that resulted in
+   * entries in the output list are themselves included in the output list. If
+   * [distance] is zero then all matches are included.
+   */
+  LogEntryList preceding(LogEntryList keys,

[Siggi Cherem (dart-lang), 2012/07/19 18:05:00]

I find these methods quite strange. Maybe we need more examples to illustrate
what they are for?
Currently it seems that the output is a flattened list of values for each key? 

preceding([a, b], dispance: 3) ==> [a1,a2,a3,b1,b2,b3]

It might make more sense to me to have this for a single LogEntry, or to return
a list of lists, one per key.

[gram, 2012/07/19 18:52:19]

I respectfully disagree, other than providing more examples, which I will do.

+                         [mockNameFilter = null,
+                         logFilter = null,
+                         int distance = 1,
+                         bool includeKeys = false]) =>
+      _neighboring(true, keys, mockNameFilter, logFilter,
+          distance, includeKeys);
+
+  /**
+   * Iterate through the LogEntryList looking for matches to the entries
+   * in [keys]; for each match found the closest [distance] subsequent log
+   * entries that match [mocknameFilter] and [logFilter] will be included in
+   * the result. If [includeKeys] is true then the entries in [keys] that
+   * resulted in entries in the output list are themselves included in the
+   * output list. If [distance] is zero then all matches are included.
+   */
+  LogEntryList following(LogEntryList keys,
+                         [mockNameFilter = null,
+                         logFilter = null,
+                         int distance = 1,
+                         bool includeKeys = false]) =>
+      _neighboring(false, keys, mockNameFilter, logFilter,
+          distance, includeKeys);
 }
 
 /**
  * [_TimesMatcher]s are used to make assertions about the number of
  * times a method was called.
  */
 class _TimesMatcher extends BaseMatcher {
   final int min, max;
 
   const _TimesMatcher(this.min, [this.max = -1]);
@@ skipping 43 matching lines @@
 final Matcher happenedAtLeastOnce = const _TimesMatcher(1);
 
 /** [happenedAtMostOnce] matches zero or one call. */
 final Matcher happenedAtMostOnce = const _TimesMatcher(0, 1);
 
 /**
  * [_ResultMatcher]s are used to make assertions about the results
  * of method calls. These can be used as optional parameters to [getLogs].
  */
 class _ResultMatcher extends BaseMatcher {
-  final _Action action;
+  final Action action;
   final Matcher value;
 
   const _ResultMatcher(this.action, this.value);
 
   bool matches(item) {
     if (item is! LogEntry) {
      return false;
     }
     // normalize the action; _PROXY is like _RETURN.
-    _Action eaction = item.action;
-    if (eaction == _Action.PROXY) {
-      eaction = _Action.RETURN;
+    Action eaction = item.action;
+    if (eaction == Action.PROXY) {
+      eaction = Action.RETURN;
     }
     return (eaction == action && value.matches(item.value));
   }
 
   Description describe(Description description) {
     description.add(' to ');
-    if (action == _Action.RETURN || action == _Action.PROXY)
+    if (action == Action.RETURN || action == Action.PROXY)
       description.add('return ');
     else
       description.add('throw ');
     return description.addDescriptionOf(value);
   }
 
   Description describeMismatch(item, Description mismatchDescription) {
-    if (item.action == _Action.RETURN || item.action == _Action.PROXY) {
+    if (item.action == Action.RETURN || item.action == Action.PROXY) {
       mismatchDescription.add('returned ');
     } else {
       mismatchDescription.add('threw ');
     }
     mismatchDescription.add(item.value);
     return mismatchDescription;
   }
 }
 
 /**
  *[returning] matches log entries where the call to a method returned
  * a value that matched [value].
  */
 Matcher returning(value) =>
-    new _ResultMatcher(_Action.RETURN, wrapMatcher(value));
+    new _ResultMatcher(Action.RETURN, wrapMatcher(value));
 
 /**
  *[throwing] matches log entrues where the call to a method threw
  * a value that matched [value].
  */
 Matcher throwing(value) =>
-    new _ResultMatcher(_Action.THROW, wrapMatcher(value));
+    new _ResultMatcher(Action.THROW, wrapMatcher(value));
 
 /** Special values for use with [_ResultSetMatcher] [frequency]. */
 class _Frequency {
   /** Every call/throw must match */
   static final ALL = const _Frequency._('ALL');
 
   /** At least one call/throw must match. */
   static final SOME = const _Frequency._('SOME');
 
   /** No calls/throws should match. */
   static final NONE = const _Frequency._('NONE');
 
   const _Frequency._(this.name);
 
   final String name;
 }
 
 /**
  * [_ResultSetMatcher]s are used to make assertions about the results
  * of method calls. When filtering an execution log by calling
  * [getLogs], a [LogEntrySet] of matching call logs is returned;
  * [_ResultSetMatcher]s can then assert various things about this
  * (sub)set of logs.
  *
  * We could make this class use _ResultMatcher but it doesn't buy that
  * match and adds some perf hit, so there is some duplication here.
  */
 class _ResultSetMatcher extends BaseMatcher {
-  final _Action action;
+  final Action action;
   final Matcher value;
   final _Frequency frequency; // ALL, SOME, or NONE.
 
   const _ResultSetMatcher(this.action, this.value, this.frequency);
 
   bool matches(log) {
     for (LogEntry entry in log) {
-      // normalize the action; _PROXY is like _RETURN.
-      _Action eaction = entry.action;
-      if (eaction == _Action.PROXY) {
-        eaction = _Action.RETURN;
+      // normalize the action; PROXY is like RETURN.
+      Action eaction = entry.action;
+      if (eaction == Action.PROXY) {
+        eaction = Action.RETURN;
       }
       if (eaction == action && value.matches(entry.value)) {
         if (frequency == _Frequency.NONE) {
           return false;
         } else if (frequency == _Frequency.SOME) {
           return true;
         }
       } else {
         // Mismatch.
         if (frequency == _Frequency.ALL) { // We need just one mismatch to fail.
           return false;
         }
       }
     }
     // If we get here, then if count is _ALL we got all matches and
     // this is success; otherwise we got all mismatched which is
     // success for count == _NONE and failure for count == _SOME.
     return (frequency != _Frequency.SOME);
   }
 
   Description describe(Description description) {
     description.add(' to ');
     description.add(frequency == _Frequency.ALL ? 'alway ' :
         (frequency == _Frequency.NONE ? 'never ' : 'sometimes '));
-    if (action == _Action.RETURN || action == __Action.PROXY)
+    if (action == Action.RETURN || action == Action.PROXY)
       description.add('return ');
     else
       description.add('throw ');
     return description.addDescriptionOf(value);
   }
 
   Description describeMismatch(log, Description mismatchDescription) {
     if (frequency != _Frequency.SOME) {
       for (LogEntry entry in log) {
         if (entry.action != action || !value.matches(entry.value)) {
-          if (entry.action == _Action.RETURN || entry.action == _Action.PROXY)
+          if (entry.action == Action.RETURN || entry.action == Action.PROXY)
             mismatchDescription.add('returned ');
           else
             mismatchDescription.add('threw ');
           mismatchDescription.add(entry.value);
           mismatchDescription.add(' at least once');
           break;
         }
       }
     } else {
       mismatchDescription.add('never did');
     }
     return mismatchDescription;
   }
 }
 
 /**
  *[alwaysReturned] asserts that all matching calls to a method returned
  * a value that matched [value].
  */
 Matcher alwaysReturned(value) =>
-    new _ResultSetMatcher(_Action.RETURN, wrapMatcher(value), _Frequency.ALL);
+    new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.ALL);
 
 /**
  *[sometimeReturned] asserts that at least one matching call to a method
  * returned a value that matched [value].
  */
 Matcher sometimeReturned(value) =>
-    new _ResultSetMatcher(_Action.RETURN, wrapMatcher(value), _Frequency.SOME);
+    new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.SOME);
 
 /**
  *[neverReturned] asserts that no matching calls to a method returned
  * a value that matched [value].
  */
 Matcher neverReturned(value) =>
-    new _ResultSetMatcher(_Action.RETURN, wrapMatcher(value), _Frequency.NONE);
+    new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.NONE);
 
 /**
  *[alwaysThrew] asserts that all matching calls to a method threw
  * a value that matched [value].
  */
 Matcher alwaysThrew(value) =>
-    new _ResultSetMatcher(_Action.THROW, wrapMatcher(value), _Frequency.ALL);
+    new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.ALL);
 
 /**
  *[sometimeThrew] asserts that at least one matching call to a method threw
  * a value that matched [value].
  */
 Matcher sometimeThrew(value) =>
-  new _ResultSetMatcher(_Action.THROW, wrapMatcher(value), _Frequency.SOME);
+  new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.SOME);
 
 /**
  *[neverThrew] asserts that no matching call to a method threw
  * a value that matched [value].
  */
 Matcher neverThrew(value) =>
-  new _ResultSetMatcher(_Action.THROW, wrapMatcher(value), _Frequency.NONE);
+  new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.NONE);
 
 /** The shared log used for named mocks. */
 LogEntryList sharedLog = null;
 
 /**
  * [Mock] is the base class for all mocked objects, with
  * support for basic mocking.
  *
  * To create a mock objects for some class T, create a new class using:
  *
@@ skipping 78 matching lines @@
   /** The [log] of calls made. Only used if [name] is null. */
   LogEntryList log;
 
   /** How to handle unknown method calls - swallow or throw. */
   final bool _throwIfNoBehavior;
 
   /** Whether to create an audit log or not. */
   bool _logging;
 
   bool get logging() => _logging;
-  bool set logging(bool value) {
+  set logging(bool value) {
     if (value && log == null) {
       log = new LogEntryList();
     }
     _logging = value;
   }
 
   /**
    * Default constructor. Unknown method calls are allowed and logged,
    * the mock has no name, and has its own log.
    */
@@ skipping 66 matching lines @@
         // Get the first response.
         Responder response = actions[0];
         // If it is exhausted, remove it from the list.
         // Note that for endlessly repeating values, we started the count at
         // 0, so we get a potentially useful value here, which is the
         // (negation of) the number of times we returned the value.
         if (--response.count == 0) {
           actions.removeRange(0, 1);
         }
         // Do the response.
-        _Action action = response.action;
+        Action action = response.action;
         var value = response.value;
-        if (action == _Action.RETURN) {
+        if (action == Action.RETURN) {
           if (_logging) {
             log.add(new LogEntry(name, method, args, action, value));
           }
           return value;
-        } else if (action == _Action.THROW) {
+        } else if (action == Action.THROW) {
           if (_logging) {
             log.add(new LogEntry(name, method, args, action, value));
           }
           throw value;
-        } else if (action == _Action.PROXY) {
+        } else if (action == Action.PROXY) {
           var rtn;
           switch (args.length) {
             case 0:
               rtn = value();
               break;
             case 1:
               rtn = value(args[0]);
               break;
             case 2:
               rtn = value(args[0], args[1]);
@@ skipping 43 matching lines @@
       // actions are exhausted. This is considered an error.
       throw new Exception('No more actions for method '
           '${_qualifiedName(name, method)}.');
     } else if (_throwIfNoBehavior) {
       throw new Exception('No behavior specified for method '
           '${_qualifiedName(name, method)}.');
     }
     // Otherwise user hasn't specified behavior for this method; we don't throw
     // so we can underspecify.
     if (_logging) {
-      log.add(new LogEntry(name, method, args, _Action.IGNORE));
+      log.add(new LogEntry(name, method, args, Action.IGNORE));
     }
   }
 
   /** [verifyZeroInteractions] returns true if no calls were made */
   bool verifyZeroInteractions() {
     if (log == null) {
       // This means we created the mock with logging off and have never turned
       // it on, so it doesn't make sense to verify behavior on such a mock.
       throw new
           Exception("Can't verify behavior when logging was never enabled.");
     }
     return log.logs.length == 0;
   }
 
   /**
    * [getLogs] extracts all calls from the call log that match the
-   * [logFilter] [CallMatcher], and returns the matching list of
-   * [LogEntry]s. If [destructive] is false (the default) the matching
-   * calls are left in the log, else they are removed. Removal allows
-   * us to verify a set of interactions and then verify that there are
-   * no other interactions left. [actionMatcher] can be used to further
+   * [logFilter], and returns the matching list of [LogEntry]s. If
+   * [destructive] is false (the default) the matching calls are left
+   * in the log, else they are removed. Removal allows us to verify a
+   * set of interactions and then verify that there are no other
+   * interactions left. [actionMatcher] can be used to further
    * restrict the returned logs based on the action the mock performed.
+   * [logFilter] can be a [CallMatcher] or a predicate function that
+   * takes a [LogEntry] and returns a bool.
    *
    * Typical usage:
    *
    *     getLogs(callsTo(...)).verify(...);
    */
   LogEntryList getLogs([CallMatcher logFilter,
                         Matcher actionMatcher,
                         bool destructive = false]) {
     if (log == null) {
       // This means we created the mock with logging off and have never turned
       // it on, so it doesn't make sense to get logs from such a mock.
       throw new
           Exception("Can't retrieve logs when logging was never enabled.");
     } else {
       return log.getMatches(name, logFilter, actionMatcher, destructive);
     }
   }
+
+  /**
+   * Useful shorthand method that creates a [CallMatcher] from its arguments
+   * and then calls [getLogs].
+   */
+  LogEntryList calls(method,
+                      [arg0 = _noArg,
+                       arg1 = _noArg,
+                       arg2 = _noArg,
+                       arg3 = _noArg,
+                       arg4 = _noArg,
+                       arg5 = _noArg,
+                       arg6 = _noArg,
+                       arg7 = _noArg,
+                       arg8 = _noArg,
+                       arg9 = _noArg]) =>
+      getLogs(callsTo(method, arg0, arg1, arg2, arg3, arg4,
+          arg5, arg6, arg7, arg8, arg9));
 }