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 : /// Matchers build up their error messages by appending to Description objects. 6 : /// 7 : /// This interface is implemented by StringDescription. 8 : /// 9 : /// This interface is unlikely to need other implementations, but could be 10 : /// useful to replace in some cases - e.g. language conversion. 11 : abstract class Description { 12 : int get length; 13 : 14 : /// Change the value of the description. 15 : Description replace(String text); 16 : 17 : /// This is used to add arbitrary text to the description. 18 : Description add(String text); 19 : 20 : /// This is used to add a meaningful description of a value. 21 : Description addDescriptionOf(Object? value); 22 : 23 : /// This is used to add a description of an [Iterable] [list], 24 : /// with appropriate [start] and [end] markers and inter-element [separator]. 25 : Description addAll(String start, String separator, String end, Iterable list); 26 : } 27 : 28 : /// The base class for all matchers. 29 : /// 30 : /// [matches] and [describe] must be implemented by subclasses. 31 : /// 32 : /// Subclasses can override [describeMismatch] if a more specific description is 33 : /// required when the matcher fails. 34 : abstract class Matcher { 35 78 : const Matcher(); 36 : 37 : /// Does the matching of the actual vs expected values. 38 : /// 39 : /// [item] is the actual value. [matchState] can be supplied 40 : /// and may be used to add details about the mismatch that are too 41 : /// costly to determine in [describeMismatch]. 42 : bool matches(dynamic item, Map matchState); 43 : 44 : /// Builds a textual description of the matcher. 45 : Description describe(Description description); 46 : 47 : /// Builds a textual description of a specific mismatch. 48 : /// 49 : /// [item] 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 : /// 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 0 : Description describeMismatch(dynamic item, Description mismatchDescription, 58 : Map matchState, bool verbose) => 59 : mismatchDescription; 60 : }