Improved the way we generate mismatch descriptions.

lib/unittest/interfaces.dart

Index: lib/unittest/interfaces.dart
===================================================================
--- lib/unittest/interfaces.dart	(revision 9956)
+++ 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);

[Siggi Cherem (dart-lang), 2012/07/31 17:16:40]

should matchState be optional?

[gram, 2012/07/31 17:56:01]

I decided not to do this because the initial call to matches happens only in one
place (expect) which is going to pass a value in, and that value is used
recursively. So there is no need right now for it to be optional, and making it
optional  means we have to add tests for null wherever we have a failure and are
going to use it. SO there would be cost with no benefit.

 
   /** 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);

[Siggi Cherem (dart-lang), 2012/07/31 17:16:40]

should matchState + verbose be optional?

[gram, 2012/07/31 17:56:01]

Similarly, there is currently only one place where we pass this in initially, so
there is no need to make it optional.

 }
 
 /**
@@ -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);
 }