pkg/unittest/lib/unittest.dart - sdk.git - Git at Google

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.

 /// Support for writing Dart unit tests.
 ///
 /// For information on installing and importing this library, see the
 /// [unittest package on pub.dartlang.org]
 /// (http://pub.dartlang.org/packages/unittest).
 ///
 /// **See also:**
 /// [Unit Testing with Dart]
 /// (http://www.dartlang.org/articles/dart-unit-tests/)
 ///
 /// ##Concepts
 ///
 ///  * __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`.
 ///
 /// ##Examples
 ///
 /// A trivial test:
 ///
 ///     import 'package:unittest/unittest.dart';
 ///     main() {
 ///       test('this is a test', () {
 ///         int x = 2 + 3;
 ///         expect(x, equals(5));
 ///       });
 ///     }
 ///
 /// Multiple tests:
 ///
 ///     import 'package:unittest/unittest.dart';
 ///     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';
 ///     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...
 ///         var timer = 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]
 ///         Timer.run(callback);
 ///         Timer.run(callback);
 ///       });
 ///     }
 ///
 /// 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));
 ///         });
 ///       });
 ///     }
 library unittest;

 import 'dart:async';
 import 'dart:collection';
 import 'dart:isolate';

 import 'package:matcher/matcher.dart' show DefaultFailureHandler,
     configureExpectFailureHandler, TestFailure, wrapAsync;
 export 'package:matcher/matcher.dart';

 import 'src/utils.dart';

 import 'src/configuration.dart';
 export 'src/configuration.dart';

 part 'src/simple_configuration.dart';
 part 'src/group_context.dart';
 part 'src/spread_args_helper.dart';
 part 'src/test_case.dart';
 part 'src/test_environment.dart';

 const Symbol _UNITTEST_ENVIRONMENT = #unittest.environment;

 final _TestEnvironment _defaultEnvironment = new _TestEnvironment();

 /**
  * Internal getter for the current unittest config.
  */
 _TestEnvironment get _environment {
   var environment = Zone.current[_UNITTEST_ENVIRONMENT];
   if (environment == null) return _defaultEnvironment;
   return environment;
 }

 // Convenience getter for the current environment's config.
 Configuration get _config => _environment.config;

 // Convenience setter for the current environment's config.
 void set _config(Configuration config) {
   _environment.config = config;
 }

 // Convenience getter for the current environment's test cases.
 List<TestCase> get _testCases => _environment.testCases;

 /// [Configuration] used by the unittest library.
 ///
 /// Note that if a configuration has not been set, calling this getter will
 /// create a default configuration.
 Configuration get unittestConfiguration {
   if (_config == null) {
     _config = new Configuration();
   }
   return _config;
 }

 /// Sets the [Configuration] used by the unittest library.
 ///
 /// Throws a [StateError] if there is an existing, incompatible value.
 void set unittestConfiguration(Configuration value) {
   if (!identical(_config, value)) {
     if (_config != null) {
       logMessage('Warning: The unittestConfiguration has already been set. New '
           'unittestConfiguration ignored.');
     } else {
       _config = value;
     }
   }
 }

 /// Can be called by tests to log status. Tests should use this
 /// instead of [print].
 void logMessage(String message) =>
     _config.onLogMessage(currentTestCase, message);

 /// Separator used between group names and test names.
 String groupSep = ' ';

 /// Tests executed in this suite.
 List<TestCase> get testCases =>
     new UnmodifiableListView<TestCase>(_environment.testCases);

 /// Interval (in msecs) after which synchronous tests will insert an async
 /// delay to allow DOM or other updates.
 const int BREATH_INTERVAL = 200;

 /// [TestCase] currently being executed.
 TestCase get currentTestCase =>
     (_environment.currentTestCaseIndex >= 0 &&
      _environment.currentTestCaseIndex < testCases.length)
         ? testCases[_environment.currentTestCaseIndex]
         : null;

 /* Test case result strings. */
 // TODO(gram) we should change these constants to use a different string
 // (so that writing 'FAIL' in the middle of a test doesn't
 // imply that the test fails). We can't do it without also changing
 // the testrunner and test.dart though.
 /// Result string for a passing test case.
 const PASS = 'pass';
 /// Result string for a failing test case.
 const FAIL = 'fail';
 /// Result string for an test case with an error.
 const ERROR = 'error';

 /// Creates a new test case with the given description and body. The
 /// description will include the descriptions of any surrounding group()
 /// calls.
 void test(String spec, TestFunction body) {
   _requireNotRunning();
   ensureInitialized();
   if (!_environment.soloTestSeen || _environment.soloNestingLevel > 0) {
     var testcase = new TestCase._internal(testCases.length + 1, _fullSpec(spec),
         body);
     _testCases.add(testcase);
   }
 }

 /// Convenience function for skipping a test.
 void skip_test(String spec, TestFunction body) {}

 /// Creates a new test case with the given description and body. The
 /// description will include the descriptions of any surrounding group()
 /// calls.
 ///
 /// If we use [solo_test] (or [solo_group]) instead of test, then all non-solo
 /// tests will be disabled. Note that if we use [solo_group], all tests in
 /// the group will be enabled, regardless of whether they use [test] or
 /// [solo_test], or whether they are in a nested [group] vs [solo_group]. Put
 /// another way, if there are any calls to [solo_test] or [solo_group] in a test
 /// file, all tests that are not inside a [solo_group] will be disabled unless
 /// they are [solo_test]s.
 ///
 /// [skip_test] and [skip_group] take precedence over soloing, by virtue of the
 /// fact that they are effectively no-ops.
 void solo_test(String spec, TestFunction body) {
   _requireNotRunning();
   ensureInitialized();
   if (!_environment.soloTestSeen) {
     _environment.soloTestSeen = true;
     // This is the first solo-ed test. Discard all tests up to now.
     _testCases.clear();
   }
   ++_environment.soloNestingLevel;
   try {
     test(spec, body);
   } finally {
     --_environment.soloNestingLevel;
   }
 }

 /// Indicate that [callback] is expected to be called a [count] number of times
 /// (by default 1).
 ///
 /// The unittest framework will wait for the callback to run the
 /// specified [count] times before it continues with the following test.  Using
 /// [expectAsync] will also ensure that errors that occur within [callback] are
 /// tracked and reported. [callback] should take 0 positional arguments (named
 /// arguments are not supported). [id] can be used to provide more
 /// descriptive error messages if the callback is called more often than
 /// expected.
 ///
 /// [max] can be used to specify an upper bound on the number of
 /// calls; if this is exceeded the test will fail (or be marked as in error if
 /// it was already complete). A value of 0 for [max] (the default) will set
 /// the upper bound to the same value as [count]; i.e. the callback should be
 /// called exactly [count] times. A value of -1 for [max] will mean no upper
 /// bound.
 ///
 /// [reason] is optional and is typically not supplied, as a reason is generated
 /// by the unittest package; if reason is included it is appended to the
 /// generated reason.
 Function expectAsync(Function callback,
     {int count: 1, int max: 0, String id, String reason}) =>
   new _SpreadArgsHelper(callback, count, max, id, reason).func;

 /// Indicate that [callback] is expected to be called until [isDone] returns
 /// true.
 ///
 /// The unittest framework checks [isDone] after each callback and only
 /// when it returns true will it continue with the following test. Using
 /// [expectAsyncUntil] will also ensure that errors that occur within
 /// [callback] are tracked and reported. [callback] should take 0 positional
 /// arguments (named arguments are not supported). [id] can be used to
 /// identify the callback in error messages (for example if it is called
 /// after the test case is complete).
 ///
 /// [reason] is optional and is typically not supplied, as a reason is generated
 /// by the unittest package; if reason is included it is appended to the
 /// generated reason.
 Function expectAsyncUntil(Function callback, bool isDone(),
     {String id, String reason}) =>
   new _SpreadArgsHelper(callback, 0, -1, id, reason, isDone: isDone).func;

 /// Creates a new named group of tests.
 ///
 /// Calls to group() or test() within the body of the function passed to this
 /// named group will inherit this group's description.
 void group(String description, void body()) {
   ensureInitialized();
   _requireNotRunning();
   _environment.currentContext =
       new _GroupContext(_environment.currentContext, description);
   try {
     body();
   } catch (e, trace) {
     var stack = (trace == null) ? '' : ': ${trace.toString()}';
     _environment.uncaughtErrorMessage = "${e.toString()}$stack";
   } finally {
     // Now that the group is over, restore the previous one.
     _environment.currentContext = _environment.currentContext.parent;
   }
 }

 /// Like [skip_test], but for groups.
 void skip_group(String description, void body()) {}

 /// Like [solo_test], but for groups.
 void solo_group(String description, void body()) {
   _requireNotRunning();
   ensureInitialized();
   if (!_environment.soloTestSeen) {
     _environment.soloTestSeen = true;
     // This is the first solo-ed group. Discard all tests up to now.
     _testCases.clear();
   }
   ++_environment.soloNestingLevel;
   try {
     group(description, body);
   } finally {
     --_environment.soloNestingLevel;
   }
 }

 /// Register a [setUp] function for a test [group].
 ///
 /// This function will be called before each test in the group is run.
 /// [setUp] and [tearDown] should be called within the [group] before any
 /// calls to [test]. The [setupTest] function can be asynchronous; in this
 /// case it must return a [Future].
 void setUp(Function setupTest) {
   _requireNotRunning();
   _environment.currentContext.testSetup = setupTest;
 }

 /// Register a [tearDown] function for a test [group].
 ///
 /// This function will be called after each test in the group is run.
 ///
 /// Note that if groups are nested only the most locally scoped [teardownTest]
 /// function will be run. [setUp] and [tearDown] should be called within the
 /// [group] before any calls to [test]. The [teardownTest] function can be
 /// asynchronous; in this case it must return a [Future].
 void tearDown(Function teardownTest) {
   _requireNotRunning();
   _environment.currentContext.testTeardown = teardownTest;
 }

 /// Advance to the next test case.
 void _nextTestCase() {
   _environment.currentTestCaseIndex++;
   _runTest();
 }

 /// Handle errors that happen outside the tests.
 // TODO(vsm): figure out how to expose the stack trace here
 // Currently e.message works in dartium, but not in dartc.
 void handleExternalError(e, String message, [stack]) {
   var msg = '$message\nCaught $e';

   if (currentTestCase != null) {
     currentTestCase._error(msg, stack);
   } else {
     _environment.uncaughtErrorMessage = "$msg: $stack";
   }
 }

 /// Filter the tests by [testFilter].
 ///
 /// [testFilter] can be a [RegExp], a [String] or a
 /// predicate function. This is different from enabling or disabling tests
 /// in that it removes the tests completely.
 void filterTests(testFilter) {
   var filterFunction;
   if (testFilter is String) {
     RegExp re = new RegExp(testFilter);
     filterFunction = (t) => re.hasMatch(t.description);
   } else if (testFilter is RegExp) {
     filterFunction = (t) => testFilter.hasMatch(t.description);
   } else if (testFilter is Function) {
     filterFunction = testFilter;
   }
   _testCases.retainWhere(filterFunction);
 }

 /// Runs all queued tests, one at a time.
 void runTests() {
   _requireNotRunning();
   _ensureInitialized(false);
   _environment.currentTestCaseIndex = 0;
   _config.onStart();
   _runTest();
 }

 /// Registers that an exception was caught for the current test.
 void registerException(e, [trace]) {
   _registerException(currentTestCase, e, trace);
 }

 /// Registers that an exception was caught for the current test.
 void _registerException(TestCase testCase, e, [trace]) {
   String message = (e is TestFailure) ? e.message : 'Caught $e';
   if (testCase.result == null) {
     testCase._fail(message, trace);
   } else {
     testCase._error(message, trace);
   }
 }

 /// Runs the next test.
 void _runTest() {
   if (_environment.currentTestCaseIndex >= testCases.length) {
     assert(_environment.currentTestCaseIndex == testCases.length);
     _completeTests();
   } else {
     var testCase = testCases[_environment.currentTestCaseIndex];
     Future f = runZoned(testCase._run, onError: (error, stack) {
       // TODO(kevmoo) Do a better job of flagging these are async errors.
       // https://code.google.com/p/dart/issues/detail?id=16530
       _registerException(testCase, error, stack);
     });

     var timeout = unittestConfiguration.timeout;

     Timer timer;
     if (timeout != null) {
       try {
         timer = new Timer(timeout, () {
           testCase._error("Test timed out after ${timeout.inSeconds} seconds.");
           _nextTestCase();
         });
       } on UnsupportedError catch (e) {
         if (e.message != "Timer greater than 0.") rethrow;
         // Support running on d8 and jsshell which don't support timers.
       }
     }
     f.whenComplete(() {
       if (timer != null) timer.cancel();
       var now = new DateTime.now().millisecondsSinceEpoch;
       if ((now - _environment.lastBreath) >= BREATH_INTERVAL) {
         _environment.lastBreath = now;
         Timer.run(_nextTestCase);
       } else {
         scheduleMicrotask(_nextTestCase); // Schedule the next test.
       }
     });
   }
 }

 /// Publish results on the page and notify controller.
 void _completeTests() {
   if (!_environment.initialized) return;
   int passed = 0;
   int failed = 0;
   int errors = 0;

   for (TestCase t in testCases) {
     switch (t.result) {
       case PASS:  passed++; break;
       case FAIL:  failed++; break;
       case ERROR: errors++; break;
     }
   }
   _config.onSummary(passed, failed, errors, testCases,
       _environment.uncaughtErrorMessage);
   _config.onDone(passed > 0 && failed == 0 && errors == 0 &&
       _environment.uncaughtErrorMessage == null);
   _environment.initialized = false;
   _environment.currentTestCaseIndex = -1;
 }

 String _fullSpec(String spec) {
   var group = '${_environment.currentContext.fullName}';
   if (spec == null) return group;
   return group != '' ? '$group$groupSep$spec' : spec;
 }

 /// Lazily initializes the test library if not already initialized.
 void ensureInitialized() {
   _ensureInitialized(true);
 }

 void _ensureInitialized(bool configAutoStart) {
   if (_environment.initialized) {
     return;
   }
   _environment.initialized = true;
   // Hook our async guard into the matcher library.
   wrapAsync = (f, [id]) => expectAsync(f, id: id);

   _environment.uncaughtErrorMessage = null;

   unittestConfiguration.onInit();

   if (configAutoStart && _config.autoStart) {
     // Immediately queue the suite up. It will run after a timeout (i.e. after
     // main() has returned).
     scheduleMicrotask(runTests);
   }
 }

 /// Select a solo test by ID.
 void setSoloTest(int id) => _testCases.retainWhere((t) => t.id == id);

 /// Enable/disable a test by ID.
 void _setTestEnabledState(int testId, bool state) {
   // Try fast path first.
   if (testCases.length > testId && testCases[testId].id == testId) {
     testCases[testId]._enabled = state;
   } else {
     for (var i = 0; i < testCases.length; i++) {
       if (testCases[i].id == testId) {
         testCases[i]._enabled = state;
         break;
       }
     }
   }
 }

 /// Enable a test by ID.
 void enableTest(int testId) => _setTestEnabledState(testId, true);

 /// Disable a test by ID.
 void disableTest(int testId) => _setTestEnabledState(testId, false);

 /// Signature for a test function.
 typedef dynamic TestFunction();

 /// A flag that controls whether we hide unittest and core library details in
 /// exception stacks.
 ///
 /// Useful to disable when debugging unittest or matcher customizations.
 bool formatStacks = true;

 /// A flag that controls whether we try to filter out irrelevant frames from
 /// the stack trace.
 ///
 /// Requires [formatStacks] to be set.
 bool filterStacks = true;

 void _requireNotRunning() {
   if (_environment.currentTestCaseIndex != -1) {
     throw new StateError('Not allowed when tests are running.');
   }
 }

 /// Method to create a test environment running in its own zone scope.
 ///
 /// This allows for multiple invocations of the unittest library in the same
 /// application instance.
 /// This is useful when, for example, creating a test runner application which
 /// needs to create a new pristine test environment on each invocation to run
 /// a given set of test.
 dynamic withTestEnvironment(callback()) {
   return runZoned(callback,
       zoneValues: {_UNITTEST_ENVIRONMENT: new _TestEnvironment()});
 }
	// Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file
	// for details. All rights reserved. Use of this source code is governed by a
	// BSD-style license that can be found in the LICENSE file.

	/// Support for writing Dart unit tests.
	///
	/// For information on installing and importing this library, see the
	/// [unittest package on pub.dartlang.org]
	/// (http://pub.dartlang.org/packages/unittest).
	///
	/// See also:
	/// [Unit Testing with Dart]
	/// (http://www.dartlang.org/articles/dart-unit-tests/)
	///
	/// ##Concepts
	///
	/// * __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`.
	///
	/// ##Examples
	///
	/// A trivial test:
	///
	/// import 'package:unittest/unittest.dart';
	/// main() {
	/// test('this is a test', () {
	/// int x = 2 + 3;
	/// expect(x, equals(5));
	/// });
	/// }
	///
	/// Multiple tests:
	///
	/// import 'package:unittest/unittest.dart';
	/// 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';
	/// 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...
	/// var timer = 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]
	/// Timer.run(callback);
	/// Timer.run(callback);
	/// });
	/// }
	///
	/// 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));
	/// });
	/// });
	/// }
	library unittest;

	import 'dart:async';
	import 'dart:collection';
	import 'dart:isolate';

	import 'package:matcher/matcher.dart' show DefaultFailureHandler,
	configureExpectFailureHandler, TestFailure, wrapAsync;
	export 'package:matcher/matcher.dart';

	import 'src/utils.dart';

	import 'src/configuration.dart';
	export 'src/configuration.dart';

	part 'src/simple_configuration.dart';
	part 'src/group_context.dart';
	part 'src/spread_args_helper.dart';
	part 'src/test_case.dart';
	part 'src/test_environment.dart';

	const Symbol _UNITTEST_ENVIRONMENT = #unittest.environment;

	final _TestEnvironment _defaultEnvironment = new _TestEnvironment();

	/**
	* Internal getter for the current unittest config.
	*/
	_TestEnvironment get _environment {
	var environment = Zone.current[_UNITTEST_ENVIRONMENT];
	if (environment == null) return _defaultEnvironment;
	return environment;
	}

	// Convenience getter for the current environment's config.
	Configuration get _config => _environment.config;

	// Convenience setter for the current environment's config.
	void set _config(Configuration config) {
	_environment.config = config;
	}

	// Convenience getter for the current environment's test cases.
	List<TestCase> get _testCases => _environment.testCases;

	/// [Configuration] used by the unittest library.
	///
	/// Note that if a configuration has not been set, calling this getter will
	/// create a default configuration.
	Configuration get unittestConfiguration {
	if (_config == null) {
	_config = new Configuration();
	}
	return _config;
	}

	/// Sets the [Configuration] used by the unittest library.
	///
	/// Throws a [StateError] if there is an existing, incompatible value.
	void set unittestConfiguration(Configuration value) {
	if (!identical(_config, value)) {
	if (_config != null) {
	logMessage('Warning: The unittestConfiguration has already been set. New '
	'unittestConfiguration ignored.');
	} else {
	_config = value;
	}
	}
	}

	/// Can be called by tests to log status. Tests should use this
	/// instead of [print].
	void logMessage(String message) =>
	_config.onLogMessage(currentTestCase, message);

	/// Separator used between group names and test names.
	String groupSep = ' ';

	/// Tests executed in this suite.
	List<TestCase> get testCases =>
	new UnmodifiableListView<TestCase>(_environment.testCases);

	/// Interval (in msecs) after which synchronous tests will insert an async
	/// delay to allow DOM or other updates.
	const int BREATH_INTERVAL = 200;

	/// [TestCase] currently being executed.
	TestCase get currentTestCase =>
	(_environment.currentTestCaseIndex >= 0 &&
	_environment.currentTestCaseIndex < testCases.length)
	? testCases[_environment.currentTestCaseIndex]
	: null;

	/* Test case result strings. */
	// TODO(gram) we should change these constants to use a different string
	// (so that writing 'FAIL' in the middle of a test doesn't
	// imply that the test fails). We can't do it without also changing
	// the testrunner and test.dart though.
	/// Result string for a passing test case.
	const PASS = 'pass';
	/// Result string for a failing test case.
	const FAIL = 'fail';
	/// Result string for an test case with an error.
	const ERROR = 'error';

	/// Creates a new test case with the given description and body. The
	/// description will include the descriptions of any surrounding group()
	/// calls.
	void test(String spec, TestFunction body) {
	_requireNotRunning();
	ensureInitialized();
	if (!_environment.soloTestSeen \|\| _environment.soloNestingLevel > 0) {
	var testcase = new TestCase._internal(testCases.length + 1, _fullSpec(spec),
	body);
	_testCases.add(testcase);
	}
	}

	/// Convenience function for skipping a test.
	void skip_test(String spec, TestFunction body) {}

	/// Creates a new test case with the given description and body. The
	/// description will include the descriptions of any surrounding group()
	/// calls.
	///
	/// If we use [solo_test] (or [solo_group]) instead of test, then all non-solo
	/// tests will be disabled. Note that if we use [solo_group], all tests in
	/// the group will be enabled, regardless of whether they use [test] or
	/// [solo_test], or whether they are in a nested [group] vs [solo_group]. Put
	/// another way, if there are any calls to [solo_test] or [solo_group] in a test
	/// file, all tests that are not inside a [solo_group] will be disabled unless
	/// they are [solo_test]s.
	///
	/// [skip_test] and [skip_group] take precedence over soloing, by virtue of the
	/// fact that they are effectively no-ops.
	void solo_test(String spec, TestFunction body) {
	_requireNotRunning();
	ensureInitialized();
	if (!_environment.soloTestSeen) {
	_environment.soloTestSeen = true;
	// This is the first solo-ed test. Discard all tests up to now.
	_testCases.clear();
	}
	++_environment.soloNestingLevel;
	try {
	test(spec, body);
	} finally {
	--_environment.soloNestingLevel;
	}
	}

	/// Indicate that [callback] is expected to be called a [count] number of times
	/// (by default 1).
	///
	/// The unittest framework will wait for the callback to run the
	/// specified [count] times before it continues with the following test. Using
	/// [expectAsync] will also ensure that errors that occur within [callback] are
	/// tracked and reported. [callback] should take 0 positional arguments (named
	/// arguments are not supported). [id] can be used to provide more
	/// descriptive error messages if the callback is called more often than
	/// expected.
	///
	/// [max] can be used to specify an upper bound on the number of
	/// calls; if this is exceeded the test will fail (or be marked as in error if
	/// it was already complete). A value of 0 for [max] (the default) will set
	/// the upper bound to the same value as [count]; i.e. the callback should be
	/// called exactly [count] times. A value of -1 for [max] will mean no upper
	/// bound.
	///
	/// [reason] is optional and is typically not supplied, as a reason is generated
	/// by the unittest package; if reason is included it is appended to the
	/// generated reason.
	Function expectAsync(Function callback,
	{int count: 1, int max: 0, String id, String reason}) =>
	new _SpreadArgsHelper(callback, count, max, id, reason).func;

	/// Indicate that [callback] is expected to be called until [isDone] returns
	/// true.
	///
	/// The unittest framework checks [isDone] after each callback and only
	/// when it returns true will it continue with the following test. Using
	/// [expectAsyncUntil] will also ensure that errors that occur within
	/// [callback] are tracked and reported. [callback] should take 0 positional
	/// arguments (named arguments are not supported). [id] can be used to
	/// identify the callback in error messages (for example if it is called
	/// after the test case is complete).
	///
	/// [reason] is optional and is typically not supplied, as a reason is generated
	/// by the unittest package; if reason is included it is appended to the
	/// generated reason.
	Function expectAsyncUntil(Function callback, bool isDone(),
	{String id, String reason}) =>
	new _SpreadArgsHelper(callback, 0, -1, id, reason, isDone: isDone).func;

	/// Creates a new named group of tests.
	///
	/// Calls to group() or test() within the body of the function passed to this
	/// named group will inherit this group's description.
	void group(String description, void body()) {
	ensureInitialized();
	_requireNotRunning();
	_environment.currentContext =
	new _GroupContext(_environment.currentContext, description);
	try {
	body();
	} catch (e, trace) {
	var stack = (trace == null) ? '' : ': ${trace.toString()}';
	_environment.uncaughtErrorMessage = "${e.toString()}$stack";
	} finally {
	// Now that the group is over, restore the previous one.
	_environment.currentContext = _environment.currentContext.parent;
	}
	}

	/// Like [skip_test], but for groups.
	void skip_group(String description, void body()) {}

	/// Like [solo_test], but for groups.
	void solo_group(String description, void body()) {
	_requireNotRunning();
	ensureInitialized();
	if (!_environment.soloTestSeen) {
	_environment.soloTestSeen = true;
	// This is the first solo-ed group. Discard all tests up to now.
	_testCases.clear();
	}
	++_environment.soloNestingLevel;
	try {
	group(description, body);
	} finally {
	--_environment.soloNestingLevel;
	}
	}

	/// Register a [setUp] function for a test [group].
	///
	/// This function will be called before each test in the group is run.
	/// [setUp] and [tearDown] should be called within the [group] before any
	/// calls to [test]. The [setupTest] function can be asynchronous; in this
	/// case it must return a [Future].
	void setUp(Function setupTest) {
	_requireNotRunning();
	_environment.currentContext.testSetup = setupTest;
	}

	/// Register a [tearDown] function for a test [group].
	///
	/// This function will be called after each test in the group is run.
	///
	/// Note that if groups are nested only the most locally scoped [teardownTest]
	/// function will be run. [setUp] and [tearDown] should be called within the
	/// [group] before any calls to [test]. The [teardownTest] function can be
	/// asynchronous; in this case it must return a [Future].
	void tearDown(Function teardownTest) {
	_requireNotRunning();
	_environment.currentContext.testTeardown = teardownTest;
	}

	/// Advance to the next test case.
	void _nextTestCase() {
	_environment.currentTestCaseIndex++;
	_runTest();
	}

	/// Handle errors that happen outside the tests.
	// TODO(vsm): figure out how to expose the stack trace here
	// Currently e.message works in dartium, but not in dartc.
	void handleExternalError(e, String message, [stack]) {
	var msg = '$message\nCaught $e';

	if (currentTestCase != null) {
	currentTestCase._error(msg, stack);
	} else {
	_environment.uncaughtErrorMessage = "$msg: $stack";
	}
	}

	/// Filter the tests by [testFilter].
	///
	/// [testFilter] can be a [RegExp], a [String] or a
	/// predicate function. This is different from enabling or disabling tests
	/// in that it removes the tests completely.
	void filterTests(testFilter) {
	var filterFunction;
	if (testFilter is String) {
	RegExp re = new RegExp(testFilter);
	filterFunction = (t) => re.hasMatch(t.description);
	} else if (testFilter is RegExp) {
	filterFunction = (t) => testFilter.hasMatch(t.description);
	} else if (testFilter is Function) {
	filterFunction = testFilter;
	}
	_testCases.retainWhere(filterFunction);
	}

	/// Runs all queued tests, one at a time.
	void runTests() {
	_requireNotRunning();
	_ensureInitialized(false);
	_environment.currentTestCaseIndex = 0;
	_config.onStart();
	_runTest();
	}

	/// Registers that an exception was caught for the current test.
	void registerException(e, [trace]) {
	_registerException(currentTestCase, e, trace);
	}

	/// Registers that an exception was caught for the current test.
	void _registerException(TestCase testCase, e, [trace]) {
	String message = (e is TestFailure) ? e.message : 'Caught $e';
	if (testCase.result == null) {
	testCase._fail(message, trace);
	} else {
	testCase._error(message, trace);
	}
	}

	/// Runs the next test.
	void _runTest() {
	if (_environment.currentTestCaseIndex >= testCases.length) {
	assert(_environment.currentTestCaseIndex == testCases.length);
	_completeTests();
	} else {
	var testCase = testCases[_environment.currentTestCaseIndex];
	Future f = runZoned(testCase._run, onError: (error, stack) {
	// TODO(kevmoo) Do a better job of flagging these are async errors.
	// https://code.google.com/p/dart/issues/detail?id=16530
	_registerException(testCase, error, stack);
	});

	var timeout = unittestConfiguration.timeout;

	Timer timer;
	if (timeout != null) {
	try {
	timer = new Timer(timeout, () {
	testCase._error("Test timed out after ${timeout.inSeconds} seconds.");
	_nextTestCase();
	});
	} on UnsupportedError catch (e) {
	if (e.message != "Timer greater than 0.") rethrow;
	// Support running on d8 and jsshell which don't support timers.
	}
	}
	f.whenComplete(() {
	if (timer != null) timer.cancel();
	var now = new DateTime.now().millisecondsSinceEpoch;
	if ((now - _environment.lastBreath) >= BREATH_INTERVAL) {
	_environment.lastBreath = now;
	Timer.run(_nextTestCase);
	} else {
	scheduleMicrotask(_nextTestCase); // Schedule the next test.
	}
	});
	}
	}

	/// Publish results on the page and notify controller.
	void _completeTests() {
	if (!_environment.initialized) return;
	int passed = 0;
	int failed = 0;
	int errors = 0;

	for (TestCase t in testCases) {
	switch (t.result) {
	case PASS: passed++; break;
	case FAIL: failed++; break;
	case ERROR: errors++; break;
	}
	}
	_config.onSummary(passed, failed, errors, testCases,
	_environment.uncaughtErrorMessage);
	_config.onDone(passed > 0 && failed == 0 && errors == 0 &&
	_environment.uncaughtErrorMessage == null);
	_environment.initialized = false;
	_environment.currentTestCaseIndex = -1;
	}

	String _fullSpec(String spec) {
	var group = '${_environment.currentContext.fullName}';
	if (spec == null) return group;
	return group != '' ? '$group$groupSep$spec' : spec;
	}

	/// Lazily initializes the test library if not already initialized.
	void ensureInitialized() {
	_ensureInitialized(true);
	}

	void _ensureInitialized(bool configAutoStart) {
	if (_environment.initialized) {
	return;
	}
	_environment.initialized = true;
	// Hook our async guard into the matcher library.
	wrapAsync = (f, [id]) => expectAsync(f, id: id);

	_environment.uncaughtErrorMessage = null;

	unittestConfiguration.onInit();

	if (configAutoStart && _config.autoStart) {
	// Immediately queue the suite up. It will run after a timeout (i.e. after
	// main() has returned).
	scheduleMicrotask(runTests);
	}
	}

	/// Select a solo test by ID.
	void setSoloTest(int id) => _testCases.retainWhere((t) => t.id == id);

	/// Enable/disable a test by ID.
	void _setTestEnabledState(int testId, bool state) {
	// Try fast path first.
	if (testCases.length > testId && testCases[testId].id == testId) {
	testCases[testId]._enabled = state;
	} else {
	for (var i = 0; i < testCases.length; i++) {
	if (testCases[i].id == testId) {
	testCases[i]._enabled = state;
	break;
	}
	}
	}
	}

	/// Enable a test by ID.
	void enableTest(int testId) => _setTestEnabledState(testId, true);

	/// Disable a test by ID.
	void disableTest(int testId) => _setTestEnabledState(testId, false);

	/// Signature for a test function.
	typedef dynamic TestFunction();

	/// A flag that controls whether we hide unittest and core library details in
	/// exception stacks.
	///
	/// Useful to disable when debugging unittest or matcher customizations.
	bool formatStacks = true;

	/// A flag that controls whether we try to filter out irrelevant frames from
	/// the stack trace.
	///
	/// Requires [formatStacks] to be set.
	bool filterStacks = true;

	void _requireNotRunning() {
	if (_environment.currentTestCaseIndex != -1) {
	throw new StateError('Not allowed when tests are running.');
	}
	}

	/// Method to create a test environment running in its own zone scope.
	///
	/// This allows for multiple invocations of the unittest library in the same
	/// application instance.
	/// This is useful when, for example, creating a test runner application which
	/// needs to create a new pristine test environment on each invocation to run
	/// a given set of test.
	dynamic withTestEnvironment(callback()) {
	return runZoned(callback,
	zoneValues: {_UNITTEST_ENVIRONMENT: new _TestEnvironment()});
	}