OLD | NEW |
(Empty) | |
| 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 |
| 3 // BSD-style license that can be found in the LICENSE file. |
| 4 |
| 5 // To decouple the reporting of errors, and allow for extensibility of |
| 6 // matchers, we make use of some interfaces. |
| 7 |
| 8 /** |
| 9 * The ErrorFormatter type is used for functions that |
| 10 * can be used to build up error reports upon [expect] failures. |
| 11 * There is one built-in implementation ([defaultErrorFormatter]) |
| 12 * which is used by the default failure handler. If the failure handler |
| 13 * is replaced it may be desirable to replace the [stringDescription] |
| 14 * error formatter with another. |
| 15 */ |
| 16 typedef String ErrorFormatter(actual, Matcher matcher, String reason); |
| 17 |
| 18 /** |
| 19 * Matchers build up their error messages by appending to |
| 20 * Description objects. This interface is implemented by |
| 21 * StringDescription. This interface is unlikely to need |
| 22 * other implementations, but could be useful to replace in |
| 23 * some cases - e.g. language conversion. |
| 24 */ |
| 25 interface Description { |
| 26 /** This is used to add arbitrary text to the description. */ |
| 27 Description add(String text); |
| 28 |
| 29 /** This is used to add a meaningful description of a value. */ |
| 30 Description addDescriptionOf(value); |
| 31 |
| 32 /** |
| 33 * This is used to add a description of an [Iterable] [list], |
| 34 * with appropriate [start] and [end] markers and inter-element [separator]. |
| 35 */ |
| 36 Description addAll(String start, String separator, String end, |
| 37 Iterable list); |
| 38 } |
| 39 |
| 40 /** |
| 41 * [expect] Matchers must implement the Matcher interface. |
| 42 * The base Matcher class that implements this interface has |
| 43 * a generic implementation of [describeMismatch] so this does |
| 44 * not need to be provided unless a more clear description is |
| 45 * required. The other two methods ([matches] and [describe]) |
| 46 * must always be provided as they are highly matcher-specific. |
| 47 */ |
| 48 interface Matcher { |
| 49 /** This does the matching of the actual vs expected values. */ |
| 50 bool matches(item); |
| 51 |
| 52 /** This builds a textual description of the matcher. */ |
| 53 Description describe(Description description); |
| 54 |
| 55 /**This builds a textual description of a specific mismatch. */ |
| 56 Description describeMismatch(item, Description mismatchDescription); |
| 57 } |
| 58 |
| 59 /** |
| 60 * Failed matches are reported using a default IFailureHandler. |
| 61 * The default implementation simply throws ExpectExceptions; |
| 62 * this can be replaced by some other implementation of |
| 63 * IFailureHandler by calling configureExpectHandler. |
| 64 */ |
| 65 interface FailureHandler { |
| 66 /** This handles failures given a textual decription */ |
| 67 void fail(String reason); |
| 68 |
| 69 /** |
| 70 * This handles failures given the actual [value], the [matcher] |
| 71 * and the [reason]. It will typically use these to create a |
| 72 * detailed error message (typically using an [ErrorFormatter]) |
| 73 * and then call [fail]. |
| 74 */ |
| 75 void failMatch(actual, Matcher matcher, String reason); |
| 76 } |
| 77 |
OLD | NEW |