Changed the syntax some. All the handling of variable argument lists is

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 22 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. */
+final RETURN = 0;
+final THROW = 1;
+final PROXY = 2;
+
 /**
  * The behavior of a method call in the mock library is specified
  * with [BehaviorValue]s. A [BehaviorValue] 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 BehaviorValue {
   var value;
-  bool isThrow;
+  int action;
   int count;
-  BehaviorValue(this.value, [this.count = 1, this.isThrow = false]);
+  BehaviorValue(this.value, [this.count = 1, this.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 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 50 matching lines @@
     }
     d.add(')');
     return d.toString();
   }
 
   /**
    * Given a [method] name oand list of [arguments], return true
    * if it matches this [CallMatcher.
    */
   bool matches(String method, List arguments) {
-    if (method != this.name || arguments.length != argMatchers.length) {
+    if (method != this.name) {
       return false;
     }
-    for (var i = 0; i < arguments.length; i++) {
+    if (arguments.length < argMatchers.length) {
+      throw new Exception("Less arguments than matchers for $name");
+    }
+    for (var i = 0; i < argMatchers.length; i++) {
       if (!argMatchers[i].matches(arguments[i])) {
         return false;
       }
     }
     return true;
   }
 }
 
+/** [callstTo] returns a CallMatcher for the specified signature. */
+CallMatcher callsTo(String method, [ arg0 = _noArg,
+                        arg1 = _noArg,
+                        arg2 = _noArg,
+                        arg3 = _noArg,
+                        arg4 = _noArg,
+                        arg5 = _noArg,
+                        arg6 = _noArg,
+                        arg7 = _noArg,
+                        arg8 = _noArg,
+                        arg9 = _noArg]) {
+  return new CallMatcher(method, arg0, arg1, arg2, arg3, arg4,
+      arg5, arg6, arg7, arg8, arg9);
+}
+
 /**
  * A [Behavior] represents how a [Mock] will respond to one particular
  * type of method call.
  */
 class Behavior {
   CallMatcher matcher; // The method call matcher.
-  List<BehaviorValue> returnValues; // The values to return/throw.
+  List<BehaviorValue> actions; // The values to return/throw or proxies to call.
 
   Behavior (this.matcher) {
-    returnValues = new List<BehaviorValue>();
+    actions = new List<BehaviorValue>();
   }
 
   /**
    * [thenReturn] creates a return value, that is returned [count]
    * times (1 by default).
    */
   Behavior thenReturn(value, [count = 1]) {
-    returnValues.add(new BehaviorValue(value, count));
+    actions.add(new BehaviorValue(value, count, RETURN));
     return this; // For chaining calls.
   }
 
   /** [alwaysReturn] creates a repeating return value. */
   Behavior alwaysReturn(value) {
     return thenReturn(value, 0);
   }
 
   /**
    * [thenThrow] creates an exception, that is thrown [count]
    * times (1 by default).
    */
   Behavior thenThrow(value, [count = 1]) {
-    returnValues.add(new BehaviorValue(value, count, true));
+    actions.add(new BehaviorValue(value, count, THROW));
     return this; // For chaining calls.
   }
 
   /** [alwaysThrow] creates a repeating exception. */
   Behavior alwaysThrow(value) {
     return thenThrow(value, 0);
   }
 
+  /**
+   * [thenCall] creates a proxy, that is called [count]
+   * times (1 by default).
+   */
+  Behavior thenCall(value, [count = 1]) {

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

what is [value]. Looking a the code in the test, seems like this is a closure
that takes the same arguments as the call matcher?

[gram, 2012/06/28 17:32:54]

Added a comment.

+    actions.add(new BehaviorValue(value, count, PROXY));
+    return this; // For chaining calls.
+  }
+
+  /** [alwaysCall] creates a repeating proxy call. */
+  Behavior alwaysCall(value) {
+    return thenCall(value, 0);
+  }
+
   /** [matches] return true if a method call matches the [Behavior]. */
   bool matches(name, args) => matcher.matches(name, args);
 }
 
 /**
  * Every call to a [Mock] object method is logged. The logs are
  * kept in instances of [LogEntry].
  */
 class LogEntry {
   final String name; // The method name.
   final List args; // The parameters.
-  final BehaviorValue result; // The behavior that resulted.
+  final int action; // The behavior that resulted.
+  final value; // The value that was returned (if no throw).
 
-  const LogEntry(this.name, this.args, this.result);
+  const LogEntry(this.name, this.args, this.action, [this.value = null]);
 }
 
 /**
  * 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;
   final List<LogEntry> logs;
   const LogEntryList(this.logs, [this.filter = null]);
 
   /** Add a [LogEntry] to the log. */
   add(LogEntry entry) => logs.add(entry);
 
   /**
    * Create a new [LogEntryList] consisting of [LogEntry]s from
-   * this list that match the specified [logfilter].
+   * this list that match the specified [logfilter]. If [destructive]
+   * is true, the log entries are removed from the original list.
    */
-  LogEntryList getMatches(CallMatcher logfilter) {
+  LogEntryList getMatches(CallMatcher logfilter, bool destructive) {
     LogEntryList rtn =
         new LogEntryList(new List<LogEntry>(), logfilter.toString());
     for (var i = 0; i < logs.length; i++) {
       LogEntry entry = logs[i];
       if (logfilter.matches(entry.name, entry.args)) {
         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());
@@ skipping 49 matching lines @@
 /** [calledOnce] matches exactly one call. */
 final Matcher calledOnce = const _TimesMatcher(1, 1);
 
 /** [calledAtLeastOnce] matches one or more calls. */
 final Matcher calledAtLeastOnce = const _TimesMatcher(1);
 
 /** [calledAtMostOnce] matches zero or one call. */
 final Matcher calledAtMostOnce = const _TimesMatcher(0, 1);
 
 /**
+ * [_ResultMatcher]s are used to make assertions about the results
+ * of method calls.

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

=> of a sequence of method calls? (since this is applied on a log?)

[gram, 2012/06/28 17:32:54]

I don't like 'sequence', even if the logs are temporally ordered, because we are
filtering to a subset that may not be related temporally. I have adjusted the
comment to make things clearer I hope.

+ */
+class _ResultMatcher extends BaseMatcher {
+  final int action;
+  final value;
+  final int count; // -1 for all, 0 for none, 1 for some.

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

please change to something more self explanatory (e.g. enums or booleans).

I think using booleans like:
final bool matchAlways;
final bool matchSome;
final bool matchNone;

will make the code in matches easier to understand:
...
if (eaction == action && value.matches(entry.value)) {
  if (matchSome) return true;
  if (matchNone) return false;
} else {
  // Mismatch.
  if (matchAlways) return false;
}
return matchAlways || matchNone;

[gram, 2012/06/28 17:32:54]

I used a single value as an enum; it scales better than boolean flags (e.g. you
could add something like "not all" easily).

+
+  const _ResultMatcher(this.action, this.value, this.count);
+
+  bool matches(log) {
+    for (LogEntry entry in log) {
+      // normalize the action; PROXY is like RETURN.
+      int eaction = (entry.action == THROW) ? THROW : RETURN;
+      if (eaction == action && value.matches(entry.value)) {
+        if (count == 0) {
+          return false;
+        } else if (count == 1) {
+          return true;
+        }
+      } else {
+        // Mismatch.
+        if (count == -1) { // We need just one mismatch to fail.
+          return false;
+        }
+      }
+    }
+    // If we get here, then if count is -1 we got all matches and
+    // this is success; otherwise we got all mismatched which is
+    // success for count == 0 and failure for count == 1.
+    return (count != 1);
+  }

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

+ line separation between methods (here and below )

[gram, 2012/06/28 17:32:54]

Done.

+  Description describe(Description description) {
+    description.add(' to ');
+    description.add(count == -1 ? 'alway ' :
+        (count == 0 ? 'never ' : 'sometimes '));
+    if (action == RETURN || action == PROXY)
+      description.add('return ');
+    else
+      description.add('throw ');
+    return description.addDescriptionOf(value);
+  }
+  Description describeMismatch(log, Description mismatchDescription) {
+    if (count != 1) {
+      mismatchDescription.add(entry.value);
+      for (LogEntry entry in log) {
+        if (entry.action != action || !value.matches(entry.value)) {
+          if (entry.action == RETURN || entry.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 _ResultMatcher(RETURN, wrapMatcher(value), -1);
+
+/**
+ *[sometimeReturned] asserts that at least one matching call to a method
+ * returned a value that matched [value].
+ */
+Matcher sometimeReturned(value) =>
+    new _ResultMatcher(RETURN, wrapMatcher(value), 1);
+
+/**
+ *[neverReturned] asserts that no matching calls to a method returned
+ * a value that matched [value].
+ */
+Matcher neverReturned(value) =>
+    new _ResultMatcher(RETURN, wrapMatcher(value), 0);
+
+/**
+ *[alwaysThrew] asserts that all matching calls to a method threw
+ * a value that matched [value].
+ */
+Matcher alwaysThrew(value) =>
+    new _ResultMatcher(THROW, wrapMatcher(value), -1);
+
+/**
+ *[sometimeThrew] asserts that at least one matching call to a method threw
+ * a value that matched [value].
+ */
+Matcher sometimeThrew(value) =>
+  new _ResultMatcher(THROW, wrapMatcher(value), 1);
+
+/**
+ *[neverThrew] asserts that no matching call to a method threw
+ * a value that matched [value].
+ */
+Matcher neverThrew(value) =>
+  new _ResultMatcher(THROW, wrapMatcher(value), 0);
+
+/**
  * [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:
  *
  *     class MockT extends Mock implements T {};
  *
  * Then specify the behavior of the Mock for different methods using
- * [when] (to select the method and parameters) and [thenReturn],
- * [alwaysReturn], [thenThrow] and/or [alwaysThrow].
+ * [whenThereAre] (to select the method and parameters) and [thenReturn],

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

whenThereAre feels really verbose, see some suggestions in the test file...

[gram, 2012/06/28 17:32:54]

Done.

+ * [alwaysReturn], [thenThrow], [alwaysThrow], [thenCall] or [alwaysCall].
+ * [thenReturn], [thenThrow] and [thenCall] are one-shot so you would
+ * typically call these more than once to specify a sequence of actions;
+ * this can be done with chained calls, e.g.:
+ *
+ *      m.whenThereAre(callsTo('foo')).
+ *          thenReturn(0).thenReturn(1).thenReturn(2);

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

you can also use cascades here :)
m.whenThereAre(callsTo('foo'))..thenReturn(0)
                              ..thenReturn(1)
                              ..thenReturn(2);

[gram, 2012/06/28 17:32:54]

Yeah, but most people are never going to know they exist! I only found out
yesterday :-)

+ *
+ * [thenCall] and [alwaysCall] allow you to proxy mocked methods, chaining
+ * to some other implementation. This provides a way to implement 'spies'.

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

It took me a while to get what are proxies and spies. An example would help.

I'd also emphasize that the value of this is that you can write your own
implementation of the method using a closure and passing it to [thenCall] or
[alwaysCall].

We should also mention where the return value comes from on this case.

This might be an interesting example:
  m.whenThereAre(callsTo('foo')).thenReturn(0)
is equivalent to:
  m.whenThereAre(callsTo('foo')).thenCall(() => 0)

[gram, 2012/06/28 17:32:54]

I've changed comments in a few places that hopefully make this clearer,
including your example too.

  *
  * You can then use the mock object. Once you are done, to verify the
- * behavior, use [verify] to extract a relevant subset of method call
- * logs and apply [Matchers] to these.
+ * behavior, use [forThe] to extract a relevant subset of method call

[Siggi Cherem (dart-lang), 2012/06/28 00:44:40]

:-( I liked verify better... more suggestions on the test file...

+ * logs and apply [Matchers] to these through calling [verify].
  *
  * Limitations:
  * - only positional parameters are supported (up to 10);
  * - to mock getters you will need to include parentheses.
  *
  * Here is a simple example:
  *
  *     class MockList extends Mock implements List {};
  *
  *     List m = new MockList();
- *     m.when('add', anything).alwaysReturn(0);
+ *     m.whenThereAre(callsTo('add', anything)).alwaysReturn(0);
  *
  *     m.add('foo');
  *     m.add('bar');
  *
- *     m.verify('add', anything, was:calledExactly(2));
- *     m.verify('add', 'foo', was:calledOnce);
- *     m.verify('add', 'isNull, was:neverCalled);
+ *     m.forThe(callsTo('add', anything)).verify(calledExactly(2));
+ *     m.forThe(callsTo('add', 'foo')).verify(calledOnce);
+ *     m.forThe(callsTo('add', 'isNull)).verify(neverCalled);
+ *
+ * Note that we don't need to provide argument matchers for all arguments,
+ * but we do need to provide arguments for all matchers. So this is allowed:
+ *
+ *     m.whenThereAre(callsTo('add')).alwaysReturn(0);
+ *     m.add(1, 2);
+ *
+ * But this is not allowed and will throw an exception:
+ *
+ *     m.whenThereAre(callsTo('add', anything, anything)).alwaysReturn(0);
+ *     m.add(1);
+ *
+ * Here is a way to implement a 'spy':
+ *
+ *     class Foo {
+ *       bar(a, b, c) => a + b + c;
+ *     }
+ *
+ *     class MockFoo extends Mock implements Foo {
+ *       Foo real;
+ *       MockFoo() {
+ *         real = new Foo();
+ *         this.whenThereAre(callsTo('bar')).alwaysCall(real.bar);
+ *       }
+ *     }
+ *
  */
 class Mock {
   Map<String,Behavior> behaviors; /** The set of [behavior]s supported. */
   LogEntryList log; /** The [log] of calls made. */
 
   Mock() {
     behaviors = new Map<String,Behavior>();
     log = new LogEntryList(new List<LogEntry>());
   }
 
   /**
-   * [when] is used to create a new or extend an existing [Behavior].
-   * The [method] name and the argument [Matcher] is specified. A
-   * corresponding [CallMatcher] is created, and the [Behavior]s for
-   * its signature are returned (being created first if needed).
+   * [whenThereAre] is used to create a new or extend an existing [Behavior].
+   * A [CallMatcher] [filter] must be supplied, and the [Behavior]s for
+   * that signature are returned (being created first if needed).
+   *
+   * The name [whenThereAre] was chosen to flow grammatically with the
+   * typical use case:
+   *
+   *     mock.whenThereAre(callsTo(...)).thenAlwaysReturn(...);
    */
-  Behavior when(String method, [
-       arg0 = _noArg,
-       arg1 = _noArg,
-       arg2 = _noArg,
-       arg3 = _noArg,
-       arg4 = _noArg,
-       arg5 = _noArg,
-       arg6 = _noArg,
-       arg7 = _noArg,
-       arg8 = _noArg,
-       arg9 = _noArg]) {
-    CallMatcher logfilter = new CallMatcher(method,
-        arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9);
-    String key = logfilter.toString();
+  Behavior whenThereAre(CallMatcher filter) {
+    String key = filter.toString();
     if (!behaviors.containsKey(key)) {
-      Behavior b = new Behavior(logfilter);
+      Behavior b = new Behavior(filter);
       behaviors[key] = b;
       return b;
     } else {
       return behaviors[key];
     }
   }
 
   /**
    * This is the handler for method calls. We loo through the list
    * of [Behavior]s, and find the first match that still has return
    * values available, and then do the action specified by that
    * return value. If we find no [Behavior] to apply an exception is
    * thrown.
    */
   noSuchMethod(String name, List args) {
     for (String k in behaviors.getKeys()) {
       Behavior b = behaviors[k];
       if (b.matches(name, args)) {
-        List rv = b.returnValues;
-        if (rv == null || rv.length == 0) {
+        List actions = b.actions;
+        if (actions == null || actions.length == 0) {
           continue; // No return values left in this Behavior.
         }
         // Get the first response.
-        BehaviorValue bv = rv[0];
+        BehaviorValue bv = 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 (--bv.count == 0) {
-          rv.removeRange(0, 1);
-          if (rv.length == 0) {
+          actions.removeRange(0, 1);
+          if (actions.length == 0) {
             // Remove the behavior. Note that in the future there
             // may be some value in preserving the behaviors for
             // auditing purposes (e.g. how many times was this behavior used?).
             // If we do decide to keep them and perf is an issue instead of
             // deleting we could move this to a separate list.
             behaviors.remove(k);
           }
         }
-        // Log the method call and the response.
-        log.add(new LogEntry(name, args, bv));
         // Do the response.
-        if (bv.isThrow) {
-          throw bv.value;
-        } else {
-          return bv.value;
+        switch (bv.action) {
+          case RETURN:
+            log.add(new LogEntry(name, args, bv.action, bv.value));
+            return bv.value;
+          case THROW:
+            log.add(new LogEntry(name, args, bv.action, bv.value));
+            throw bv.value;
+          case PROXY:
+            var rtn;
+            switch (args.length) {
+              case 0:
+                rtn = bv.value();
+                break;
+              case 1:
+                rtn = bv.value(args[0]);
+                break;
+              case 2:
+                rtn = bv.value(args[0], args[1]);
+                break;
+              case 3:
+                rtn = bv.value(args[0], args[1], args[2]);
+                break;
+              case 4:
+                rtn = bv.value(args[0], args[1], args[2], args[3]);
+                break;
+              case 5:
+                rtn = bv.value(args[0], args[1], args[2], args[3], args[4]);
+                break;
+              case 6:
+                rtn = bv.value(args[0], args[1], args[2], args[3],
+                    args[4], args[5]);
+                break;
+              case 7:
+                rtn = bv.value(args[0], args[1], args[2], args[3],
+                    args[4], args[5], args[6]);
+                break;
+              case 8:
+                rtn = bv.value(args[0], args[1], args[2], args[3],
+                    args[4], args[5], args[6], args[7]);
+                break;
+              case 9:
+                rtn = bv.value(args[0], args[1], args[2], args[3],
+                    args[4], args[5], args[6], args[7], args[8]);
+                break;
+              case 9:
+                rtn = bv.value(args[0], args[1], args[2], args[3],
+                    args[4], args[5], args[6], args[7], args[8], args[9]);
+                break;
+              default:
+                throw new Exception(
+                    "Cannot proxy calls with more than 10 parameters");
+            }
+            log.add(new LogEntry(name, args, bv.action, rtn));
+            return rtn;
         }
       }
     }
     throw new Exception('No behavior specified for method $name');
   }
 
   /**
-   * [verify] extracts all calls from the object log that match the
-   * method signature, then applies the [was] matcher. The matching
-   * list of [LogEntry]s is returned so that further calls to verify()
-   * can be chained .
+   * [forThe] extracts all calls from the object 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 mock object's log, else they are removed.
+   * Removal allows us to verify a set of interactions and then verify
+   * that there are no other interactions left.
+   *
+   * The name [forThe] was chosen to flow grammatically with [callsTo],
+   * as this is usually used in the form:
+   *
+   *     mock.forThe(callsTo(...)).verify(...);
    */
-  LogEntryList verify(String method, [ arg0 = _noArg,
-                          arg1 = _noArg,
-                          arg2 = _noArg,
-                          arg3 = _noArg,
-                          arg4 = _noArg,
-                          arg5 = _noArg,
-                          arg6 = _noArg,
-                          arg7 = _noArg,
-                          arg8 = _noArg,
-                          arg9 = _noArg,
-                          Matcher was = calledOnce]) {
-    CallMatcher logfilter = new CallMatcher(method,
-      arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9);
-    LogEntryList _logs = log.getMatches(logfilter);
-    _logs.verify(was);
-    return _logs;
+  LogEntryList forThe(CallMatcher logFilter, [bool destructive = false]) {
+    return log.getMatches(logFilter, destructive);
   }
 
   /** [verifyZeroInteractions] returns true if no calls were made */
   bool verifyZeroInteractions() => log.logs.length == 0;
-
 }
 
+