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; |
Siggi Cherem (dart-lang)
2014/06/02 16:47:09
not for this CL, but what do you think about mergi
| |
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 /** | 10 /// The ErrorFormatter type is used for functions that |
11 * The ErrorFormatter type is used for functions that | 11 /// can be used to build up error reports upon [expect] failures. |
12 * can be used to build up error reports upon [expect] failures. | 12 /// There is one built-in implementation ([defaultErrorFormatter]) |
13 * There is one built-in implementation ([defaultErrorFormatter]) | 13 /// which is used by the default failure handler. If the failure handler |
14 * which is used by the default failure handler. If the failure handler | 14 /// is replaced it may be desirable to replace the [stringDescription] |
15 * is replaced it may be desirable to replace the [stringDescription] | 15 /// error formatter with another. |
16 * error formatter with another. | |
17 */ | |
18 typedef String ErrorFormatter(actual, Matcher matcher, String reason, | 16 typedef String ErrorFormatter(actual, Matcher matcher, String reason, |
19 Map matchState, bool verbose); | 17 Map matchState, bool verbose); |
20 | 18 |
21 /** | 19 /// Matchers build up their error messages by appending to |
22 * Matchers build up their error messages by appending to | 20 /// Description objects. This interface is implemented by |
23 * Description objects. This interface is implemented by | 21 /// StringDescription. This interface is unlikely to need |
24 * StringDescription. This interface is unlikely to need | 22 /// other implementations, but could be useful to replace in |
25 * other implementations, but could be useful to replace in | 23 /// some cases - e.g. language conversion. |
26 * some cases - e.g. language conversion. | |
27 */ | |
28 abstract class Description { | 24 abstract class Description { |
29 int get length; | 25 int get length; |
30 | 26 |
31 /** Change the value of the description. */ | 27 /// Change the value of the description. |
32 Description replace(String text); | 28 Description replace(String text); |
33 | 29 |
34 /** This is used to add arbitrary text to the description. */ | 30 /// This is used to add arbitrary text to the description. |
35 Description add(String text); | 31 Description add(String text); |
36 | 32 |
37 /** This is used to add a meaningful description of a value. */ | 33 /// This is used to add a meaningful description of a value. |
38 Description addDescriptionOf(value); | 34 Description addDescriptionOf(value); |
39 | 35 |
40 /** | 36 /// This is used to add a description of an [Iterable] [list], |
41 * This is used to add a description of an [Iterable] [list], | 37 /// with appropriate [start] and [end] markers and inter-element [separator]. |
42 * with appropriate [start] and [end] markers and inter-element [separator]. | |
43 */ | |
44 Description addAll(String start, String separator, String end, Iterable list); | 38 Description addAll(String start, String separator, String end, Iterable list); |
45 } | 39 } |
46 | 40 |
47 /** | 41 /// [expect] Matchers must implement/extend the Matcher class. |
48 * [expect] Matchers must implement/extend the Matcher class. | 42 /// The base Matcher class has a generic implementation of [describeMismatch] |
49 * The base Matcher class has a generic implementation of [describeMismatch] | 43 /// so this does not need to be provided unless a more clear description is |
50 * so this does not need to be provided unless a more clear description is | 44 /// required. The other two methods ([matches] and [describe]) |
51 * required. The other two methods ([matches] and [describe]) | 45 /// must always be provided as they are highly matcher-specific. |
52 * must always be provided as they are highly matcher-specific. | |
53 */ | |
54 abstract class Matcher { | 46 abstract class Matcher { |
55 const Matcher(); | 47 const Matcher(); |
56 | 48 |
57 /** | 49 /// This does the matching of the actual vs expected values. |
58 * This does the matching of the actual vs expected values. | 50 /// [item] is the actual value. [matchState] can be supplied |
59 * [item] is the actual value. [matchState] can be supplied | 51 /// and may be used to add details about the mismatch that are too |
60 * and may be used to add details about the mismatch that are too | 52 /// costly to determine in [describeMismatch]. |
61 * costly to determine in [describeMismatch]. | |
62 */ | |
63 bool matches(item, Map matchState); | 53 bool matches(item, Map matchState); |
64 | 54 |
65 /** This builds a textual description of the matcher. */ | 55 /// This builds a textual description of the matcher. |
66 Description describe(Description description); | 56 Description describe(Description description); |
67 | 57 |
68 /** | 58 /// This builds a textual description of a specific mismatch. [item] |
69 * This builds a textual description of a specific mismatch. [item] | 59 /// is the value that was tested by [matches]; [matchState] is |
70 * is the value that was tested by [matches]; [matchState] is | 60 /// the [Map] that was passed to and supplemented by [matches] |
71 * the [Map] that was passed to and supplemented by [matches] | 61 /// with additional information about the mismact, and [mismatchDescription] |
72 * with additional information about the mismact, and [mismatchDescription] | 62 /// is the [Description] that is being built to decribe the mismatch. |
73 * is the [Description] that is being built to decribe the mismatch. | 63 /// A few matchers make use of the [verbose] flag to provide detailed |
74 * 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 |
75 * information that is not typically included but can be of help in | 65 /// diagnosing failures, such as stack traces. |
76 * diagnosing failures, such as stack traces. | |
77 */ | |
78 Description describeMismatch(item, Description mismatchDescription, | 66 Description describeMismatch(item, Description mismatchDescription, |
79 Map matchState, bool verbose) => mismatchDescription; | 67 Map matchState, bool verbose) => mismatchDescription; |
80 } | 68 } |
81 | 69 |
82 /** | 70 /// Failed matches are reported using a default IFailureHandler. |
83 * Failed matches are reported using a default IFailureHandler. | 71 /// The default implementation simply throws [TestFailure]s; |
84 * The default implementation simply throws [TestFailure]s; | 72 /// this can be replaced by some other implementation of |
85 * this can be replaced by some other implementation of | 73 /// IFailureHandler by calling configureExpectHandler. |
86 * IFailureHandler by calling configureExpectHandler. | |
87 */ | |
88 abstract class FailureHandler { | 74 abstract class FailureHandler { |
89 /** This handles failures given a textual decription */ | 75 /// This handles failures given a textual decription |
90 void fail(String reason); | 76 void fail(String reason); |
91 | 77 |
92 /** | 78 /// This handles failures given the actual [value], the [matcher] |
93 * This handles failures given the actual [value], the [matcher] | 79 /// the [reason] (argument from [expect]), some additonal [matchState] |
94 * the [reason] (argument from [expect]), some additonal [matchState] | 80 /// generated by the [matcher], and a verbose flag which controls in |
95 * generated by the [matcher], and a verbose flag which controls in | 81 /// some cases how much [matchState] information is used. It will use |
96 * some cases how much [matchState] information is used. It will use | 82 /// these to create a detailed error message (typically by calling |
97 * these to create a detailed error message (typically by calling | 83 /// an [ErrorFormatter]) and then call [fail] with this message. |
98 * an [ErrorFormatter]) and then call [fail] with this message. | |
99 */ | |
100 void failMatch(actual, Matcher matcher, String reason, | 84 void failMatch(actual, Matcher matcher, String reason, |
101 Map matchState, bool verbose); | 85 Map matchState, bool verbose); |
102 } | 86 } |
103 | |
OLD | NEW |