| 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 library matcher.interfaces; | |
| 6 | |
| 7 // To decouple the reporting of errors, and allow for extensibility of | |
| 8 // matchers, we make use of some interfaces. | |
| 9 | |
| 10 /// Matchers build up their error messages by appending to | |
| 11 /// Description objects. This interface is implemented by | |
| 12 /// StringDescription. This interface is unlikely to need | |
| 13 /// other implementations, but could be useful to replace in | |
| 14 /// some cases - e.g. language conversion. | |
| 15 abstract class Description { | |
| 16 int get length; | |
| 17 | |
| 18 /// Change the value of the description. | |
| 19 Description replace(String text); | |
| 20 | |
| 21 /// This is used to add arbitrary text to the description. | |
| 22 Description add(String text); | |
| 23 | |
| 24 /// This is used to add a meaningful description of a value. | |
| 25 Description addDescriptionOf(value); | |
| 26 | |
| 27 /// This is used to add a description of an [Iterable] [list], | |
| 28 /// with appropriate [start] and [end] markers and inter-element [separator]. | |
| 29 Description addAll(String start, String separator, String end, Iterable list); | |
| 30 } | |
| 31 | |
| 32 /// [expect] Matchers must implement/extend the Matcher class. | |
| 33 /// The base Matcher class has a generic implementation of [describeMismatch] | |
| 34 /// so this does not need to be provided unless a more clear description is | |
| 35 /// required. The other two methods ([matches] and [describe]) | |
| 36 /// must always be provided as they are highly matcher-specific. | |
| 37 abstract class Matcher { | |
| 38 const Matcher(); | |
| 39 | |
| 40 /// This does the matching of the actual vs expected values. | |
| 41 /// [item] is the actual value. [matchState] can be supplied | |
| 42 /// and may be used to add details about the mismatch that are too | |
| 43 /// costly to determine in [describeMismatch]. | |
| 44 bool matches(item, Map matchState); | |
| 45 | |
| 46 /// This builds a textual description of the matcher. | |
| 47 Description describe(Description description); | |
| 48 | |
| 49 /// This builds a textual description of a specific mismatch. [item] | |
| 50 /// is the value that was tested by [matches]; [matchState] is | |
| 51 /// the [Map] that was passed to and supplemented by [matches] | |
| 52 /// with additional information about the mismatch, and [mismatchDescription] | |
| 53 /// is the [Description] that is being built to decribe the mismatch. | |
| 54 /// A few matchers make use of the [verbose] flag to provide detailed | |
| 55 /// information that is not typically included but can be of help in | |
| 56 /// diagnosing failures, such as stack traces. | |
| 57 Description describeMismatch(item, Description mismatchDescription, | |
| 58 Map matchState, bool verbose) => mismatchDescription; | |
| 59 } | |
| OLD | NEW |