| OLD | NEW |
| 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 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 | 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. | 3 // BSD-style license that can be found in the LICENSE file. |
| 4 | 4 |
| 5 /** | 5 /// `unittest.mock` has been moved to the `matcher` package. |
| 6 * A simple mocking/spy library. | 6 /// |
| 7 * | 7 /// Add `matcher` to your `pubspec.yaml` file and import it via |
| 8 * ## Installing ## | 8 /// `import 'package:matcher/mirror_matchers.dart';` |
| 9 * | 9 @deprecated |
| 10 * Use [pub][] to install this package. Add the following to your `pubspec.yaml` | |
| 11 * file. | |
| 12 * | |
| 13 * dependencies: | |
| 14 * unittest: any | |
| 15 * | |
| 16 * Then run `pub install`. | |
| 17 * | |
| 18 * Import this into your Dart code with: | |
| 19 * | |
| 20 * import 'package:unittest/mock.dart'; | |
| 21 * | |
| 22 * For more information, see the [unittest package on pub.dartlang.org] | |
| 23 * (http://pub.dartlang.org/packages/unittest). | |
| 24 * | |
| 25 * ## Using ## | |
| 26 * | |
| 27 * To create a mock objects for some class T, create a new class using: | |
| 28 * | |
| 29 * class MockT extends Mock implements T {}; | |
| 30 * | |
| 31 * Then specify the [Behavior] of the Mock for different methods using | |
| 32 * [when] (to select the method and parameters) and then the [Action]s | |
| 33 * for the [Behavior] by calling [thenReturn], [alwaysReturn], [thenThrow], | |
| 34 * [alwaysThrow], [thenCall] or [alwaysCall]. | |
| 35 * | |
| 36 * [thenReturn], [thenThrow] and [thenCall] are one-shot so you would | |
| 37 * typically call these more than once to specify a sequence of actions; | |
| 38 * this can be done with chained calls, e.g.: | |
| 39 * | |
| 40 * m.when(callsTo('foo')). | |
| 41 * thenReturn(0).thenReturn(1).thenReturn(2); | |
| 42 * | |
| 43 * [thenCall] and [alwaysCall] allow you to proxy mocked methods, chaining | |
| 44 * to some other implementation. This provides a way to implement 'spies'. | |
| 45 * | |
| 46 * For getters and setters, use "get foo" and "set foo"-style arguments | |
| 47 * to [callsTo]. | |
| 48 * | |
| 49 * You can disable logging for a particular [Behavior] easily: | |
| 50 * | |
| 51 * m.when(callsTo('bar')).logging = false; | |
| 52 * | |
| 53 * You can then use the mock object. Once you are done, to verify the | |
| 54 * behavior, use [getLogs] to extract a relevant subset of method call | |
| 55 * logs and apply [Matchers] to these through calling [verify]. | |
| 56 * | |
| 57 * A Mock can be given a name when constructed. In this case instead of | |
| 58 * keeping its own log, it uses a shared log. This can be useful to get an | |
| 59 * audit trail of interleaved behavior. It is the responsibility of the user | |
| 60 * to ensure that mock names, if used, are unique. | |
| 61 * | |
| 62 * Limitations: | |
| 63 * | |
| 64 * * only positional parameters are supported (up to 10); | |
| 65 * * to mock getters you will need to include parentheses in the call | |
| 66 * (e.g. m.length() will work but not m.length). | |
| 67 * | |
| 68 * Here is a simple example: | |
| 69 * | |
| 70 * class MockList extends Mock implements List {}; | |
| 71 * | |
| 72 * List m = new MockList(); | |
| 73 * m.when(callsTo('add', anything)).alwaysReturn(0); | |
| 74 * | |
| 75 * m.add('foo'); | |
| 76 * m.add('bar'); | |
| 77 * | |
| 78 * getLogs(m, callsTo('add', anything)).verify(happenedExactly(2)); | |
| 79 * getLogs(m, callsTo('add', 'foo')).verify(happenedOnce); | |
| 80 * getLogs(m, callsTo('add', 'isNull)).verify(neverHappened); | |
| 81 * | |
| 82 * Note that we don't need to provide argument matchers for all arguments, | |
| 83 * but we do need to provide arguments for all matchers. So this is allowed: | |
| 84 * | |
| 85 * m.when(callsTo('add')).alwaysReturn(0); | |
| 86 * m.add(1, 2); | |
| 87 * | |
| 88 * But this is not allowed and will throw an exception: | |
| 89 * | |
| 90 * m.when(callsTo('add', anything, anything)).alwaysReturn(0); | |
| 91 * m.add(1); | |
| 92 * | |
| 93 * Here is a way to implement a 'spy', which is where we log the call | |
| 94 * but then hand it off to some other function, which is the same | |
| 95 * method in a real instance of the class being mocked: | |
| 96 * | |
| 97 * class Foo { | |
| 98 * bar(a, b, c) => a + b + c; | |
| 99 * } | |
| 100 * | |
| 101 * class MockFoo extends Mock implements Foo { | |
| 102 * Foo real; | |
| 103 * MockFoo() { | |
| 104 * real = new Foo(); | |
| 105 * this.when(callsTo('bar')).alwaysCall(real.bar); | |
| 106 * } | |
| 107 * } | |
| 108 * | |
| 109 * However, there is an even easier way, by calling [Mock.spy], e.g.: | |
| 110 * | |
| 111 * var foo = new Foo(); | |
| 112 * var spy = new Mock.spy(foo); | |
| 113 * print(spy.bar(1, 2, 3)); | |
| 114 * | |
| 115 * Spys created with Mock.spy do not have user-defined behavior; | |
| 116 * they are simply proxies, and thus will throw an exception if | |
| 117 * you call [when]. They capture all calls in the log, so you can | |
| 118 * do assertions on their history, such as: | |
| 119 * | |
| 120 * spy.getLogs(callsTo('bar')).verify(happenedOnce); | |
| 121 * | |
| 122 * [pub]: http://pub.dartlang.org | |
| 123 */ | |
| 124 | |
| 125 library unittest.mock; | 10 library unittest.mock; |
| 126 | 11 |
| 127 import 'dart:mirrors'; | 12 export 'package:mock/mock.dart'; |
| 128 import 'dart:collection' show LinkedHashMap; | |
| 129 | |
| 130 import 'matcher.dart'; | |
| 131 | |
| 132 /** | |
| 133 * The error formatter for mocking is a bit different from the default one | |
| 134 * for unit testing; instead of the third argument being a 'reason' | |
| 135 * it is instead a [signature] describing the method signature filter | |
| 136 * that was used to select the logs that were verified. | |
| 137 */ | |
| 138 String _mockingErrorFormatter(actual, Matcher matcher, String signature, | |
| 139 Map matchState, bool verbose) { | |
| 140 var description = new StringDescription(); | |
| 141 description.add('Expected ${signature} ').addDescriptionOf(matcher). | |
| 142 add('\n but: '); | |
| 143 matcher.describeMismatch(actual, description, matchState, verbose).add('.'); | |
| 144 return description.toString(); | |
| 145 } | |
| 146 | |
| 147 /** | |
| 148 * The failure handler for the [expect()] calls that occur in [verify()] | |
| 149 * methods in the mock objects. This calls the real failure handler used | |
| 150 * by the unit test library after formatting the error message with | |
| 151 * the custom formatter. | |
| 152 */ | |
| 153 class _MockFailureHandler implements FailureHandler { | |
| 154 FailureHandler proxy; | |
| 155 _MockFailureHandler(this.proxy); | |
| 156 void fail(String reason) { | |
| 157 proxy.fail(reason); | |
| 158 } | |
| 159 void failMatch(actual, Matcher matcher, String reason, | |
| 160 Map matchState, bool verbose) { | |
| 161 proxy.fail(_mockingErrorFormatter(actual, matcher, reason, | |
| 162 matchState, verbose)); | |
| 163 } | |
| 164 } | |
| 165 | |
| 166 _MockFailureHandler _mockFailureHandler = null; | |
| 167 | |
| 168 /** Sentinel value for representing no argument. */ | |
| 169 class _Sentinel { | |
| 170 const _Sentinel(); | |
| 171 } | |
| 172 const _noArg = const _Sentinel(); | |
| 173 | |
| 174 /** The ways in which a call to a mock method can be handled. */ | |
| 175 class Action { | |
| 176 /** Do nothing (void method) */ | |
| 177 static const IGNORE = const Action._('IGNORE'); | |
| 178 | |
| 179 /** Return a supplied value. */ | |
| 180 static const RETURN = const Action._('RETURN'); | |
| 181 | |
| 182 /** Throw a supplied value. */ | |
| 183 static const THROW = const Action._('THROW'); | |
| 184 | |
| 185 /** Call a supplied function. */ | |
| 186 static const PROXY = const Action._('PROXY'); | |
| 187 | |
| 188 const Action._(this.name); | |
| 189 | |
| 190 final String name; | |
| 191 | |
| 192 String toString() => 'Action: $name'; | |
| 193 } | |
| 194 | |
| 195 /** | |
| 196 * The behavior of a method call in the mock library is specified | |
| 197 * with [Responder]s. A [Responder] has a [value] to throw | |
| 198 * or return (depending on the type of [action]), | |
| 199 * and can either be one-shot, multi-shot, or infinitely repeating, | |
| 200 * depending on the value of [count (1, greater than 1, or 0 respectively). | |
| 201 */ | |
| 202 class Responder { | |
| 203 final Object value; | |
| 204 final Action action; | |
| 205 int count; | |
| 206 Responder(this.value, [this.count = 1, this.action = Action.RETURN]); | |
| 207 } | |
| 208 | |
| 209 /** | |
| 210 * A [CallMatcher] is a special matcher used to match method calls (i.e. | |
| 211 * a method name and set of arguments). It is not a [Matcher] like the | |
| 212 * unit test [Matcher], but instead represents a method name and a | |
| 213 * collection of [Matcher]s, one per argument, that will be applied | |
| 214 * to the parameters to decide if the method call is a match. | |
| 215 */ | |
| 216 class CallMatcher { | |
| 217 Matcher nameFilter; | |
| 218 List<Matcher> argMatchers; | |
| 219 | |
| 220 /** | |
| 221 * Constructor for [CallMatcher]. [name] can be null to | |
| 222 * match anything, or a literal [String], a predicate [Function], | |
| 223 * or a [Matcher]. The various arguments can be scalar values or | |
| 224 * [Matcher]s. | |
| 225 */ | |
| 226 CallMatcher([name, | |
| 227 arg0 = _noArg, | |
| 228 arg1 = _noArg, | |
| 229 arg2 = _noArg, | |
| 230 arg3 = _noArg, | |
| 231 arg4 = _noArg, | |
| 232 arg5 = _noArg, | |
| 233 arg6 = _noArg, | |
| 234 arg7 = _noArg, | |
| 235 arg8 = _noArg, | |
| 236 arg9 = _noArg]) { | |
| 237 if (name == null) { | |
| 238 nameFilter = anything; | |
| 239 } else { | |
| 240 nameFilter = wrapMatcher(name); | |
| 241 } | |
| 242 argMatchers = new List<Matcher>(); | |
| 243 if (identical(arg0, _noArg)) return; | |
| 244 argMatchers.add(wrapMatcher(arg0)); | |
| 245 if (identical(arg1, _noArg)) return; | |
| 246 argMatchers.add(wrapMatcher(arg1)); | |
| 247 if (identical(arg2, _noArg)) return; | |
| 248 argMatchers.add(wrapMatcher(arg2)); | |
| 249 if (identical(arg3, _noArg)) return; | |
| 250 argMatchers.add(wrapMatcher(arg3)); | |
| 251 if (identical(arg4, _noArg)) return; | |
| 252 argMatchers.add(wrapMatcher(arg4)); | |
| 253 if (identical(arg5, _noArg)) return; | |
| 254 argMatchers.add(wrapMatcher(arg5)); | |
| 255 if (identical(arg6, _noArg)) return; | |
| 256 argMatchers.add(wrapMatcher(arg6)); | |
| 257 if (identical(arg7, _noArg)) return; | |
| 258 argMatchers.add(wrapMatcher(arg7)); | |
| 259 if (identical(arg8, _noArg)) return; | |
| 260 argMatchers.add(wrapMatcher(arg8)); | |
| 261 if (identical(arg9, _noArg)) return; | |
| 262 argMatchers.add(wrapMatcher(arg9)); | |
| 263 } | |
| 264 | |
| 265 /** | |
| 266 * We keep our behavior specifications in a Map, which is keyed | |
| 267 * by the [CallMatcher]. To make the keys unique and to get a | |
| 268 * descriptive value for the [CallMatcher] we have this override | |
| 269 * of [toString()]. | |
| 270 */ | |
| 271 String toString() { | |
| 272 Description d = new StringDescription(); | |
| 273 d.addDescriptionOf(nameFilter); | |
| 274 // If the nameFilter was a simple string - i.e. just a method name - | |
| 275 // strip the quotes to make this more natural in appearance. | |
| 276 if (d.toString()[0] == "'") { | |
| 277 d.replace(d.toString().substring(1, d.toString().length - 1)); | |
| 278 } | |
| 279 d.add('('); | |
| 280 for (var i = 0; i < argMatchers.length; i++) { | |
| 281 if (i > 0) d.add(', '); | |
| 282 d.addDescriptionOf(argMatchers[i]); | |
| 283 } | |
| 284 d.add(')'); | |
| 285 return d.toString(); | |
| 286 } | |
| 287 | |
| 288 /** | |
| 289 * Given a [method] name and list of [arguments], return true | |
| 290 * if it matches this [CallMatcher. | |
| 291 */ | |
| 292 bool matches(String method, List arguments) { | |
| 293 var matchState = {}; | |
| 294 if (!nameFilter.matches(method, matchState)) { | |
| 295 return false; | |
| 296 } | |
| 297 var numArgs = (arguments == null) ? 0 : arguments.length; | |
| 298 if (numArgs < argMatchers.length) { | |
| 299 throw new Exception("Less arguments than matchers for $method."); | |
| 300 } | |
| 301 for (var i = 0; i < argMatchers.length; i++) { | |
| 302 if (!argMatchers[i].matches(arguments[i], matchState)) { | |
| 303 return false; | |
| 304 } | |
| 305 } | |
| 306 return true; | |
| 307 } | |
| 308 } | |
| 309 | |
| 310 /** | |
| 311 * Returns a [CallMatcher] for the specified signature. [method] can be | |
| 312 * null to match anything, or a literal [String], a predicate [Function], | |
| 313 * or a [Matcher]. The various arguments can be scalar values or [Matcher]s. | |
| 314 * To match getters and setters, use "get " and "set " prefixes on the names. | |
| 315 * For example, for a property "foo", you could use "get foo" and "set foo" | |
| 316 * as literal string arguments to callsTo to match the getter and setter | |
| 317 * of "foo". | |
| 318 */ | |
| 319 CallMatcher callsTo([method, | |
| 320 arg0 = _noArg, | |
| 321 arg1 = _noArg, | |
| 322 arg2 = _noArg, | |
| 323 arg3 = _noArg, | |
| 324 arg4 = _noArg, | |
| 325 arg5 = _noArg, | |
| 326 arg6 = _noArg, | |
| 327 arg7 = _noArg, | |
| 328 arg8 = _noArg, | |
| 329 arg9 = _noArg]) { | |
| 330 return new CallMatcher(method, arg0, arg1, arg2, arg3, arg4, | |
| 331 arg5, arg6, arg7, arg8, arg9); | |
| 332 } | |
| 333 | |
| 334 /** | |
| 335 * A [Behavior] represents how a [Mock] will respond to one particular | |
| 336 * type of method call. | |
| 337 */ | |
| 338 class Behavior { | |
| 339 CallMatcher matcher; // The method call matcher. | |
| 340 List<Responder> actions; // The values to return/throw or proxies to call. | |
| 341 bool logging = true; | |
| 342 | |
| 343 Behavior (this.matcher) { | |
| 344 actions = new List<Responder>(); | |
| 345 } | |
| 346 | |
| 347 /** | |
| 348 * Adds a [Responder] that returns a [value] for [count] calls | |
| 349 * (1 by default). | |
| 350 */ | |
| 351 Behavior thenReturn(value, [count = 1]) { | |
| 352 actions.add(new Responder(value, count, Action.RETURN)); | |
| 353 return this; // For chaining calls. | |
| 354 } | |
| 355 | |
| 356 /** Adds a [Responder] that repeatedly returns a [value]. */ | |
| 357 Behavior alwaysReturn(value) { | |
| 358 return thenReturn(value, 0); | |
| 359 } | |
| 360 | |
| 361 /** | |
| 362 * Adds a [Responder] that throws [value] [count] | |
| 363 * times (1 by default). | |
| 364 */ | |
| 365 Behavior thenThrow(value, [count = 1]) { | |
| 366 actions.add(new Responder(value, count, Action.THROW)); | |
| 367 return this; // For chaining calls. | |
| 368 } | |
| 369 | |
| 370 /** Adds a [Responder] that throws [value] endlessly. */ | |
| 371 Behavior alwaysThrow(value) { | |
| 372 return thenThrow(value, 0); | |
| 373 } | |
| 374 | |
| 375 /** | |
| 376 * [thenCall] creates a proxy Responder, that is called [count] | |
| 377 * times (1 by default; 0 is used for unlimited calls, and is | |
| 378 * exposed as [alwaysCall]). [value] is the function that will | |
| 379 * be called with the same arguments that were passed to the | |
| 380 * mock. Proxies can be used to wrap real objects or to define | |
| 381 * more complex return/throw behavior. You could even (if you | |
| 382 * wanted) use proxies to emulate the behavior of thenReturn; | |
| 383 * e.g.: | |
| 384 * | |
| 385 * m.when(callsTo('foo')).thenReturn(0) | |
| 386 * | |
| 387 * is equivalent to: | |
| 388 * | |
| 389 * m.when(callsTo('foo')).thenCall(() => 0) | |
| 390 */ | |
| 391 Behavior thenCall(value, [count = 1]) { | |
| 392 actions.add(new Responder(value, count, Action.PROXY)); | |
| 393 return this; // For chaining calls. | |
| 394 } | |
| 395 | |
| 396 /** Creates a repeating proxy call. */ | |
| 397 Behavior alwaysCall(value) { | |
| 398 return thenCall(value, 0); | |
| 399 } | |
| 400 | |
| 401 /** Returns true if a method call matches the [Behavior]. */ | |
| 402 bool matches(String method, List args) => matcher.matches(method, args); | |
| 403 | |
| 404 /** Returns the [matcher]'s representation. */ | |
| 405 String toString() => matcher.toString(); | |
| 406 } | |
| 407 | |
| 408 /** | |
| 409 * Every call to a [Mock] object method is logged. The logs are | |
| 410 * kept in instances of [LogEntry]. | |
| 411 */ | |
| 412 class LogEntry { | |
| 413 /** The time of the event. */ | |
| 414 DateTime time; | |
| 415 | |
| 416 /** The mock object name, if any. */ | |
| 417 final String mockName; | |
| 418 | |
| 419 /** The method name. */ | |
| 420 final String methodName; | |
| 421 | |
| 422 /** The parameters. */ | |
| 423 final List args; | |
| 424 | |
| 425 /** The behavior that resulted. */ | |
| 426 final Action action; | |
| 427 | |
| 428 /** The value that was returned (if no throw). */ | |
| 429 final value; | |
| 430 | |
| 431 LogEntry(this.mockName, this.methodName, | |
| 432 this.args, this.action, [this.value]) { | |
| 433 time = new DateTime.now(); | |
| 434 } | |
| 435 | |
| 436 String _pad2(int val) => (val >= 10 ? '$val' : '0$val'); | |
| 437 | |
| 438 String toString([DateTime baseTime]) { | |
| 439 Description d = new StringDescription(); | |
| 440 if (baseTime == null) { | |
| 441 // Show absolute time. | |
| 442 d.add('${time.hour}:${_pad2(time.minute)}:' | |
| 443 '${_pad2(time.second)}.${time.millisecond}> '); | |
| 444 } else { | |
| 445 // Show relative time. | |
| 446 int delta = time.millisecondsSinceEpoch - baseTime.millisecondsSinceEpoch; | |
| 447 int secs = delta ~/ 1000; | |
| 448 int msecs = delta % 1000; | |
| 449 d.add('$secs.$msecs> '); | |
| 450 } | |
| 451 d.add('${_qualifiedName(mockName, methodName)}('); | |
| 452 if (args != null) { | |
| 453 for (var i = 0; i < args.length; i++) { | |
| 454 if (i != 0) d.add(', '); | |
| 455 d.addDescriptionOf(args[i]); | |
| 456 } | |
| 457 } | |
| 458 d.add(') ${action == Action.THROW ? "threw" : "returned"} '); | |
| 459 d.addDescriptionOf(value); | |
| 460 return d.toString(); | |
| 461 } | |
| 462 } | |
| 463 | |
| 464 /** Utility function for optionally qualified method names */ | |
| 465 String _qualifiedName(owner, String method) { | |
| 466 if (owner == null || identical(owner, anything)) { | |
| 467 return method; | |
| 468 } else if (owner is Matcher) { | |
| 469 Description d = new StringDescription(); | |
| 470 d.addDescriptionOf(owner); | |
| 471 d.add('.'); | |
| 472 d.add(method); | |
| 473 return d.toString(); | |
| 474 } else { | |
| 475 return '$owner.$method'; | |
| 476 } | |
| 477 } | |
| 478 | |
| 479 /** | |
| 480 * [StepValidator]s are used by [stepwiseValidate] in [LogEntryList], which | |
| 481 * iterates through the list and call the [StepValidator] function with the | |
| 482 * log [List] and position. The [StepValidator] should return the number of | |
| 483 * positions to advance upon success, or zero upon failure. When zero is | |
| 484 * returned an error is reported. | |
| 485 */ | |
| 486 typedef int StepValidator(List<LogEntry> logs, int pos); | |
| 487 | |
| 488 /** | |
| 489 * We do verification on a list of [LogEntry]s. To allow chaining | |
| 490 * of calls to verify, we encapsulate such a list in the [LogEntryList] | |
| 491 * class. | |
| 492 */ | |
| 493 class LogEntryList { | |
| 494 String filter; | |
| 495 List<LogEntry> logs; | |
| 496 LogEntryList([this.filter]) { | |
| 497 logs = new List<LogEntry>(); | |
| 498 } | |
| 499 | |
| 500 /** Add a [LogEntry] to the log. */ | |
| 501 add(LogEntry entry) => logs.add(entry); | |
| 502 | |
| 503 /** Get the first entry, or null if no entries. */ | |
| 504 get first => (logs == null || logs.length == 0) ? null : logs[0]; | |
| 505 | |
| 506 /** Get the last entry, or null if no entries. */ | |
| 507 get last => (logs == null || logs.length == 0) ? null : logs.last; | |
| 508 | |
| 509 /** Creates a LogEntry predicate function from the argument. */ | |
| 510 Function _makePredicate(arg) { | |
| 511 if (arg == null) { | |
| 512 return (e) => true; | |
| 513 } else if (arg is CallMatcher) { | |
| 514 return (e) => arg.matches(e.methodName, e.args); | |
| 515 } else if (arg is Function) { | |
| 516 return arg; | |
| 517 } else { | |
| 518 throw new Exception("Invalid argument to _makePredicate."); | |
| 519 } | |
| 520 } | |
| 521 | |
| 522 /** | |
| 523 * Create a new [LogEntryList] consisting of [LogEntry]s from | |
| 524 * this list that match the specified [mockNameFilter] and [logFilter]. | |
| 525 * [mockNameFilter] can be null, a [String], a predicate [Function], | |
| 526 * or a [Matcher]. If [mockNameFilter] is null, this is the same as | |
| 527 * [anything]. | |
| 528 * If [logFilter] is null, all entries in the log will be returned. | |
| 529 * Otherwise [logFilter] should be a [CallMatcher] or predicate function | |
| 530 * that takes a [LogEntry] and returns a bool. | |
| 531 * If [destructive] is true, the log entries are removed from the | |
| 532 * original list. | |
| 533 */ | |
| 534 LogEntryList getMatches([mockNameFilter, | |
| 535 logFilter, | |
| 536 Matcher actionMatcher, | |
| 537 bool destructive = false]) { | |
| 538 if (mockNameFilter == null) { | |
| 539 mockNameFilter = anything; | |
| 540 } else { | |
| 541 mockNameFilter = wrapMatcher(mockNameFilter); | |
| 542 } | |
| 543 Function entryFilter = _makePredicate(logFilter); | |
| 544 String filterName = _qualifiedName(mockNameFilter, logFilter.toString()); | |
| 545 LogEntryList rtn = new LogEntryList(filterName); | |
| 546 var matchState = {}; | |
| 547 for (var i = 0; i < logs.length; i++) { | |
| 548 LogEntry entry = logs[i]; | |
| 549 if (mockNameFilter.matches(entry.mockName, matchState) && | |
| 550 entryFilter(entry)) { | |
| 551 if (actionMatcher == null || | |
| 552 actionMatcher.matches(entry, matchState)) { | |
| 553 rtn.add(entry); | |
| 554 if (destructive) { | |
| 555 int startIndex = i--; | |
| 556 logs.removeRange(startIndex, startIndex + 1); | |
| 557 } | |
| 558 } | |
| 559 } | |
| 560 } | |
| 561 return rtn; | |
| 562 } | |
| 563 | |
| 564 /** Apply a unit test [Matcher] to the [LogEntryList]. */ | |
| 565 LogEntryList verify(Matcher matcher) { | |
| 566 if (_mockFailureHandler == null) { | |
| 567 _mockFailureHandler = | |
| 568 new _MockFailureHandler(getOrCreateExpectFailureHandler()); | |
| 569 } | |
| 570 expect(logs, matcher, reason:filter, failureHandler: _mockFailureHandler); | |
| 571 return this; | |
| 572 } | |
| 573 | |
| 574 /** | |
| 575 * Iterate through the list and call the [validator] function with the | |
| 576 * log [List] and position. The [validator] should return the number of | |
| 577 * positions to advance upon success, or zero upon failure. When zero is | |
| 578 * returned an error is reported. [reason] can be used to provide a | |
| 579 * more descriptive failure message. If a failure occurred false will be | |
| 580 * returned (unless the failure handler itself threw an exception); | |
| 581 * otherwise true is returned. | |
| 582 * The use case here is to perform more complex validations; for example | |
| 583 * we may want to assert that the return value from some function is | |
| 584 * later used as a parameter to a following function. If we filter the logs | |
| 585 * to include just these two functions we can write a simple validator to | |
| 586 * do this check. | |
| 587 */ | |
| 588 bool stepwiseValidate(StepValidator validator, [String reason = '']) { | |
| 589 if (_mockFailureHandler == null) { | |
| 590 _mockFailureHandler = | |
| 591 new _MockFailureHandler(getOrCreateExpectFailureHandler()); | |
| 592 } | |
| 593 var i = 0; | |
| 594 while (i < logs.length) { | |
| 595 var n = validator(logs, i); | |
| 596 if (n == 0) { | |
| 597 if (reason.length > 0) { | |
| 598 reason = ': $reason'; | |
| 599 } | |
| 600 _mockFailureHandler.fail("Stepwise validation failed at $filter " | |
| 601 "position $i$reason"); | |
| 602 return false; | |
| 603 } else { | |
| 604 i += n; | |
| 605 } | |
| 606 } | |
| 607 return true; | |
| 608 } | |
| 609 | |
| 610 /** | |
| 611 * Turn the logs into human-readable text. If [baseTime] is specified | |
| 612 * then each entry is prefixed with the offset from that time in | |
| 613 * milliseconds; otherwise the time of day is used. | |
| 614 */ | |
| 615 String toString([DateTime baseTime]) { | |
| 616 String s = ''; | |
| 617 for (var e in logs) { | |
| 618 s = '$s${e.toString(baseTime)}\n'; | |
| 619 } | |
| 620 return s; | |
| 621 } | |
| 622 | |
| 623 /** | |
| 624 * Find the first log entry that satisfies [logFilter] and | |
| 625 * return its position. A search [start] position can be provided | |
| 626 * to allow for repeated searches. [logFilter] can be a [CallMatcher], | |
| 627 * or a predicate function that takes a [LogEntry] argument and returns | |
| 628 * a bool. If [logFilter] is null, it will match any [LogEntry]. | |
| 629 * If no entry is found, then [failureReturnValue] is returned. | |
| 630 * After each check the position is updated by [skip], so using | |
| 631 * [skip] of -1 allows backward searches, using a [skip] of 2 can | |
| 632 * be used to check pairs of adjacent entries, and so on. | |
| 633 */ | |
| 634 int findLogEntry(logFilter, [int start = 0, int failureReturnValue = -1, | |
| 635 skip = 1]) { | |
| 636 logFilter = _makePredicate(logFilter); | |
| 637 int pos = start; | |
| 638 while (pos >= 0 && pos < logs.length) { | |
| 639 if (logFilter(logs[pos])) { | |
| 640 return pos; | |
| 641 } | |
| 642 pos += skip; | |
| 643 } | |
| 644 return failureReturnValue; | |
| 645 } | |
| 646 | |
| 647 /** | |
| 648 * Returns log events that happened up to the first one that | |
| 649 * satisfies [logFilter]. If [inPlace] is true, then returns | |
| 650 * this LogEntryList after removing the from the first satisfier; | |
| 651 * onwards otherwise a new list is created. [description] | |
| 652 * is used to create a new name for the resulting list. | |
| 653 * [defaultPosition] is used as the index of the matching item in | |
| 654 * the case that no match is found. | |
| 655 */ | |
| 656 LogEntryList _head(logFilter, bool inPlace, | |
| 657 String description, int defaultPosition) { | |
| 658 if (filter != null) { | |
| 659 description = '$filter $description'; | |
| 660 } | |
| 661 int pos = findLogEntry(logFilter, 0, defaultPosition); | |
| 662 if (inPlace) { | |
| 663 if (pos < logs.length) { | |
| 664 logs.removeRange(pos, logs.length); | |
| 665 } | |
| 666 filter = description; | |
| 667 return this; | |
| 668 } else { | |
| 669 LogEntryList newList = new LogEntryList(description); | |
| 670 for (var i = 0; i < pos; i++) { | |
| 671 newList.logs.add(logs[i]); | |
| 672 } | |
| 673 return newList; | |
| 674 } | |
| 675 } | |
| 676 | |
| 677 /** | |
| 678 * Returns log events that happened from the first one that | |
| 679 * satisfies [logFilter]. If [inPlace] is true, then returns | |
| 680 * this LogEntryList after removing the entries up to the first | |
| 681 * satisfier; otherwise a new list is created. [description] | |
| 682 * is used to create a new name for the resulting list. | |
| 683 * [defaultPosition] is used as the index of the matching item in | |
| 684 * the case that no match is found. | |
| 685 */ | |
| 686 LogEntryList _tail(logFilter, bool inPlace, | |
| 687 String description, int defaultPosition) { | |
| 688 if (filter != null) { | |
| 689 description = '$filter $description'; | |
| 690 } | |
| 691 int pos = findLogEntry(logFilter, 0, defaultPosition); | |
| 692 if (inPlace) { | |
| 693 if (pos > 0) { | |
| 694 logs.removeRange(0, pos); | |
| 695 } | |
| 696 filter = description; | |
| 697 return this; | |
| 698 } else { | |
| 699 LogEntryList newList = new LogEntryList(description); | |
| 700 while (pos < logs.length) { | |
| 701 newList.logs.add(logs[pos++]); | |
| 702 } | |
| 703 return newList; | |
| 704 } | |
| 705 } | |
| 706 | |
| 707 /** | |
| 708 * Returns log events that happened after [when]. If [inPlace] | |
| 709 * is true, then it returns this LogEntryList after removing | |
| 710 * the entries that happened up to [when]; otherwise a new | |
| 711 * list is created. | |
| 712 */ | |
| 713 LogEntryList after(DateTime when, [bool inPlace = false]) => | |
| 714 _tail((e) => e.time.isAfter(when), inPlace, 'after $when', logs.length); | |
| 715 | |
| 716 /** | |
| 717 * Returns log events that happened from [when] onwards. If | |
| 718 * [inPlace] is true, then it returns this LogEntryList after | |
| 719 * removing the entries that happened before [when]; otherwise | |
| 720 * a new list is created. | |
| 721 */ | |
| 722 LogEntryList from(DateTime when, [bool inPlace = false]) => | |
| 723 _tail((e) => !e.time.isBefore(when), inPlace, 'from $when', logs.length); | |
| 724 | |
| 725 /** | |
| 726 * Returns log events that happened until [when]. If [inPlace] | |
| 727 * is true, then it returns this LogEntryList after removing | |
| 728 * the entries that happened after [when]; otherwise a new | |
| 729 * list is created. | |
| 730 */ | |
| 731 LogEntryList until(DateTime when, [bool inPlace = false]) => | |
| 732 _head((e) => e.time.isAfter(when), inPlace, 'until $when', logs.length); | |
| 733 | |
| 734 /** | |
| 735 * Returns log events that happened before [when]. If [inPlace] | |
| 736 * is true, then it returns this LogEntryList after removing | |
| 737 * the entries that happened from [when] onwards; otherwise a new | |
| 738 * list is created. | |
| 739 */ | |
| 740 LogEntryList before(DateTime when, [bool inPlace = false]) => | |
| 741 _head((e) => !e.time.isBefore(when), | |
| 742 inPlace, | |
| 743 'before $when', | |
| 744 logs.length); | |
| 745 | |
| 746 /** | |
| 747 * Returns log events that happened after [logEntry]'s time. | |
| 748 * If [inPlace] is true, then it returns this LogEntryList after | |
| 749 * removing the entries that happened up to [when]; otherwise a new | |
| 750 * list is created. If [logEntry] is null the current time is used. | |
| 751 */ | |
| 752 LogEntryList afterEntry(LogEntry logEntry, [bool inPlace = false]) => | |
| 753 after(logEntry == null ? new DateTime.now() : logEntry.time); | |
| 754 | |
| 755 /** | |
| 756 * Returns log events that happened from [logEntry]'s time onwards. | |
| 757 * If [inPlace] is true, then it returns this LogEntryList after | |
| 758 * removing the entries that happened before [when]; otherwise | |
| 759 * a new list is created. If [logEntry] is null the current time is used. | |
| 760 */ | |
| 761 LogEntryList fromEntry(LogEntry logEntry, [bool inPlace = false]) => | |
| 762 from(logEntry == null ? new DateTime.now() : logEntry.time); | |
| 763 | |
| 764 /** | |
| 765 * Returns log events that happened until [logEntry]'s time. If | |
| 766 * [inPlace] is true, then it returns this LogEntryList after removing | |
| 767 * the entries that happened after [when]; otherwise a new | |
| 768 * list is created. If [logEntry] is null the epoch time is used. | |
| 769 */ | |
| 770 LogEntryList untilEntry(LogEntry logEntry, [bool inPlace = false]) => | |
| 771 until(logEntry == null ? | |
| 772 new DateTime.fromMillisecondsSinceEpoch(0) : logEntry.time); | |
| 773 | |
| 774 /** | |
| 775 * Returns log events that happened before [logEntry]'s time. If | |
| 776 * [inPlace] is true, then it returns this LogEntryList after removing | |
| 777 * the entries that happened from [when] onwards; otherwise a new | |
| 778 * list is created. If [logEntry] is null the epoch time is used. | |
| 779 */ | |
| 780 LogEntryList beforeEntry(LogEntry logEntry, [bool inPlace = false]) => | |
| 781 before(logEntry == null ? | |
| 782 new DateTime.fromMillisecondsSinceEpoch(0) : logEntry.time); | |
| 783 | |
| 784 /** | |
| 785 * Returns log events that happened after the first event in [segment]. | |
| 786 * If [inPlace] is true, then it returns this LogEntryList after removing | |
| 787 * the entries that happened earlier; otherwise a new list is created. | |
| 788 */ | |
| 789 LogEntryList afterFirst(LogEntryList segment, [bool inPlace = false]) => | |
| 790 afterEntry(segment.first, inPlace); | |
| 791 | |
| 792 /** | |
| 793 * Returns log events that happened after the last event in [segment]. | |
| 794 * If [inPlace] is true, then it returns this LogEntryList after removing | |
| 795 * the entries that happened earlier; otherwise a new list is created. | |
| 796 */ | |
| 797 LogEntryList afterLast(LogEntryList segment, [bool inPlace = false]) => | |
| 798 afterEntry(segment.last, inPlace); | |
| 799 | |
| 800 /** | |
| 801 * Returns log events that happened from the time of the first event in | |
| 802 * [segment] onwards. If [inPlace] is true, then it returns this | |
| 803 * LogEntryList after removing the earlier entries; otherwise a new list | |
| 804 * is created. | |
| 805 */ | |
| 806 LogEntryList fromFirst(LogEntryList segment, [bool inPlace = false]) => | |
| 807 fromEntry(segment.first, inPlace); | |
| 808 | |
| 809 /** | |
| 810 * Returns log events that happened from the time of the last event in | |
| 811 * [segment] onwards. If [inPlace] is true, then it returns this | |
| 812 * LogEntryList after removing the earlier entries; otherwise a new list | |
| 813 * is created. | |
| 814 */ | |
| 815 LogEntryList fromLast(LogEntryList segment, [bool inPlace = false]) => | |
| 816 fromEntry(segment.last, inPlace); | |
| 817 | |
| 818 /** | |
| 819 * Returns log events that happened until the first event in [segment]. | |
| 820 * If [inPlace] is true, then it returns this LogEntryList after removing | |
| 821 * the entries that happened later; otherwise a new list is created. | |
| 822 */ | |
| 823 LogEntryList untilFirst(LogEntryList segment, [bool inPlace = false]) => | |
| 824 untilEntry(segment.first, inPlace); | |
| 825 | |
| 826 /** | |
| 827 * Returns log events that happened until the last event in [segment]. | |
| 828 * If [inPlace] is true, then it returns this LogEntryList after removing | |
| 829 * the entries that happened later; otherwise a new list is created. | |
| 830 */ | |
| 831 LogEntryList untilLast(LogEntryList segment, [bool inPlace = false]) => | |
| 832 untilEntry(segment.last, inPlace); | |
| 833 | |
| 834 /** | |
| 835 * Returns log events that happened before the first event in [segment]. | |
| 836 * If [inPlace] is true, then it returns this LogEntryList after removing | |
| 837 * the entries that happened later; otherwise a new list is created. | |
| 838 */ | |
| 839 LogEntryList beforeFirst(LogEntryList segment, [bool inPlace = false]) => | |
| 840 beforeEntry(segment.first, inPlace); | |
| 841 | |
| 842 /** | |
| 843 * Returns log events that happened before the last event in [segment]. | |
| 844 * If [inPlace] is true, then it returns this LogEntryList after removing | |
| 845 * the entries that happened later; otherwise a new list is created. | |
| 846 */ | |
| 847 LogEntryList beforeLast(LogEntryList segment, [bool inPlace = false]) => | |
| 848 beforeEntry(segment.last, inPlace); | |
| 849 | |
| 850 /** | |
| 851 * Iterate through the LogEntryList looking for matches to the entries | |
| 852 * in [keys]; for each match found the closest [distance] neighboring log | |
| 853 * entries that match [mockNameFilter] and [logFilter] will be included in | |
| 854 * the result. If [isPreceding] is true we use the neighbors that precede | |
| 855 * the matched entry; else we use the neighbors that followed. | |
| 856 * If [includeKeys] is true then the entries in [keys] that resulted in | |
| 857 * entries in the output list are themselves included in the output list. If | |
| 858 * [distance] is zero then all matches are included. | |
| 859 */ | |
| 860 LogEntryList _neighboring(bool isPreceding, | |
| 861 LogEntryList keys, | |
| 862 mockNameFilter, | |
| 863 logFilter, | |
| 864 int distance, | |
| 865 bool includeKeys) { | |
| 866 String filterName = 'Calls to ' | |
| 867 '${_qualifiedName(mockNameFilter, logFilter.toString())} ' | |
| 868 '${isPreceding?"preceding":"following"} ${keys.filter}'; | |
| 869 | |
| 870 LogEntryList rtn = new LogEntryList(filterName); | |
| 871 | |
| 872 // Deal with the trivial case. | |
| 873 if (logs.length == 0 || keys.logs.length == 0) { | |
| 874 return rtn; | |
| 875 } | |
| 876 | |
| 877 // Normalize the mockNameFilter and logFilter values. | |
| 878 if (mockNameFilter == null) { | |
| 879 mockNameFilter = anything; | |
| 880 } else { | |
| 881 mockNameFilter = wrapMatcher(mockNameFilter); | |
| 882 } | |
| 883 logFilter = _makePredicate(logFilter); | |
| 884 | |
| 885 // The scratch list is used to hold matching entries when we | |
| 886 // are doing preceding neighbors. The remainingCount is used to | |
| 887 // keep track of how many matching entries we can still add in the | |
| 888 // current segment (0 if we are doing doing following neighbors, until | |
| 889 // we get our first key match). | |
| 890 List scratch = null; | |
| 891 int remainingCount = 0; | |
| 892 if (isPreceding) { | |
| 893 scratch = new List(); | |
| 894 remainingCount = logs.length; | |
| 895 } | |
| 896 | |
| 897 var keyIterator = keys.logs.iterator; | |
| 898 keyIterator.moveNext(); | |
| 899 LogEntry keyEntry = keyIterator.current; | |
| 900 Map matchState = {}; | |
| 901 | |
| 902 for (LogEntry logEntry in logs) { | |
| 903 // If we have a log entry match, copy the saved matches from the | |
| 904 // scratch buffer into the return list, as well as the matching entry, | |
| 905 // if appropriate, and reset the scratch buffer. Continue processing | |
| 906 // from the next key entry. | |
| 907 if (keyEntry == logEntry) { | |
| 908 if (scratch != null) { | |
| 909 int numToCopy = scratch.length; | |
| 910 if (distance > 0 && distance < numToCopy) { | |
| 911 numToCopy = distance; | |
| 912 } | |
| 913 for (var i = scratch.length - numToCopy; i < scratch.length; i++) { | |
| 914 rtn.logs.add(scratch[i]); | |
| 915 } | |
| 916 scratch.clear(); | |
| 917 } else { | |
| 918 remainingCount = distance > 0 ? distance : logs.length; | |
| 919 } | |
| 920 if (includeKeys) { | |
| 921 rtn.logs.add(keyEntry); | |
| 922 } | |
| 923 if (keyIterator.moveNext()) { | |
| 924 keyEntry = keyIterator.current; | |
| 925 } else if (isPreceding) { // We're done. | |
| 926 break; | |
| 927 } | |
| 928 } else if (remainingCount > 0 && | |
| 929 mockNameFilter.matches(logEntry.mockName, matchState) && | |
| 930 logFilter(logEntry)) { | |
| 931 if (scratch != null) { | |
| 932 scratch.add(logEntry); | |
| 933 } else { | |
| 934 rtn.logs.add(logEntry); | |
| 935 --remainingCount; | |
| 936 } | |
| 937 } | |
| 938 } | |
| 939 return rtn; | |
| 940 } | |
| 941 | |
| 942 /** | |
| 943 * Iterate through the LogEntryList looking for matches to the entries | |
| 944 * in [keys]; for each match found the closest [distance] prior log entries | |
| 945 * that match [mocknameFilter] and [logFilter] will be included in the result. | |
| 946 * If [includeKeys] is true then the entries in [keys] that resulted in | |
| 947 * entries in the output list are themselves included in the output list. If | |
| 948 * [distance] is zero then all matches are included. | |
| 949 * | |
| 950 * The idea here is that you could find log entries that are related to | |
| 951 * other logs entries in some temporal sense. For example, say we have a | |
| 952 * method commit() that returns -1 on failure. Before commit() gets called | |
| 953 * the value being committed is created by process(). We may want to find | |
| 954 * the calls to process() that preceded calls to commit() that failed. | |
| 955 * We could do this with: | |
| 956 * | |
| 957 * print(log.preceding(log.getLogs(callsTo('commit'), returning(-1)), | |
| 958 * logFilter: callsTo('process')).toString()); | |
| 959 * | |
| 960 * We might want to include the details of the failing calls to commit() | |
| 961 * to see what parameters were passed in, in which case we would set | |
| 962 * [includeKeys]. | |
| 963 * | |
| 964 * As another simple example, say we wanted to know the three method | |
| 965 * calls that immediately preceded each failing call to commit(): | |
| 966 * | |
| 967 * print(log.preceding(log.getLogs(callsTo('commit'), returning(-1)), | |
| 968 * distance: 3).toString()); | |
| 969 */ | |
| 970 LogEntryList preceding(LogEntryList keys, | |
| 971 {mockNameFilter: null, | |
| 972 logFilter: null, | |
| 973 int distance: 1, | |
| 974 bool includeKeys: false}) => | |
| 975 _neighboring(true, keys, mockNameFilter, logFilter, | |
| 976 distance, includeKeys); | |
| 977 | |
| 978 /** | |
| 979 * Iterate through the LogEntryList looking for matches to the entries | |
| 980 * in [keys]; for each match found the closest [distance] subsequent log | |
| 981 * entries that match [mocknameFilter] and [logFilter] will be included in | |
| 982 * the result. If [includeKeys] is true then the entries in [keys] that | |
| 983 * resulted in entries in the output list are themselves included in the | |
| 984 * output list. If [distance] is zero then all matches are included. | |
| 985 * See [preceding] for a usage example. | |
| 986 */ | |
| 987 LogEntryList following(LogEntryList keys, | |
| 988 {mockNameFilter: null, | |
| 989 logFilter: null, | |
| 990 int distance: 1, | |
| 991 bool includeKeys: false}) => | |
| 992 _neighboring(false, keys, mockNameFilter, logFilter, | |
| 993 distance, includeKeys); | |
| 994 } | |
| 995 | |
| 996 /** | |
| 997 * [_TimesMatcher]s are used to make assertions about the number of | |
| 998 * times a method was called. | |
| 999 */ | |
| 1000 class _TimesMatcher extends Matcher { | |
| 1001 final int min, max; | |
| 1002 | |
| 1003 const _TimesMatcher(this.min, [this.max = -1]); | |
| 1004 | |
| 1005 bool matches(logList, Map matchState) => logList.length >= min && | |
| 1006 (max < 0 || logList.length <= max); | |
| 1007 | |
| 1008 Description describe(Description description) { | |
| 1009 description.add('to be called '); | |
| 1010 if (max < 0) { | |
| 1011 description.add('at least $min'); | |
| 1012 } else if (max == min) { | |
| 1013 description.add('$max'); | |
| 1014 } else if (min == 0) { | |
| 1015 description.add('at most $max'); | |
| 1016 } else { | |
| 1017 description.add('between $min and $max'); | |
| 1018 } | |
| 1019 return description.add(' times'); | |
| 1020 } | |
| 1021 | |
| 1022 Description describeMismatch(logList, Description mismatchDescription, | |
| 1023 Map matchState, bool verbose) => | |
| 1024 mismatchDescription.add('was called ${logList.length} times'); | |
| 1025 } | |
| 1026 | |
| 1027 /** [happenedExactly] matches an exact number of calls. */ | |
| 1028 Matcher happenedExactly(count) { | |
| 1029 return new _TimesMatcher(count, count); | |
| 1030 } | |
| 1031 | |
| 1032 /** [happenedAtLeast] matches a minimum number of calls. */ | |
| 1033 Matcher happenedAtLeast(count) { | |
| 1034 return new _TimesMatcher(count); | |
| 1035 } | |
| 1036 | |
| 1037 /** [happenedAtMost] matches a maximum number of calls. */ | |
| 1038 Matcher happenedAtMost(count) { | |
| 1039 return new _TimesMatcher(0, count); | |
| 1040 } | |
| 1041 | |
| 1042 /** [neverHappened] matches zero calls. */ | |
| 1043 const Matcher neverHappened = const _TimesMatcher(0, 0); | |
| 1044 | |
| 1045 /** [happenedOnce] matches exactly one call. */ | |
| 1046 const Matcher happenedOnce = const _TimesMatcher(1, 1); | |
| 1047 | |
| 1048 /** [happenedAtLeastOnce] matches one or more calls. */ | |
| 1049 const Matcher happenedAtLeastOnce = const _TimesMatcher(1); | |
| 1050 | |
| 1051 /** [happenedAtMostOnce] matches zero or one call. */ | |
| 1052 const Matcher happenedAtMostOnce = const _TimesMatcher(0, 1); | |
| 1053 | |
| 1054 /** | |
| 1055 * [_ResultMatcher]s are used to make assertions about the results | |
| 1056 * of method calls. These can be used as optional parameters to [getLogs]. | |
| 1057 */ | |
| 1058 class _ResultMatcher extends Matcher { | |
| 1059 final Action action; | |
| 1060 final Matcher value; | |
| 1061 | |
| 1062 const _ResultMatcher(this.action, this.value); | |
| 1063 | |
| 1064 bool matches(item, Map matchState) { | |
| 1065 if (item is! LogEntry) { | |
| 1066 return false; | |
| 1067 } | |
| 1068 // normalize the action; _PROXY is like _RETURN. | |
| 1069 Action eaction = item.action; | |
| 1070 if (eaction == Action.PROXY) { | |
| 1071 eaction = Action.RETURN; | |
| 1072 } | |
| 1073 return (eaction == action && value.matches(item.value, matchState)); | |
| 1074 } | |
| 1075 | |
| 1076 Description describe(Description description) { | |
| 1077 description.add(' to '); | |
| 1078 if (action == Action.RETURN || action == Action.PROXY) | |
| 1079 description.add('return '); | |
| 1080 else | |
| 1081 description.add('throw '); | |
| 1082 return description.addDescriptionOf(value); | |
| 1083 } | |
| 1084 | |
| 1085 Description describeMismatch(item, Description mismatchDescription, | |
| 1086 Map matchState, bool verbose) { | |
| 1087 if (item.action == Action.RETURN || item.action == Action.PROXY) { | |
| 1088 mismatchDescription.add('returned '); | |
| 1089 } else { | |
| 1090 mismatchDescription.add('threw '); | |
| 1091 } | |
| 1092 mismatchDescription.add(item.value); | |
| 1093 return mismatchDescription; | |
| 1094 } | |
| 1095 } | |
| 1096 | |
| 1097 /** | |
| 1098 *[returning] matches log entries where the call to a method returned | |
| 1099 * a value that matched [value]. | |
| 1100 */ | |
| 1101 Matcher returning(value) => | |
| 1102 new _ResultMatcher(Action.RETURN, wrapMatcher(value)); | |
| 1103 | |
| 1104 /** | |
| 1105 *[throwing] matches log entrues where the call to a method threw | |
| 1106 * a value that matched [value]. | |
| 1107 */ | |
| 1108 Matcher throwing(value) => | |
| 1109 new _ResultMatcher(Action.THROW, wrapMatcher(value)); | |
| 1110 | |
| 1111 /** Special values for use with [_ResultSetMatcher] [frequency]. */ | |
| 1112 class _Frequency { | |
| 1113 /** Every call/throw must match */ | |
| 1114 static const ALL = const _Frequency._('ALL'); | |
| 1115 | |
| 1116 /** At least one call/throw must match. */ | |
| 1117 static const SOME = const _Frequency._('SOME'); | |
| 1118 | |
| 1119 /** No calls/throws should match. */ | |
| 1120 static const NONE = const _Frequency._('NONE'); | |
| 1121 | |
| 1122 const _Frequency._(this.name); | |
| 1123 | |
| 1124 final String name; | |
| 1125 } | |
| 1126 | |
| 1127 /** | |
| 1128 * [_ResultSetMatcher]s are used to make assertions about the results | |
| 1129 * of method calls. When filtering an execution log by calling | |
| 1130 * [getLogs], a [LogEntrySet] of matching call logs is returned; | |
| 1131 * [_ResultSetMatcher]s can then assert various things about this | |
| 1132 * (sub)set of logs. | |
| 1133 * | |
| 1134 * We could make this class use _ResultMatcher but it doesn't buy that | |
| 1135 * match and adds some perf hit, so there is some duplication here. | |
| 1136 */ | |
| 1137 class _ResultSetMatcher extends Matcher { | |
| 1138 final Action action; | |
| 1139 final Matcher value; | |
| 1140 final _Frequency frequency; // ALL, SOME, or NONE. | |
| 1141 | |
| 1142 const _ResultSetMatcher(this.action, this.value, this.frequency); | |
| 1143 | |
| 1144 bool matches(logList, Map matchState) { | |
| 1145 for (LogEntry entry in logList) { | |
| 1146 // normalize the action; PROXY is like RETURN. | |
| 1147 Action eaction = entry.action; | |
| 1148 if (eaction == Action.PROXY) { | |
| 1149 eaction = Action.RETURN; | |
| 1150 } | |
| 1151 if (eaction == action && value.matches(entry.value, matchState)) { | |
| 1152 if (frequency == _Frequency.NONE) { | |
| 1153 addStateInfo(matchState, {'entry': entry}); | |
| 1154 return false; | |
| 1155 } else if (frequency == _Frequency.SOME) { | |
| 1156 return true; | |
| 1157 } | |
| 1158 } else { | |
| 1159 // Mismatch. | |
| 1160 if (frequency == _Frequency.ALL) { // We need just one mismatch to fail. | |
| 1161 addStateInfo(matchState, {'entry': entry}); | |
| 1162 return false; | |
| 1163 } | |
| 1164 } | |
| 1165 } | |
| 1166 // If we get here, then if count is _ALL we got all matches and | |
| 1167 // this is success; otherwise we got all mismatched which is | |
| 1168 // success for count == _NONE and failure for count == _SOME. | |
| 1169 return (frequency != _Frequency.SOME); | |
| 1170 } | |
| 1171 | |
| 1172 Description describe(Description description) { | |
| 1173 description.add(' to '); | |
| 1174 description.add(frequency == _Frequency.ALL ? 'alway ' : | |
| 1175 (frequency == _Frequency.NONE ? 'never ' : 'sometimes ')); | |
| 1176 if (action == Action.RETURN || action == Action.PROXY) | |
| 1177 description.add('return '); | |
| 1178 else | |
| 1179 description.add('throw '); | |
| 1180 return description.addDescriptionOf(value); | |
| 1181 } | |
| 1182 | |
| 1183 Description describeMismatch(logList, Description mismatchDescription, | |
| 1184 Map matchState, bool verbose) { | |
| 1185 if (frequency != _Frequency.SOME) { | |
| 1186 LogEntry entry = matchState['entry']; | |
| 1187 if (entry.action == Action.RETURN || entry.action == Action.PROXY) { | |
| 1188 mismatchDescription.add('returned'); | |
| 1189 } else { | |
| 1190 mismatchDescription.add('threw'); | |
| 1191 } | |
| 1192 mismatchDescription.add(' value that '); | |
| 1193 value.describeMismatch(entry.value, mismatchDescription, | |
| 1194 matchState['state'], verbose); | |
| 1195 mismatchDescription.add(' at least once'); | |
| 1196 } else { | |
| 1197 mismatchDescription.add('never did'); | |
| 1198 } | |
| 1199 return mismatchDescription; | |
| 1200 } | |
| 1201 } | |
| 1202 | |
| 1203 /** | |
| 1204 *[alwaysReturned] asserts that all matching calls to a method returned | |
| 1205 * a value that matched [value]. | |
| 1206 */ | |
| 1207 Matcher alwaysReturned(value) => | |
| 1208 new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.ALL); | |
| 1209 | |
| 1210 /** | |
| 1211 *[sometimeReturned] asserts that at least one matching call to a method | |
| 1212 * returned a value that matched [value]. | |
| 1213 */ | |
| 1214 Matcher sometimeReturned(value) => | |
| 1215 new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.SOME); | |
| 1216 | |
| 1217 /** | |
| 1218 *[neverReturned] asserts that no matching calls to a method returned | |
| 1219 * a value that matched [value]. | |
| 1220 */ | |
| 1221 Matcher neverReturned(value) => | |
| 1222 new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.NONE); | |
| 1223 | |
| 1224 /** | |
| 1225 *[alwaysThrew] asserts that all matching calls to a method threw | |
| 1226 * a value that matched [value]. | |
| 1227 */ | |
| 1228 Matcher alwaysThrew(value) => | |
| 1229 new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.ALL); | |
| 1230 | |
| 1231 /** | |
| 1232 *[sometimeThrew] asserts that at least one matching call to a method threw | |
| 1233 * a value that matched [value]. | |
| 1234 */ | |
| 1235 Matcher sometimeThrew(value) => | |
| 1236 new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.SOME); | |
| 1237 | |
| 1238 /** | |
| 1239 *[neverThrew] asserts that no matching call to a method threw | |
| 1240 * a value that matched [value]. | |
| 1241 */ | |
| 1242 Matcher neverThrew(value) => | |
| 1243 new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.NONE); | |
| 1244 | |
| 1245 /** The shared log used for named mocks. */ | |
| 1246 LogEntryList sharedLog = null; | |
| 1247 | |
| 1248 /** The base class for all mocked objects. */ | |
| 1249 @proxy | |
| 1250 class Mock { | |
| 1251 /** The mock name. Needed if the log is shared; optional otherwise. */ | |
| 1252 final String name; | |
| 1253 | |
| 1254 /** The set of [Behavior]s supported. */ | |
| 1255 final LinkedHashMap<String,Behavior> _behaviors; | |
| 1256 | |
| 1257 /** How to handle unknown method calls - swallow or throw. */ | |
| 1258 final bool _throwIfNoBehavior; | |
| 1259 | |
| 1260 /** For spys, the real object that we are spying on. */ | |
| 1261 final Object _realObject; | |
| 1262 | |
| 1263 /** The [log] of calls made. Only used if [name] is null. */ | |
| 1264 LogEntryList log; | |
| 1265 | |
| 1266 /** Whether to create an audit log or not. */ | |
| 1267 bool _logging; | |
| 1268 | |
| 1269 bool get logging => _logging; | |
| 1270 set logging(bool value) { | |
| 1271 if (value && log == null) { | |
| 1272 log = new LogEntryList(); | |
| 1273 } | |
| 1274 _logging = value; | |
| 1275 } | |
| 1276 | |
| 1277 /** | |
| 1278 * Default constructor. Unknown method calls are allowed and logged, | |
| 1279 * the mock has no name, and has its own log. | |
| 1280 */ | |
| 1281 Mock() : | |
| 1282 _throwIfNoBehavior = false, log = null, name = null, _realObject = null, | |
| 1283 _behaviors = new LinkedHashMap<String,Behavior>() { | |
| 1284 logging = true; | |
| 1285 } | |
| 1286 | |
| 1287 /** | |
| 1288 * This constructor makes a mock that has a [name] and possibly uses | |
| 1289 * a shared [log]. If [throwIfNoBehavior] is true, any calls to methods | |
| 1290 * that have no defined behaviors will throw an exception; otherwise they | |
| 1291 * will be allowed and logged (but will not do anything). | |
| 1292 * If [enableLogging] is false, no logging will be done initially (whether | |
| 1293 * or not a [log] is supplied), but [logging] can be set to true later. | |
| 1294 */ | |
| 1295 Mock.custom({this.name, | |
| 1296 this.log, | |
| 1297 throwIfNoBehavior: false, | |
| 1298 enableLogging: true}) | |
| 1299 : _throwIfNoBehavior = throwIfNoBehavior, _realObject = null, | |
| 1300 _behaviors = new LinkedHashMap<String,Behavior>() { | |
| 1301 if (log != null && name == null) { | |
| 1302 throw new Exception("Mocks with shared logs must have a name."); | |
| 1303 } | |
| 1304 logging = enableLogging; | |
| 1305 } | |
| 1306 | |
| 1307 /** | |
| 1308 * This constructor creates a spy with no user-defined behavior. | |
| 1309 * This is simply a proxy for a real object that passes calls | |
| 1310 * through to that real object but captures an audit trail of | |
| 1311 * calls made to the object that can be queried and validated | |
| 1312 * later. | |
| 1313 */ | |
| 1314 Mock.spy(this._realObject, {this.name, this.log}) | |
| 1315 : _behaviors = null, | |
| 1316 _throwIfNoBehavior = true { | |
| 1317 logging = true; | |
| 1318 } | |
| 1319 | |
| 1320 /** | |
| 1321 * [when] is used to create a new or extend an existing [Behavior]. | |
| 1322 * A [CallMatcher] [filter] must be supplied, and the [Behavior]s for | |
| 1323 * that signature are returned (being created first if needed). | |
| 1324 * | |
| 1325 * Typical use case: | |
| 1326 * | |
| 1327 * mock.when(callsTo(...)).alwaysReturn(...); | |
| 1328 */ | |
| 1329 Behavior when(CallMatcher logFilter) { | |
| 1330 String key = logFilter.toString(); | |
| 1331 if (!_behaviors.containsKey(key)) { | |
| 1332 Behavior b = new Behavior(logFilter); | |
| 1333 _behaviors[key] = b; | |
| 1334 return b; | |
| 1335 } else { | |
| 1336 return _behaviors[key]; | |
| 1337 } | |
| 1338 } | |
| 1339 | |
| 1340 /** | |
| 1341 * This is the handler for method calls. We loop through the list | |
| 1342 * of [Behavior]s, and find the first match that still has return | |
| 1343 * values available, and then do the action specified by that | |
| 1344 * return value. If we find no [Behavior] to apply an exception is | |
| 1345 * thrown. | |
| 1346 */ | |
| 1347 noSuchMethod(Invocation invocation) { | |
| 1348 var method = MirrorSystem.getName(invocation.memberName); | |
| 1349 var args = invocation.positionalArguments; | |
| 1350 if (invocation.isGetter) { | |
| 1351 method = 'get $method'; | |
| 1352 } else if (invocation.isSetter) { | |
| 1353 method = 'set $method'; | |
| 1354 // Remove the trailing '='. | |
| 1355 if (method[method.length-1] == '=') { | |
| 1356 method = method.substring(0, method.length - 1); | |
| 1357 } | |
| 1358 } | |
| 1359 if (_behaviors == null) { // Spy. | |
| 1360 var mirror = reflect(_realObject); | |
| 1361 try { | |
| 1362 var result = mirror.delegate(invocation); | |
| 1363 log.add(new LogEntry(name, method, args, Action.PROXY, result)); | |
| 1364 return result; | |
| 1365 } catch (e) { | |
| 1366 log.add(new LogEntry(name, method, args, Action.THROW, e)); | |
| 1367 throw e; | |
| 1368 } | |
| 1369 } | |
| 1370 bool matchedMethodName = false; | |
| 1371 Map matchState = {}; | |
| 1372 for (String k in _behaviors.keys) { | |
| 1373 Behavior b = _behaviors[k]; | |
| 1374 if (b.matcher.nameFilter.matches(method, matchState)) { | |
| 1375 matchedMethodName = true; | |
| 1376 } | |
| 1377 if (b.matches(method, args)) { | |
| 1378 List actions = b.actions; | |
| 1379 if (actions == null || actions.length == 0) { | |
| 1380 continue; // No return values left in this Behavior. | |
| 1381 } | |
| 1382 // Get the first response. | |
| 1383 Responder response = actions[0]; | |
| 1384 // If it is exhausted, remove it from the list. | |
| 1385 // Note that for endlessly repeating values, we started the count at | |
| 1386 // 0, so we get a potentially useful value here, which is the | |
| 1387 // (negation of) the number of times we returned the value. | |
| 1388 if (--response.count == 0) { | |
| 1389 actions.removeRange(0, 1); | |
| 1390 } | |
| 1391 // Do the response. | |
| 1392 Action action = response.action; | |
| 1393 var value = response.value; | |
| 1394 if (action == Action.RETURN) { | |
| 1395 if (_logging && b.logging) { | |
| 1396 log.add(new LogEntry(name, method, args, action, value)); | |
| 1397 } | |
| 1398 return value; | |
| 1399 } else if (action == Action.THROW) { | |
| 1400 if (_logging && b.logging) { | |
| 1401 log.add(new LogEntry(name, method, args, action, value)); | |
| 1402 } | |
| 1403 throw value; | |
| 1404 } else if (action == Action.PROXY) { | |
| 1405 // TODO(gram): Replace all this with: | |
| 1406 // var rtn = reflect(value).apply(invocation.positionalArguments, | |
| 1407 // invocation.namedArguments); | |
| 1408 // once that is supported. | |
| 1409 var rtn; | |
| 1410 switch (args.length) { | |
| 1411 case 0: | |
| 1412 rtn = value(); | |
| 1413 break; | |
| 1414 case 1: | |
| 1415 rtn = value(args[0]); | |
| 1416 break; | |
| 1417 case 2: | |
| 1418 rtn = value(args[0], args[1]); | |
| 1419 break; | |
| 1420 case 3: | |
| 1421 rtn = value(args[0], args[1], args[2]); | |
| 1422 break; | |
| 1423 case 4: | |
| 1424 rtn = value(args[0], args[1], args[2], args[3]); | |
| 1425 break; | |
| 1426 case 5: | |
| 1427 rtn = value(args[0], args[1], args[2], args[3], args[4]); | |
| 1428 break; | |
| 1429 case 6: | |
| 1430 rtn = value(args[0], args[1], args[2], args[3], | |
| 1431 args[4], args[5]); | |
| 1432 break; | |
| 1433 case 7: | |
| 1434 rtn = value(args[0], args[1], args[2], args[3], | |
| 1435 args[4], args[5], args[6]); | |
| 1436 break; | |
| 1437 case 8: | |
| 1438 rtn = value(args[0], args[1], args[2], args[3], | |
| 1439 args[4], args[5], args[6], args[7]); | |
| 1440 break; | |
| 1441 case 9: | |
| 1442 rtn = value(args[0], args[1], args[2], args[3], | |
| 1443 args[4], args[5], args[6], args[7], args[8]); | |
| 1444 break; | |
| 1445 case 9: | |
| 1446 rtn = value(args[0], args[1], args[2], args[3], | |
| 1447 args[4], args[5], args[6], args[7], args[8], args[9]); | |
| 1448 break; | |
| 1449 default: | |
| 1450 throw new Exception( | |
| 1451 "Cannot proxy calls with more than 10 parameters."); | |
| 1452 } | |
| 1453 if (_logging && b.logging) { | |
| 1454 log.add(new LogEntry(name, method, args, action, rtn)); | |
| 1455 } | |
| 1456 return rtn; | |
| 1457 } | |
| 1458 } | |
| 1459 } | |
| 1460 if (matchedMethodName) { | |
| 1461 // User did specify behavior for this method, but all the | |
| 1462 // actions are exhausted. This is considered an error. | |
| 1463 throw new Exception('No more actions for method ' | |
| 1464 '${_qualifiedName(name, method)}.'); | |
| 1465 } else if (_throwIfNoBehavior) { | |
| 1466 throw new Exception('No behavior specified for method ' | |
| 1467 '${_qualifiedName(name, method)}.'); | |
| 1468 } | |
| 1469 // Otherwise user hasn't specified behavior for this method; we don't throw | |
| 1470 // so we can underspecify. | |
| 1471 if (_logging) { | |
| 1472 log.add(new LogEntry(name, method, args, Action.IGNORE)); | |
| 1473 } | |
| 1474 } | |
| 1475 | |
| 1476 /** [verifyZeroInteractions] returns true if no calls were made */ | |
| 1477 bool verifyZeroInteractions() { | |
| 1478 if (log == null) { | |
| 1479 // This means we created the mock with logging off and have never turned | |
| 1480 // it on, so it doesn't make sense to verify behavior on such a mock. | |
| 1481 throw new | |
| 1482 Exception("Can't verify behavior when logging was never enabled."); | |
| 1483 } | |
| 1484 return log.logs.length == 0; | |
| 1485 } | |
| 1486 | |
| 1487 /** | |
| 1488 * [getLogs] extracts all calls from the call log that match the | |
| 1489 * [logFilter], and returns the matching list of [LogEntry]s. If | |
| 1490 * [destructive] is false (the default) the matching calls are left | |
| 1491 * in the log, else they are removed. Removal allows us to verify a | |
| 1492 * set of interactions and then verify that there are no other | |
| 1493 * interactions left. [actionMatcher] can be used to further | |
| 1494 * restrict the returned logs based on the action the mock performed. | |
| 1495 * [logFilter] can be a [CallMatcher] or a predicate function that | |
| 1496 * takes a [LogEntry] and returns a bool. | |
| 1497 * | |
| 1498 * Typical usage: | |
| 1499 * | |
| 1500 * getLogs(callsTo(...)).verify(...); | |
| 1501 */ | |
| 1502 LogEntryList getLogs([CallMatcher logFilter, | |
| 1503 Matcher actionMatcher, | |
| 1504 bool destructive = false]) { | |
| 1505 if (log == null) { | |
| 1506 // This means we created the mock with logging off and have never turned | |
| 1507 // it on, so it doesn't make sense to get logs from such a mock. | |
| 1508 throw new | |
| 1509 Exception("Can't retrieve logs when logging was never enabled."); | |
| 1510 } else { | |
| 1511 return log.getMatches(name, logFilter, actionMatcher, destructive); | |
| 1512 } | |
| 1513 } | |
| 1514 | |
| 1515 /** | |
| 1516 * Useful shorthand method that creates a [CallMatcher] from its arguments | |
| 1517 * and then calls [getLogs]. | |
| 1518 */ | |
| 1519 LogEntryList calls(method, | |
| 1520 [arg0 = _noArg, | |
| 1521 arg1 = _noArg, | |
| 1522 arg2 = _noArg, | |
| 1523 arg3 = _noArg, | |
| 1524 arg4 = _noArg, | |
| 1525 arg5 = _noArg, | |
| 1526 arg6 = _noArg, | |
| 1527 arg7 = _noArg, | |
| 1528 arg8 = _noArg, | |
| 1529 arg9 = _noArg]) => | |
| 1530 getLogs(callsTo(method, arg0, arg1, arg2, arg3, arg4, | |
| 1531 arg5, arg6, arg7, arg8, arg9)); | |
| 1532 | |
| 1533 /** Clear the behaviors for the Mock. */ | |
| 1534 void resetBehavior() => _behaviors.clear(); | |
| 1535 | |
| 1536 /** Clear the logs for the Mock. */ | |
| 1537 void clearLogs() { | |
| 1538 if (log != null) { | |
| 1539 if (name == null) { // This log is not shared. | |
| 1540 log.logs.clear(); | |
| 1541 } else { // This log may be shared. | |
| 1542 log.logs = log.logs.where((e) => e.mockName != name).toList(); | |
| 1543 } | |
| 1544 } | |
| 1545 } | |
| 1546 | |
| 1547 /** Clear both logs and behavior. */ | |
| 1548 void reset() { | |
| 1549 resetBehavior(); | |
| 1550 clearLogs(); | |
| 1551 } | |
| 1552 } | |
| OLD | NEW |