Improved the way we generate mismatch descriptions.

lib/unittest/interfaces.dart

Index: lib/unittest/interfaces.dart
===================================================================
--- lib/unittest/interfaces.dart	(revision 10002)
+++ lib/unittest/interfaces.dart	(working copy)
@@ -13,7 +13,8 @@
  * is replaced it may be desirable to replace the [stringDescription]
  * error formatter with another.
  */
-typedef String ErrorFormatter(actual, Matcher matcher, String reason);
+typedef String ErrorFormatter(actual, Matcher matcher, String reason,
+    MatchState matchState, bool verbose);
 
 /**
  * Matchers build up their error messages by appending to
@@ -49,14 +50,29 @@
  * must always be provided as they are highly matcher-specific.
  */
 interface Matcher {
-  /** This does the matching of the actual vs expected values. */
-  bool matches(item);
+  /**
+   * This does the matching of the actual vs expected values.
+   * [item] is the actual value. [matchState] can be supplied
+   * and may be used to add details about the mismatch that are too
+   * costly to determine in [describeMismatch].
+   */
+  bool matches(item, MatchState matchState);
 
   /** This builds a textual description of the matcher. */
   Description describe(Description description);
 
-  /**This builds a textual description of a specific mismatch. */
-  Description describeMismatch(item, Description mismatchDescription);
+  /**
+   * This builds a textual description of a specific mismatch. [item]
+   * is the value that was tested by [matches]; [matchState] is
+   * the [MatchState] that was passed to and supplemented by [matches]
+   * with additional information about the mismact, and [mismatchDescription]
+   * is the [Description] that is being built to decribe the mismatch.
+   * A few matchers make use of the [verbose] flag to provide detailed
+   * information that is not typically included but can be of help in
+   * diagnosing failures, such as stack traces.
+   */
+  Description describeMismatch(item, Description mismatchDescription,
+      MatchState matchState, bool verbose);
 }
 
 /**
@@ -71,10 +87,13 @@
 
   /**
    * This handles failures given the actual [value], the [matcher]
-   * and the [reason]. It will typically use these to create a
-   * detailed error message (typically using an [ErrorFormatter])
-   * and then call [fail].
+   * the [reason] (argument from [expect]), some additonal [matchState]
+   * generated by the [matcher], and a verbose flag which controls in
+   * some cases how much [matchState] information is used. It will use
+   * these to create a detailed error message (typically by calling
+   * an [ErrorFormatter]) and then call [fail] with this message.
    */
-  void failMatch(actual, Matcher matcher, String reason);
+  void failMatch(actual, Matcher matcher, String reason,
+                 MatchState matchState, bool verbose);
 }