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