Dart Documentationmock

mock library

A simple mocking/spy library.

To create a mock objects for some class T, create a new class using:

class MockT extends Mock implements T {};

Then specify the Behavior of the Mock for different methods using when (to select the method and parameters) and then the Actions for the Behavior by calling thenReturn, alwaysReturn, thenThrow, alwaysThrow, thenCall or alwaysCall.

thenReturn, thenThrow and thenCall are one-shot so you would typically call these more than once to specify a sequence of actions; this can be done with chained calls, e.g.:

 m.when(callsTo('foo')).
     thenReturn(0).thenReturn(1).thenReturn(2);

thenCall and alwaysCall allow you to proxy mocked methods, chaining to some other implementation. This provides a way to implement 'spies'.

For getters and setters, use "get foo" and "set foo"-style arguments to callsTo.

You can disable logging for a particular Behavior easily:

m.when(callsTo('bar')).logging = false;

You can then use the mock object. Once you are done, to verify the behavior, use getLogs to extract a relevant subset of method call logs and apply Matchers to these through calling verify.

A Mock can be given a name when constructed. In this case instead of keeping its own log, it uses a shared log. This can be useful to get an audit trail of interleaved behavior. It is the responsibility of the user to ensure that mock names, if used, are unique.

Limitations:

  • only positional parameters are supported (up to 10);
  • to mock getters you will need to include parentheses in the call (e.g. m.length() will work but not m.length).

Here is a simple example:

class MockList extends Mock implements List {};

List m = new MockList();
m.when(callsTo('add', anything)).alwaysReturn(0);

m.add('foo');
m.add('bar');

getLogs(m, callsTo('add', anything)).verify(happenedExactly(2));
getLogs(m, callsTo('add', 'foo')).verify(happenedOnce);
getLogs(m, callsTo('add', 'isNull)).verify(neverHappened);

Note that we don't need to provide argument matchers for all arguments, but we do need to provide arguments for all matchers. So this is allowed:

m.when(callsTo('add')).alwaysReturn(0);
m.add(1, 2);

But this is not allowed and will throw an exception:

m.when(callsTo('add', anything, anything)).alwaysReturn(0);
m.add(1);

Here is a way to implement a 'spy', which is where we log the call but then hand it off to some other function, which is the same method in a real instance of the class being mocked:

class Foo {
  bar(a, b, c) => a + b + c;
}

class MockFoo extends Mock implements Foo {
  Foo real;
  MockFoo() {
    real = new Foo();
    this.when(callsTo('bar')).alwaysCall(real.bar);
  }
}

Properties

const Matcher happenedAtLeastOnce #

happenedAtLeastOnce matches one or more calls.

const Matcher happenedAtLeastOnce = const _TimesMatcher(1)

const Matcher happenedAtMostOnce #

happenedAtMostOnce matches zero or one call.

const Matcher happenedAtMostOnce = const _TimesMatcher(0, 1)

const Matcher happenedOnce #

happenedOnce matches exactly one call.

const Matcher happenedOnce = const _TimesMatcher(1, 1)

const Matcher neverHappened #

neverHappened matches zero calls.

const Matcher neverHappened = const _TimesMatcher(0, 0)

LogEntryList sharedLog #

The shared log used for named mocks.

LogEntryList sharedLog = null

Functions

Matcher neverThrew(value) #

neverThrew asserts that no matching call to a method threw a value that matched value.

Matcher neverThrew(value) =>
 new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.NONE);

Matcher sometimeThrew(value) #

sometimeThrew asserts that at least one matching call to a method threw a value that matched value.

Matcher sometimeThrew(value) =>
 new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.SOME);

Matcher alwaysThrew(value) #

alwaysThrew asserts that all matching calls to a method threw a value that matched value.

Matcher alwaysThrew(value) =>
   new _ResultSetMatcher(Action.THROW, wrapMatcher(value), _Frequency.ALL);

Matcher neverReturned(value) #

neverReturned asserts that no matching calls to a method returned a value that matched value.

Matcher neverReturned(value) =>
   new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.NONE);

Matcher sometimeReturned(value) #

sometimeReturned asserts that at least one matching call to a method returned a value that matched value.

Matcher sometimeReturned(value) =>
   new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.SOME);

Matcher alwaysReturned(value) #

alwaysReturned asserts that all matching calls to a method returned a value that matched value.

Matcher alwaysReturned(value) =>
   new _ResultSetMatcher(Action.RETURN, wrapMatcher(value), _Frequency.ALL);

Matcher throwing(value) #

throwing matches log entrues where the call to a method threw a value that matched value.

Matcher throwing(value) =>
   new _ResultMatcher(Action.THROW, wrapMatcher(value));

Matcher returning(value) #

returning matches log entries where the call to a method returned a value that matched value.

Matcher returning(value) =>
   new _ResultMatcher(Action.RETURN, wrapMatcher(value));

Matcher happenedAtMost(count) #

happenedAtMost matches a maximum number of calls.

Matcher happenedAtMost(count) {
 return new _TimesMatcher(0, count);
}

Matcher happenedAtLeast(count) #

happenedAtLeast matches a minimum number of calls.

Matcher happenedAtLeast(count) {
 return new _TimesMatcher(count);
}

Matcher happenedExactly(count) #

happenedExactly matches an exact number of calls.

Matcher happenedExactly(count) {
 return new _TimesMatcher(count, count);
}

CallMatcher callsTo([method, arg0 = _noArg, arg1 = _noArg, arg2 = _noArg, arg3 = _noArg, arg4 = _noArg, arg5 = _noArg, arg6 = _noArg, arg7 = _noArg, arg8 = _noArg, arg9 = _noArg]) #

Returns a CallMatcher for the specified signature. method can be null to match anything, or a literal String, a predicate Function, or a Matcher. The various arguments can be scalar values or Matchers. To match getters and setters, use "get " and "set " prefixes on the names. For example, for a property "foo", you could use "get foo" and "set foo" as literal string arguments to callsTo to match the getter and setter of "foo".

CallMatcher callsTo([method,
                    arg0 = _noArg,
                    arg1 = _noArg,
                    arg2 = _noArg,
                    arg3 = _noArg,
                    arg4 = _noArg,
                    arg5 = _noArg,
                    arg6 = _noArg,
                    arg7 = _noArg,
                    arg8 = _noArg,
                    arg9 = _noArg]) {
 return new CallMatcher(method, arg0, arg1, arg2, arg3, arg4,
     arg5, arg6, arg7, arg8, arg9);
}

Classes

Typedefs