unittest 0.11.5+4

Support for writing unit tests in Dart.

See also: [Unit Testing with Dart] (http://www.dartlang.org/articles/dart-unit-tests/)


  • Tests: Tests are specified via the top-level function [test], they can be organized together using [group].

  • Checks: Test expectations can be specified via [expect]

  • Matchers: [expect] assertions are written declaratively using the [Matcher] class.

  • Configuration: The framework can be adapted by setting [unittestConfiguration] with a [Configuration]. See the other libraries in the unittest package for alternative implementations of [Configuration] including compact_vm_config.dart, html_config.dart and html_enhanced_config.dart.


A trivial test:

import 'package:unittest/unittest.dart';

void main() {
  test('this is a test', () {
    int x = 2 + 3;
    expect(x, equals(5));

Multiple tests:

import 'package:unittest/unittest.dart';

void main() {
  test('this is a test', () {
    int x = 2 + 3;
    expect(x, equals(5));
  test('this is another test', () {
    int x = 2 + 3;
    expect(x, equals(5));

Multiple tests, grouped by category:

import 'package:unittest/unittest.dart';

void main() {
  group('group A', () {
    test('test A.1', () {
      int x = 2 + 3;
      expect(x, equals(5));
    test('test A.2', () {
      int x = 2 + 3;
      expect(x, equals(5));
  group('group B', () {
    test('this B.1', () {
      int x = 2 + 3;
      expect(x, equals(5));

Asynchronous tests: if callbacks expect between 0 and 6 positional arguments, [expectAsync] will wrap a function into a new callback and will not consider the test complete until that callback is run. A count argument can be provided to specify the number of times the callback should be called (the default is 1).

import 'dart:async';
import 'package:unittest/unittest.dart';

void main() {
  test('callback is executed once', () {
    // wrap the callback of an asynchronous call with [expectAsync] if
    // the callback takes 0 arguments...
    Timer.run(expectAsync(() {
      int x = 2 + 3;
      expect(x, equals(5));

  test('callback is executed twice', () {
    var callback = expectAsync(() {
      int x = 2 + 3;
      expect(x, equals(5));
    }, count: 2); // <-- we can indicate multiplicity to [expectAsync]

There may be times when the number of times a callback should be called is non-deterministic. In this case a dummy callback can be created with expectAsync((){}) and this can be called from the real callback when it is finally complete.

A variation on this is [expectAsyncUntil], which takes a callback as the first parameter and a predicate function as the second parameter. After each time the callback is called, the predicate function will be called. If it returns false the test will still be considered incomplete.

Test functions can return [Future]s, which provide another way of doing asynchronous tests. The test framework will handle exceptions thrown by the Future, and will advance to the next test when the Future is complete.

import 'dart:async';
import 'package:unittest/unittest.dart';

void main() {
  test('test that time has passed', () {
    var duration = const Duration(milliseconds: 200);
    var time = new DateTime.now();

    return new Future.delayed(duration).then((_) {
      var delta = new DateTime.now().difference(time);

      expect(delta, greaterThanOrEqualTo(duration));


  • Improved the output of TestCase failures in HtmlConfig.


  • Fixed issue with handling exceptions.


  • Properly detect when tests are finished being run on content shell.


  • Internal code cleanups and documentation improvements.


  • Bumped the version constraint for matcher.


  • Bump the version constraint for matcher.


  • Narrow the constraint on matcher to ensure that new features are reflected in unittest's version.


  • Prints a warning instead of throwing an error when setting the test configuration after it has already been set. The first configuration is always used.


  • Fix bug in withTestEnvironment where test cases were not reinitialized if called multiple times.


  • Add reason named argument to expectAsync and expectAsyncUntil, which has the same definition as expect's reason argument.
  • Added support for private test environments.


  • Refactored package tests.


  • Release test functions after each test is run.



  • Updated maximum matcher version.


  • Removed unused files from tests and standardized remaining test file names.


  • Widen the version constraint for stack_trace.


  • Deprecated methods have been removed:
    • expectAsync0, expectAsync1, and expectAsync2 - use expectAsync instead
    • expectAsyncUntil0, expectAsyncUntil1, and expectAsyncUntil2 - use expectAsyncUntil instead
    • guardAsync - no longer needed
    • protectAsync0, protectAsync1, and protectAsync2 - no longer needed
  • matcher.dart and mirror_matchers.dart have been removed. They are now in the matcher package.
  • mock.dart has been removed. It is now in the mock package.


  • Fixed deprecation message for mock.


  • Moved to triple-slash for all doc comments.


    • matcher.dart and mirror_matchers.dart are now in the matcher package.
    • mock.dart is now in the mock package.
  • equals now allows a nested matcher as an expected list element or map value when doing deep matching.
  • expectAsync and expectAsyncUntil now support up to 6 positional arguments and correctly handle functions with optional positional arguments with default values.


  • Each test is run in a separate Zone. This ensures that any exceptions that occur is async operations are reported back to the source test case.
  • DEPRECATED guardAsync, protectAsync0, protectAsync1, and protectAsync2
    • Running each test in a Zone addresses the need for these methods.
  • NEW! expectAsync replaces the now deprecated expectAsync0, expectAsync1 and expectAsync2
  • NEW! expectAsyncUntil replaces the now deprecated expectAsyncUntil0, expectAsyncUntil1 and expectAsyncUntil2
  • TestCase:
    • Removed properties: setUp, tearDown, testFunction
    • enabled is now get-only
    • Removed methods: pass, fail, error
  • interactive_html_config.dart has been removed.
  • runTests, tearDown, setUp, test, group, solo_test, and solo_group now throw a StateError if called while tests are running.
  • rerunTests has been removed.

1. Depend on it

Add this to your package's pubspec.yaml file:

  unittest: ">=0.11.5+4 <0.12.0"

If your package is an application package you should use any as the version constraint.

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support pub. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:unittest/unittest.dart';


A library for writing dart unit tests.


Email misc@dartlang.org Dart Team