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