make Matcher generic

[DartBot]

<img src="https://avatars.githubusercontent.com/u/444270?v=3" align="left" width="96" height="96"hspace="10"> Issue by seaneagan
Originally opened as dart-lang/sdk#3652

---

It would be nice if dart:unittest's Matcher was generic:

interface Matcher<T> {
  bool matches(T item);
  //...
}

//...

Matcher<num> closeTo(num value, num delta);
Matcher<Map<K, V>> containsPair<K, V>(K key, V value);
Matcher<Map<Dynamic, V>> containsValue<V>(V value);
Matcher<Map<K, Dynamic>> containsKey<K>(K key);
Matcher<String> startsWith(String str);
Matcher<String> endsWith(String str);
Matcher<String> matches(Pattern pattern);
Matcher<String> equalsIgnoringCase(String str);
Matcher<String> equalsIgnoringWhiteSpace(String str);
Matcher<T> lessThan<T extends Comparable<T>>(Comparable c);
Matcher<T> greaterThan<T extends Comparable<T>>(T c);
Matcher<T> lessThanOrEqualTo<T extends Comparable<T>>(T c);
Matcher<T> greaterThanOrEqualTo<T extends Comparable<T>>(T c);
Matcher<Collection<E>> every(Matcher<E>);
Matcher<Collection<E>> some(Matcher<E>);
Matcher<bool> get isTrue();
Matcher<bool> get isFalse();
Matcher<num> get isPositive();
Matcher<num> get isNegative();
Matcher<num> get isNonPositive();
Matcher<num> get isNonNegative();
Matcher<num> get isZero();
Matcher<num> get isNonZero();
Matcher<Function> get throws();
Matcher<Function> get returnsNormally();
Matcher<Future> get completes();
//etc.

If issue dart-lang/sdk#4 were fixed, then "expect" could change to:

void expect<T>(T item, Matcher<T> matcher);
//...
expect<bool>(b, isTrue);
expect<num>(i, lessThan<num>(6));
expect<String>(s, matches(new Regexp(@­"\d+"));

a better option though might be to change expect to an instance method of Matcher, and rename it to "test":

isTrue.test(b);
isPositive.test(x);
matches(new Regexp(@­"\d+")).test(s);

[DartBot]

<img src="https://avatars.githubusercontent.com/u/444270?v=3" align="left" width="48" height="48"hspace="10"> Comment by seaneagan

---

If going the Matcher#test route, it would be nice to have it be a "final method" as in Java, either in BaseMatcher, or just rename BaseMatcher to Matcher and get rid of the explicit interface.

[DartBot]

<img src="https://avatars.githubusercontent.com/u/3276024?v=3" align="left" width="48" height="48"hspace="10"> Comment by anders-sandholm

---

Added Area-Test, Triaged labels.

[DartBot]

<img src="https://avatars.githubusercontent.com/u/3276024?v=3" align="left" width="48" height="48"hspace="10"> Comment by anders-sandholm

---

Removed Area-Test label.
Added Area-UnitTest label.

[DartBot]

<img src="https://avatars.githubusercontent.com/u/2762632?v=3" align="left" width="48" height="48"hspace="10"> Comment by gramster

---

In many cases, the type of the argument is tested anyway and the matcher will fail with an appropriate error message if it is the wrong type. This could be done at compile time rather than run time using generics, but it adds developer pain to have to type every call to expect.

---

Added NotPlanned label.

[DartBot]

<img src="https://avatars.githubusercontent.com/u/444270?v=3" align="left" width="48" height="48"hspace="10"> Comment by seaneagan

---

Presumably if Dart added generic methods (issue dart-lang/sdk#254) the type argument to the method call would be optional just like all other type annotations are. Also, type arguments could likely be inferred in many cases.

Even if generic methods aren't added this would still make it much easier to tell which types each matcher matches against, since you can tell merely by looking at the method signature or field definitition, as opposed to having to read the doc comments.

[DartBot]

<img src="https://avatars.githubusercontent.com/u/17034?v=3" align="left" width="48" height="48"hspace="10"> Comment by kevmoo

---

Added Pkg-Unittest label.

[DartBot]

<img src="https://avatars.githubusercontent.com/u/17034?v=3" align="left" width="48" height="48"hspace="10"> Comment by kevmoo

---

Removed Area-UnitTest label.
Added Area-Pkg label.