Add matchers for unit testing futures:

Add matchers for unit testing futures:

- completes
- completion()

Also made throws and throwsA() work with futures.

Committed: https://code.google.com/p/dart/source/detail?r=8632

[Bob Nystrom, 2012-06-12 18:45:41]

Unfortunately, I don't have tests for this stuff. I did a bunch of local testing
to make sure it works right, but I found it nigh impossible to make
unittest_test play nice with async-related tests.

I really would like to have automated tests for unittest itself, but I think we
may want something more stratified for that, like having the unittest library
and the tests of the unittest library run in separate isolates or processes.

[gram, 2012-06-12 22:12:42]

lgtm

LGTM

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

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/core_matc...
File lib/unittest/core_matchers.dart (right):

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/core_matc...
lib/unittest/core_matchers.dart:135: *     or twice upon failure (the second
time to get the failure description).
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.

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/core_matc...
lib/unittest/core_matchers.dart:159: * object matches [matcher]. If [matcher] is
not an instance of [Matcher], it
should we then rename [matcher] to something more informative, maybe
[exceptionOrMatcher]

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
File lib/unittest/future_matchers.dart (right):

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:14: Matcher completes = const
_Completes(null);
completes => completesWithValue or completesNormally

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:25: Matcher completion(matcher) => new
_Completes(wrapMatcher(matcher));
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));

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:33: if (item is! Future) return false;
should this by a synchronous expectation (e.g.

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

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

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/core_matc...
File lib/unittest/core_matchers.dart (right):

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/core_matc...
lib/unittest/core_matchers.dart:135: *     or twice upon failure (the second
time to get the failure description).
On 2012/06/13 00:04:39, sigmund wrote:
> 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.

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

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/core_matc...
lib/unittest/core_matchers.dart:159: * object matches [matcher]. If [matcher] is
not an instance of [Matcher], it
On 2012/06/13 00:04:39, sigmund wrote:
> should we then rename [matcher] to something more informative, maybe
> [exceptionOrMatcher]

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.

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
File lib/unittest/future_matchers.dart (right):

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:14: Matcher completes = const
_Completes(null);
On 2012/06/13 00:04:39, sigmund wrote:
> completes => completesWithValue or completesNormally

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?

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:25: Matcher completion(matcher) => new
_Completes(wrapMatcher(matcher));
On 2012/06/13 00:04:39, sigmund wrote:
> 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));

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.

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:33: if (item is! Future) return false;
On 2012/06/13 00:04:39, sigmund wrote:
> should this by a synchronous expectation (e.g.
> 
>   expect(item is Future, '... invalid matcher');

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.

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

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
File lib/unittest/future_matchers.dart (right):

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:25: Matcher completion(matcher) => new
_Completes(wrapMatcher(matcher));
On 2012/06/13 20:22:06, Bob Nystrom wrote:
> On 2012/06/13 00:04:39, sigmund wrote:
> > 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));
> 
> 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.

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]

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
File lib/unittest/future_matchers.dart (right):

https://chromiumcodereview.appspot.com/10548005/diff/1/lib/unittest/future_ma...
lib/unittest/future_matchers.dart:25: Matcher completion(matcher) => new
_Completes(wrapMatcher(matcher));
On 2012/06/13 20:27:20, sigmund wrote:
> On 2012/06/13 20:22:06, Bob Nystrom wrote:
> > On 2012/06/13 00:04:39, sigmund wrote:
> > > 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));
> > 
> > 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.
> 
> I guess I like 'completion' less because it is a noun, while all other
matchers
> are written as verbs. 

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

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

lgtm

makes sense.