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 /** | |
6 * This is the main assertion function. It asserts that [actual] | |
7 * matches the [matcher]. [matcher] is optional and defaults to isTrue, | |
8 * so expect can be used with a single predicate argument. [reason] | |
9 * is optional and is typically not supplied if a reasonable matcher is | |
10 * explicitly provided, as a reason can be generated from the matcher. | |
11 * If [reason] is included it is appended to the reason generated | |
12 * by the matcher. | |
13 * | |
14 * [matcher] can be a value in which case it will be wrapped in an | |
15 * [equals] matcher. | |
16 * | |
17 * If the assertion fails, then the default behavior is to throw an | |
18 * [ExpectException], but this behavior can be changed by calling | |
19 * [configureExpectFailureHandler] and providing an alternative handler that | |
20 * implements the [IFailureHandler] interface. It is also possible to | |
21 * pass a [failureHandler] to [expect] as a final parameter for fine- | |
22 * grained control. | |
23 * | |
24 * In some cases extra diagnostic info can be produced on failure (for | |
25 * example, stack traces on mismatched exceptions). To enable these, | |
26 * [verbose] should be specified as true; | |
27 * | |
28 * expect() is a 3rd generation assertion mechanism, drawing | |
29 * inspiration from [Hamcrest] and Ladislav Thon's [dart-matchers] | |
30 * library. | |
31 * | |
32 * See [Hamcrest] http://en.wikipedia.org/wiki/Hamcrest | |
33 * [Hamcrest] http://code.google.com/p/hamcrest/ | |
34 * [dart-matchers] https://github.com/Ladicek/dart-matchers | |
35 */ | |
36 void expect(actual, [matcher = isTrue, String reason = null, | |
37 FailureHandler failureHandler = null, | |
38 bool verbose = false]) { | |
39 matcher = wrapMatcher(matcher); | |
40 bool doesMatch; | |
41 var matchState = new MatchState(); | |
42 try { | |
43 doesMatch = matcher.matches(actual, matchState); | |
44 } catch (e, trace) { | |
45 doesMatch = false; | |
46 if (reason == null) { | |
47 reason = '${(e is String) ? e : e.toString()} at $trace'; | |
48 } | |
49 } | |
50 if (!doesMatch) { | |
51 if (failureHandler == null) { | |
52 failureHandler = getOrCreateExpectFailureHandler(); | |
53 } | |
54 failureHandler.failMatch(actual, matcher, reason, matchState, verbose); | |
55 } | |
56 } | |
57 | |
58 /** | |
59 * Takes an argument and returns an equivalent matcher. | |
60 * If the argument is already a matcher this does nothing, | |
61 * else if the argument is a function, it generates a predicate | |
62 * function matcher, else it generates an equals matcher. | |
63 */ | |
64 Matcher wrapMatcher(x) { | |
65 if (x is Matcher) { | |
66 return x; | |
67 } else if (x is Function) { | |
68 return predicate(x); | |
69 } else { | |
70 return equals(x); | |
71 } | |
72 } | |
73 | |
74 // The handler for failed asserts. | |
75 FailureHandler _assertFailureHandler = null; | |
76 | |
77 // The default failure handler that throws ExpectExceptions. | |
78 class DefaultFailureHandler implements FailureHandler { | |
79 DefaultFailureHandler() { | |
80 if (_assertErrorFormatter == null) { | |
81 _assertErrorFormatter = _defaultErrorFormatter; | |
82 } | |
83 } | |
84 void fail(String reason) { | |
85 throw new ExpectException(reason); | |
86 } | |
87 void failMatch(actual, Matcher matcher, String reason, | |
88 MatchState matchState, bool verbose) { | |
89 fail(_assertErrorFormatter(actual, matcher, reason, matchState, verbose)); | |
90 } | |
91 } | |
92 | |
93 /** | |
94 * Changes or resets to the default the failure handler for expect() | |
95 * [handler] is a reference to the new handler; if this is omitted | |
96 * or null then the failure handler is reset to the default, which | |
97 * throws [ExpectExceptions] on [expect] assertion failures. | |
98 */ | |
99 void configureExpectFailureHandler([FailureHandler handler = null]) { | |
100 if (handler == null) { | |
101 handler = new DefaultFailureHandler(); | |
102 } | |
103 _assertFailureHandler = handler; | |
104 } | |
105 | |
106 FailureHandler getOrCreateExpectFailureHandler() { | |
107 if (_assertFailureHandler == null) { | |
108 configureExpectFailureHandler(); | |
109 } | |
110 return _assertFailureHandler; | |
111 } | |
112 | |
113 // The error message formatter for failed asserts. | |
114 ErrorFormatter _assertErrorFormatter = null; | |
115 | |
116 // The default error formatter implementation. | |
117 String _defaultErrorFormatter(actual, Matcher matcher, String reason, | |
118 MatchState matchState, bool verbose) { | |
119 var description = new StringDescription(); | |
120 description.add('Expected: ').addDescriptionOf(matcher). | |
121 add('\n but: '); | |
122 matcher.describeMismatch(actual, description, matchState, verbose); | |
123 description.add('.\n'); | |
124 if (verbose && actual is Iterable) { | |
125 description.add('Actual: ').addDescriptionOf(actual).add('\n'); | |
126 } | |
127 if (reason != null) { | |
128 description.add(reason).add('\n'); | |
129 } | |
130 return description.toString(); | |
131 } | |
132 | |
133 /** | |
134 * Changes or resets to default the failure message formatter for expect(). | |
135 * [formatter] is a reference to the new formatter; if this is omitted or | |
136 * null then the failure formatter is reset to the default. The new | |
137 * formatter is returned; this allows custom expect handlers to easily | |
138 * get a reference to the default formatter. | |
139 */ | |
140 ErrorFormatter configureExpectFormatter([ErrorFormatter formatter = null]) { | |
141 if (formatter == null) { | |
142 formatter = _defaultErrorFormatter; | |
143 } | |
144 return _assertErrorFormatter = formatter; | |
145 } | |
146 | |
OLD | NEW |