README.md

Important

This repo has moved to https://github.com/dart-lang/test/tree/master/pkgs/matcher

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.

Using matcher

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().

Exception matchers

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);
  });
}

Future Matchers

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 Futures. 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));
  });
}

Stream Matchers

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().

Best Practices

Prefer semantically meaningful matchers to comparing derived values

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>

Prefer TypeMatcher to predicate if the match can fail in multiple ways

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.