OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 library matcher.interfaces; | 5 library matcher.interfaces; |
6 | 6 |
7 // To decouple the reporting of errors, and allow for extensibility of | 7 // To decouple the reporting of errors, and allow for extensibility of |
8 // matchers, we make use of some interfaces. | 8 // matchers, we make use of some interfaces. |
9 | 9 |
10 /// The ErrorFormatter type is used for functions that | |
11 /// can be used to build up error reports upon [expect] failures. | |
12 /// There is one built-in implementation ([defaultErrorFormatter]) | |
13 /// which is used by the default failure handler. If the failure handler | |
14 /// is replaced it may be desirable to replace the [stringDescription] | |
15 /// error formatter with another. | |
16 typedef String ErrorFormatter(actual, Matcher matcher, String reason, | |
17 Map matchState, bool verbose); | |
18 | |
19 /// Matchers build up their error messages by appending to | 10 /// Matchers build up their error messages by appending to |
20 /// Description objects. This interface is implemented by | 11 /// Description objects. This interface is implemented by |
21 /// StringDescription. This interface is unlikely to need | 12 /// StringDescription. This interface is unlikely to need |
22 /// other implementations, but could be useful to replace in | 13 /// other implementations, but could be useful to replace in |
23 /// some cases - e.g. language conversion. | 14 /// some cases - e.g. language conversion. |
24 abstract class Description { | 15 abstract class Description { |
25 int get length; | 16 int get length; |
26 | 17 |
27 /// Change the value of the description. | 18 /// Change the value of the description. |
28 Description replace(String text); | 19 Description replace(String text); |
(...skipping 22 matching lines...) Expand all Loading... |
51 /// and may be used to add details about the mismatch that are too | 42 /// and may be used to add details about the mismatch that are too |
52 /// costly to determine in [describeMismatch]. | 43 /// costly to determine in [describeMismatch]. |
53 bool matches(item, Map matchState); | 44 bool matches(item, Map matchState); |
54 | 45 |
55 /// This builds a textual description of the matcher. | 46 /// This builds a textual description of the matcher. |
56 Description describe(Description description); | 47 Description describe(Description description); |
57 | 48 |
58 /// This builds a textual description of a specific mismatch. [item] | 49 /// This builds a textual description of a specific mismatch. [item] |
59 /// is the value that was tested by [matches]; [matchState] is | 50 /// is the value that was tested by [matches]; [matchState] is |
60 /// the [Map] that was passed to and supplemented by [matches] | 51 /// the [Map] that was passed to and supplemented by [matches] |
61 /// with additional information about the mismact, and [mismatchDescription] | 52 /// with additional information about the mismatch, and [mismatchDescription] |
62 /// is the [Description] that is being built to decribe the mismatch. | 53 /// is the [Description] that is being built to decribe the mismatch. |
63 /// A few matchers make use of the [verbose] flag to provide detailed | 54 /// A few matchers make use of the [verbose] flag to provide detailed |
64 /// information that is not typically included but can be of help in | 55 /// information that is not typically included but can be of help in |
65 /// diagnosing failures, such as stack traces. | 56 /// diagnosing failures, such as stack traces. |
66 Description describeMismatch(item, Description mismatchDescription, | 57 Description describeMismatch(item, Description mismatchDescription, |
67 Map matchState, bool verbose) => mismatchDescription; | 58 Map matchState, bool verbose) => mismatchDescription; |
68 } | 59 } |
69 | |
70 /// Failed matches are reported using a default IFailureHandler. | |
71 /// The default implementation simply throws [TestFailure]s; | |
72 /// this can be replaced by some other implementation of | |
73 /// IFailureHandler by calling configureExpectHandler. | |
74 abstract class FailureHandler { | |
75 /// This handles failures given a textual decription | |
76 void fail(String reason); | |
77 | |
78 /// This handles failures given the actual [value], the [matcher] | |
79 /// the [reason] (argument from [expect]), some additonal [matchState] | |
80 /// generated by the [matcher], and a verbose flag which controls in | |
81 /// some cases how much [matchState] information is used. It will use | |
82 /// these to create a detailed error message (typically by calling | |
83 /// an [ErrorFormatter]) and then call [fail] with this message. | |
84 void failMatch(actual, Matcher matcher, String reason, | |
85 Map matchState, bool verbose); | |
86 } | |
OLD | NEW |