Add matchers for unit testing futures:

lib/unittest/future_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.
+
+/**
+ * Matches a [Future] that completes successfully with a value. 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.
+ *
+ * To test that a Future completes with an exception, you can use [throws] and
+ * [throwsA].
+ */
+Matcher completes = const _Completes(null);

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

completes => completesWithValue or completesNormally

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

Hmm. I see the ambiguity with the current name since you can "complete" a future
with an error, but those seem painfully long.

How about after this patch we discuss some general terminology changes for
future? Whenever I document future-related stuff, I find it really confusing to
talk about completing with errors. Maybe we should have "succeed" and "fail" or
something else?

+
+/**
+ * Matches a [Future] that completes succesfully with a value that matches
+ * [matcher]. 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.
+ *
+ * To test that a Future completes with an exception, you can use [throws] and
+ * [throwsA].
+ */
+Matcher completion(matcher) => new _Completes(wrapMatcher(matcher));

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

I'm trying to think if there are other names that wouled read a bit better than
'completion', some ideas (I'm not convinced of any yet):
expect(f, completion(equals(5));
expect(f, hasValue(equals(5));
expect(f, completesWith(equals(5));
expect(f, completesWithValue(equals(5));
expect(f, willBe(equals(5));
expect(f, asyncCompletes(equals(5));

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

Right, this is what I was thinking too. "completion" seemed to read the best
with nested matchers to me. "completion equals" "completion is not null", etc.

[Siggi Cherem (dart-lang), 2012/06/13 20:27:20]

I guess I like 'completion' less because it is a noun, while all other matchers
are written as verbs. 

[Bob Nystrom, 2012/06/13 20:35:51]

Yeah, but I think that's consistent with other matchers that take nested
matchers: someElement(), everyElement().

+
+class _Completes extends BaseMatcher {
+  final Matcher _matcher;
+
+  const _Completes(this._matcher);
+
+  bool matches(item) {
+    if (item is! Future) return false;

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

should this by a synchronous expectation (e.g.

  expect(item is Future, '... invalid matcher');

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

That feels a little confusing since this will be run inside a call to expect().
Other matchers (like the string ones) just return false when the is test fails.

+
+    item.onComplete(expectAsync1((future) {
+      expect(future.hasValue,
+          'Expected future to complete successfully, but it failed');
+      if (_matcher != null) expect(future.value, _matcher);
+    }));
+
+    return true;
+  }
+
+  Description describe(Description description) {
+    if (_matcher == null) {
+      description.add('completes successfully');
+    } else {
+      description.add('completes to a value that ').addDescriptionOf(_matcher);
+    }
+    return description;
+  }
+}