Support for specifying test expectations, such as for unit tests.
The matcher library provides a third-generation assertion mechanism, drawing inspiration from Hamcrest.
For more information on testing, see Unit Testing with Dart.
Expectations start with a call to expect()
or expectAsync()
.
Any matchers package can be used with expect()
to do
complex validations:
import 'package:test/test.dart';
void main() {
test('.split() splits the string on the delimiter', () {
expect('foo,bar,baz', allOf([
contains('foo'),
isNot(startsWith('bar')),
endsWith('baz')
]));
});
}
If a non-matcher value is passed, it will be wrapped with equals()
.
You can also test exceptions with the throwsA()
function or a matcher such
as throwsFormatException
:
import 'package:test/test.dart';
void main() {
test('.parse() fails on invalid input', () {
expect(() => int.parse('X'), throwsFormatException);
});
}
There are a number of useful functions and matchers for more advanced
asynchrony. The completion()
matcher can be used to test Futures
; it
ensures that the test doesn't finish until the Future
completes, and runs a
matcher against that Future
's value.
import 'dart:async';
import 'package:test/test.dart';
void main() {
test('Future.value() returns the value', () {
expect(Future.value(10), completion(equals(10)));
});
}
The throwsA()
matcher and the various throwsExceptionType
matchers work
with both synchronous callbacks and asynchronous Future
s. They ensure that a
particular type of exception is thrown:
import 'dart:async';
import 'package:test/test.dart';
void main() {
test('Future.error() throws the error', () {
expect(Future.error('oh no'), throwsA(equals('oh no')));
expect(Future.error(StateError('bad state')), throwsStateError);
});
}
The expectAsync()
function wraps another function and has two jobs. First,
it asserts that the wrapped function is called a certain number of times, and
will cause the test to fail if it's called too often; second, it keeps the test
from finishing until the function is called the requisite number of times.
import 'dart:async';
import 'package:test/test.dart';
void main() {
test('Stream.fromIterable() emits the values in the iterable', () {
var stream = Stream.fromIterable([1, 2, 3]);
stream.listen(expectAsync1((number) {
expect(number, inInclusiveRange(1, 3));
}, count: 3));
});
}
The test
package provides a suite of powerful matchers for dealing with
asynchronous streams. They're expressive and composable, and make it
easy to write complex expectations about the values emitted by a stream. For
example:
import 'dart:async';
import 'package:test/test.dart';
void main() {
test('process emits status messages', () {
// Dummy data to mimic something that might be emitted by a process.
var stdoutLines = Stream.fromIterable([
'Ready.',
'Loading took 150ms.',
'Succeeded!'
]);
expect(stdoutLines, emitsInOrder([
// Values match individual events.
'Ready.',
// Matchers also run against individual events.
startsWith('Loading took'),
// Stream matchers can be nested. This asserts that one of two events are
// emitted after the "Loading took" line.
emitsAnyOf(['Succeeded!', 'Failed!']),
// By default, more events are allowed after the matcher finishes
// matching. This asserts instead that the stream emits a done event and
// nothing else.
emitsDone
]));
});
}
A stream matcher can also match the async
package's StreamQueue
class,
which allows events to be requested from a stream rather than pushed to the
consumer. The matcher will consume the matched events, but leave the rest of the
queue alone so that it can still be used by the test, unlike a normal Stream
which can only have one subscriber. For example:
import 'dart:async';
import 'package:async/async.dart';
import 'package:test/test.dart';
void main() {
test('process emits a WebSocket URL', () async {
// Wrap the Stream in a StreamQueue so that we can request events.
var stdout = StreamQueue(Stream.fromIterable([
'WebSocket URL:',
'ws://localhost:1234/',
'Waiting for connection...'
]));
// Ignore lines from the process until it's about to emit the URL.
await expectLater(stdout, emitsThrough('WebSocket URL:'));
// Parse the next line as a URL.
var url = Uri.parse(await stdout.next);
expect(url.host, equals('localhost'));
// You can match against the same StreamQueue multiple times.
await expectLater(stdout, emits('Waiting for connection...'));
});
}
The following built-in stream matchers are available:
emits()
matches a single data event.emitsError()
matches a single error event.emitsDone
matches a single done event.mayEmit()
consumes events if they match an inner matcher, without
requiring them to match.mayEmitMultiple()
works like mayEmit()
, but it matches events against
the matcher as many times as possible.emitsAnyOf()
consumes events matching one (or more) of several possible
matchers.emitsInOrder()
consumes events matching multiple matchers in a row.emitsInAnyOrder()
works like emitsInOrder()
, but it allows the
matchers to match in any order.neverEmits()
matches a stream that finishes without matching an inner
matcher.You can also define your own custom stream matchers with StreamMatcher()
.
Matchers which have knowledge of the semantics that are tested are able to emit
more meaningful messages which don't require reading test source to understand
why the test failed. For instance compare the failures between
expect(someList.length, 1)
, and expect(someList, hasLength(1))
:
// expect(someList.length, 1);
Expected: <1>
Actual: <2>
// expect(someList, hasLength(1));
Expected: an object with length of <1>
Actual: ['expected value', 'unexpected value']
Which: has length of <2>
The predicate
utility is a convenient shortcut for testing an arbitrary
(synchronous) property of a value, but it discards context and failures are
opaque. Different failure modes cannot be distinguished in the output which is
determined by a single "description" argument. Using isA<SomeType>()
and the
TypeMatcher.having
API to extract and test derived properties in a structured
way brings the context of that structure through to failure messages, so
failures for different reasons will have distinguishable and actionable failure
messages.