Add matchers for unit testing futures:

lib/unittest/core_matchers.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.
 
 
 /**
  * Returns a matcher that matches empty strings, maps or collections.
  */
 final Matcher isEmpty = const _Empty();
 
@@ skipping 108 matching lines @@
 class isInstanceOf<T> extends BaseMatcher {
   final String _name;
   const isInstanceOf([name = 'specified type']) : this._name = name;
   bool matches(obj) => obj is T;
   // The description here is lame :-(
   Description describe(Description description) =>
       description.add('an instance of ${_name}');
 }
 
 /**
- * A matcher that matches functions that throw exceptions when called.
- * The value passed to expect() should be a reference to the function.
- * Note that the function cannot take arguments; to handle this
- * a wrapper will have to be created.
- * The function will be called once upon success, or twice upon failure
- * (the second time to get the failure description).
+ * This can be used to match two kinds of objects:
+ *
+ *   * A [Function] that throws an exception when called. The function cannot
+ *     take any arguments. If you want to test that a function expecting
+ *     arguments throws, wrap it in another zero-argument function that calls
+ *     the one you want to test. The function will be called once upon success,
+ *     or twice upon failure (the second time to get the failure description).

[Siggi Cherem (dart-lang), 2012/06/13 00:04:39]

I know this is not part of your change, but I'm commenting so that I don't
forget:
I think we should only call it once (I can see in the future people finding it
confusing that some side-effects have occurred twice). One possible solution is
to change _Throws to track how it failed, so that describeMismatch doesn't have
to re execute the function.

[Bob Nystrom, 2012/06/13 20:22:06]

Yeah, I share your concerns here. We can discuss this and see if we can come up
with a better solution.

+ *
+ *   * A [Future] that completes with an exception. Note that this creates an
+ *     asynchronous expectation. The call to `expect()` that includes this will
+ *     return immediately and execution will continue. Later, when the future
+ *     completes, the actual expectation will run.
  */
 final Matcher throws = const _Throws();
 
 /**
- * Returns a matcher that matches a function call against an exception,
- * which is in turn constrained by a [matcher].
- * The value passed to expect() should be a reference to the function.
- * Note that the function cannot take arguments; to handle this
- * a wrapper will have to be created.
- * The function will be called once upon success, or twice upon failure
- * (the second time to get the failure description).
+ * This can be used to match two kinds of objects:
+ *
+ *   * A [Function] that throws an exception when called. The function cannot
+ *     take any arguments. If you want to test that a function expecting
+ *     arguments throws, wrap it in another zero-argument function that calls
+ *     the one you want to test. The function will be called once upon success,
+ *     or twice upon failure (the second time to get the failure description).
+ *
+ *   * A [Future] that completes with an exception. Note that this creates an
+ *     asynchronous expectation. The call to `expect()` that includes this will
+ *     return immediately and execution will continue. Later, when the future
+ *     completes, the actual expectation will run.
+ *
+ * In both cases, when an exception is thrown, this will test that the exception
+ * object matches [matcher]. If [matcher] is not an instance of [Matcher], it

[Siggi Cherem (dart-lang), 2012/06/13 00:04:39]

should we then rename [matcher] to something more informative, maybe
[exceptionOrMatcher]

[Bob Nystrom, 2012/06/13 20:22:06]

The other places in the API where we call wrapMatcher() also use "matcher" for
this. Maybe not ideal, but I like that it's at least consistent.

+ * will implicitly be treated as `equals(matcher)`.
  */
-Matcher throwsA(Matcher matcher) => new _Throws(matcher);
+Matcher throwsA(matcher) => new _Throws(wrapMatcher(matcher));
 
 /**
  * A matcher that matches a function call against no exception.
  * The function will be called once. Any exceptions will be silently swallowed.
  * The value passed to expect() should be a reference to the function.
  * Note that the function cannot take arguments; to handle this
  * a wrapper will have to be created.
  */
 final Matcher returnsNormally = const _ReturnsNormally();
 
 class _Throws extends BaseMatcher {
   final Matcher _matcher;
 
   const _Throws([Matcher matcher = null]) : this._matcher = matcher;
 
   bool matches(item) {
+    if (item is Future) {
+      // Queue up an asynchronous expectation that validates when the future
+      // completes.
+      item.onComplete(expectAsync1((future) {
+        if (future.hasValue) {
+          expect(false,
+              "Expected future to fail, but succeeded with '${future.value}'.");
+        } else if (_matcher != null) {
+          expect(future.exception, _matcher);
+        }
+      }));
+
+      // It hasn't failed yet.
+      return true;
+    }
+
     try {
       item();
       return false;
     } catch (final e) {
       return _matcher == null || _matcher.matches(e);
     }
   }
 
   Description describe(Description description) {
     if (_matcher == null) {
@@ skipping 227 matching lines @@
       }
     } else if (item is Map) {
       return item.containsKey(_expected);
     }
     return false;
   }
 
   Description describe(Description description) =>
       description.add('contains ').addDescriptionOf(_expected);
 }