Added a new Matcher, FeatureMatcher, that is a useful abstract base class

pkg/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.
  */
 const Matcher isEmpty = const _Empty();
 
@@ skipping 607 matching lines @@
   final _matcher;
   final String _description;
 
   const _Predicate(this._matcher, this._description);
 
   bool matches(item, MatchState matchState) => _matcher(item);
 
   Description describe(Description description) =>
       description.add(_description);
 }
+
+/**
+ * A useful utility class for implementing other matchers through inheritance.
+ * Derived classes should call the base constructor with a feature name and
+ * description, and an instance matcher, and should implement the
+ * [featureValueOf] abstract method.
+ *
+ * The feature description will typically describe the item and the feature,
+ * while the feature name will just name the feature. For example, we may
+ * have a Widget class where each Widget has a price; we could make a
+ * FeatureMatcher that can make assertions about prices with:
+ *
+ *     class HasPrice extends FeatureMatcher {
+ *       const HasPrice(matcher) :
+ *           super("Widget with price that is", "price", matcher);
+ *       featureValueOf(actual) => actual.price;
+ *     }
+ *
+ * and then use this for example like:
+ *
+ *      expect(inventoryItem, HasPrice(greaterThan(0)));

[Siggi Cherem (dart-lang), 2012/10/17 19:53:05]

HasPrice => new HasPrice?

+ */
+abstract class FeatureMatcher extends BaseMatcher {

[Siggi Cherem (dart-lang), 2012/10/17 19:54:01]

an alternative name: CustomMatcher?

+  final String _featureDescription;
+  final String _featureName;
+  final Matcher _matcher;
+
+  const FeatureMatcher(this._featureDescription, this._featureName,
+      this._matcher);
+
+  /** Implement this to extract the interesting feature.*/
+  featureValueOf(actual);
+
+  bool matches(item, MatchState matchState) {
+    var f = featureValueOf(item);
+    if (_matcher.matches(f, matchState)) return true;
+    matchState.state = { 'innerState': matchState.state, 'feature': f };
+    return false;
+  }
+
+  Description describe(Description description) =>
+      description.add(_featureDescription).add(' ').addDescriptionOf(_matcher);
+
+  Description describeMismatch(item, Description mismatchDescription,
+                               MatchState matchState, bool verbose) {
+    mismatchDescription.add(_featureName).add(' ');
+    _matcher.describeMismatch(matchState.state['feature'], mismatchDescription,
+        matchState.state['innerState'], verbose);
+    return mismatchDescription;
+  }
+}