Add testing resources from SkyDart branch

sky/tests/resources/third_party/unittest/unittest.dart

+// 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.
+
+library unittest;
+
+import 'dart:async';
+import 'dart:collection';
+
+import '../matcher/matcher.dart' show TestFailure, wrapAsync;
+
+import 'src/configuration.dart';
+import 'src/expected_function.dart';
+import 'src/group_context.dart';
+import 'src/internal_test_case.dart';
+import 'src/test_case.dart';
+import 'src/test_environment.dart';
+
+export '../matcher/matcher.dart';
+
+export 'src/configuration.dart';
+export 'src/simple_configuration.dart';
+export 'src/test_case.dart';
+
+/// The signature for a function passed to [test].
+typedef dynamic TestFunction();
+
+/// [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) environment.config = new Configuration();
+  return config;
+}
+
+/// If `true`, stack traces are reformatted to be more readable.
+bool formatStacks = true;
+
+/// If `true`, irrelevant frames are filtered from the stack trace.
+///
+/// This does nothing if [formatStacks] is false.
+bool filterStacks = true;
+
+/// Separator used between group names and test names.
+String groupSep = ' ';
+
+/// 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)) return;
+  if (config != null) {
+    logMessage('Warning: The unittestConfiguration has already been set. New '
+        'unittestConfiguration ignored.');
+  } else {
+    environment.config = value;
+  }
+}
+
+/// Logs [message] associated with the current test case.
+///
+/// Tests should use this instead of [print].
+void logMessage(String message) =>
+    config.onLogMessage(currentTestCase, message);
+
+/// The test cases that have been defined so far.
+List<TestCase> get testCases =>
+    new UnmodifiableListView<TestCase>(environment.testCases);
+
+/// The interval (in milliseconds) after which a non-microtask asynchronous
+/// delay will be scheduled between tests.
+///
+/// This is used to avoid starving the DOM or other non-microtask events.
+const int BREATH_INTERVAL = 200;
+
+/// The [TestCase] currently being executed.
+TestCase get currentTestCase => (environment.currentTestCaseIndex >= 0 &&
+        environment.currentTestCaseIndex < testCases.length)
+    ? testCases[environment.currentTestCaseIndex]
+    : null;
+
+/// The same as [currentTestCase], but typed as an [InternalTestCase].
+InternalTestCase get _currentTestCase => currentTestCase as InternalTestCase;
+
+/// The result string for a passing test case.
+const PASS = 'pass';
+
+/// The result string for a failing test case.
+const FAIL = 'fail';
+
+/// The 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 be added to the descriptions of any surrounding
+/// [group]s.
+void test(String description, TestFunction body) {
+  _requireNotRunning();
+  ensureInitialized();
+
+  if (environment.soloTestSeen && environment.soloNestingLevel == 0) return;
+  var testCase = new InternalTestCase(
+      testCases.length + 1, _fullDescription(description), body);
+  environment.testCases.add(testCase);
+}
+
+/// Returns [description] with all of its group prefixes prepended.
+String _fullDescription(String description) {
+  var group = environment.currentContext.fullName;
+  if (description == null) return group;
+  return group != '' ? '$group$groupSep$description' : description;
+}
+
+/// A convenience function for skipping a test.
+void skip_test(String spec, TestFunction body) {}
+
+/// Creates a new test case with the given description and body.
+///
+/// If [solo_test] is used instead of [test], then all non-solo tests will be
+/// disabled. Note that if [solo_group] is used as well, 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] versus [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.
+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.
+    environment.testCases.clear();
+  }
+  environment.soloNestingLevel++;
+  try {
+    test(spec, body);
+  } finally {
+    environment.soloNestingLevel--;
+  }
+}
+
+/// Indicate that [callback] is expected to be called [count] number of times
+/// (by default 1).
+///
+/// The unittest framework will wait for the callback to run the [count] times
+/// before it considers the current test to be complete. Using [expectAsync]
+/// will also ensure that errors that occur within [callback] are tracked and
+/// reported. [callback] may take up to six optional or required positional
+/// arguments; named arguments are not supported.
+///
+/// [max] can be used to specify an upper bound on the number of calls; if this
+/// is exceeded the test will fail. If [max] is `0` (the default), the callback
+/// is expected to be called exactly [count] times. If [max] is `-1`, the
+/// callback is allowed to be called any number of times greater than [count].
+///
+/// Both [id] and [reason] are optional and provide extra information about the
+/// callback when debugging. [id] should be the name of the callback, while
+/// [reason] should be the reason the callback is expected to be called.
+Function expectAsync(Function callback,
+    {int count: 1, int max: 0, String id, String reason}) =>
+        new ExpectedFunction(callback, count, max, id: id, reason: reason).func;
+
+/// Indicate that [callback] is expected to be called until [isDone] returns
+/// true.
+///
+/// [isDone] is called after each time the function is run. Only when it returns
+/// true will the callback be considered complete. Using [expectAsyncUntil] will
+/// also ensure that errors that occur within [callback] are tracked and
+/// reported. [callback] may take up to six optional or required positional
+/// arguments; named arguments are not supported.
+///
+/// Both [id] and [reason] are optional and provide extra information about the
+/// callback when debugging. [id] should be the name of the callback, while
+/// [reason] should be the reason the callback is expected to be called.
+Function expectAsyncUntil(Function callback, bool isDone(),
+    {String id, String reason}) => new ExpectedFunction(callback, 0, -1,
+        id: id, reason: reason, isDone: isDone).func;
+
+/// Creates a group of tests.
+///
+/// A group's description is included in the descriptions of any tests or
+/// sub-groups it contains. [setUp] and [tearDown] are also scoped to the
+/// containing group.
+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;
+  }
+}
+
+/// A convenience function for skipping a group of tests.
+void skip_group(String description, void body()) {}
+
+/// Creates a group of tests.
+///
+/// If [solo_group] is used instead of [group], then all tests not declared with
+/// [solo_test] or in a [solo_group] will be disabled. Note that all tests in a
+/// [solo_group] will be run, regardless of whether they're declared with [test]
+/// or [solo_test].
+///
+/// [skip_test] and [skip_group] take precedence over [solo_group].
+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.
+    environment.testCases.clear();
+  }
+  ++environment.soloNestingLevel;
+  try {
+    group(description, body);
+  } finally {
+    --environment.soloNestingLevel;
+  }
+}
+
+/// Registers a function to be run before tests.
+///
+/// This function will be called before each test is run. [callback] may be
+/// asynchronous; if so, it must return a [Future].
+///
+/// If this is called within a test group, it applies only to tests in that
+/// group. [callback] will be run after any set-up callbacks in parent groups or
+/// at the top level.
+void setUp(Function callback) {
+  _requireNotRunning();
+  environment.currentContext.testSetUp = callback;
+}
+
+/// Registers a function to be run after tests.
+///
+/// This function will be called after each test is run. [callback] may be
+/// asynchronous; if so, it must return a [Future].
+///
+/// If this is called within a test group, it applies only to tests in that
+/// group. [callback] will be run before any tear-down callbacks in parent groups or
+/// at the top level.
+void tearDown(Function callback) {
+  _requireNotRunning();
+  environment.currentContext.testTearDown = callback;
+}
+
+/// Advance to the next test case.
+void _nextTestCase() {
+  environment.currentTestCaseIndex++;
+  _runTest();
+}
+
+/// Handle an error that occurs outside of any test.
+void handleExternalError(e, String message, [stackTrace]) {
+  var msg = '$message\nCaught $e';
+
+  if (currentTestCase != null) {
+    _currentTestCase.error(msg, stackTrace);
+  } else {
+    environment.uncaughtErrorMessage = "$msg: $stackTrace";
+  }
+}
+
+/// Remove any tests that match [testFilter].
+///
+/// [testFilter] can be a predicate function, a [RegExp], or a [String]. If it's
+/// a function, it's called with each [TestCase]. If it's a [String], it's
+/// parsed as a [RegExp] and matched against each [TestCase.description].
+///
+/// This is different from enabling or disabling tests in that it removes the
+/// tests completely.
+void filterTests(testFilter) {
+  var filterFunction;
+  if (testFilter is String) {
+    var 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;
+  }
+  environment.testCases.retainWhere(filterFunction);
+}
+
+/// Runs all queued tests, one at a time.
+void runTests() {
+  _requireNotRunning();
+  _ensureInitialized(false);
+  environment.currentTestCaseIndex = 0;
+  config.onStart();
+  _runTest();
+}
+
+/// Registers an exception that was caught for the current test.
+void registerException(error, [StackTrace stackTrace]) =>
+    _currentTestCase.registerException(error, stackTrace);
+
+/// Runs the next test.
+void _runTest() {
+  if (environment.currentTestCaseIndex >= testCases.length) {
+    assert(environment.currentTestCaseIndex == testCases.length);
+    _completeTests();
+    return;
+  }
+
+  var testCase = _currentTestCase;
+  var 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
+    testCase.registerException(error, stack);
+  });
+
+  var timer;
+  var timeout = unittestConfiguration.timeout;
+  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.
+    }
+  });
+}
+
+/// Notify the configuration that the testing has finished.
+void _completeTests() {
+  if (!environment.initialized) return;
+
+  var passed = 0;
+  var failed = 0;
+  var errors = 0;
+  for (var testCase in testCases) {
+    switch (testCase.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;
+}
+
+/// Initializes the test environment if it hasn't already been initialized.
+void ensureInitialized() {
+  _ensureInitialized(true);
+}
+
+/// Initializes the test environment.
+///
+/// If [configAutoStart] is `true`, schedule a microtask to run the tests. This
+/// microtask is expected to run after all the tests are defined.
+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();
+
+  // Immediately queue the suite up. It will run after a timeout (i.e. after
+  // main() has returned).
+  if (configAutoStart && config.autoStart) scheduleMicrotask(runTests);
+}
+
+/// Remove all tests other than the one identified by [id].
+void setSoloTest(int id) =>
+    environment.testCases.retainWhere((t) => t.id == id);
+
+/// Enable the test identified by [id].
+void enableTest(int id) => _setTestEnabledState(id, enable: true);
+
+/// Disable the test by [id].
+void disableTest(int id) => _setTestEnabledState(id, enable: false);
+
+/// Enable or disable the test identified by [id].
+void _setTestEnabledState(int id, {bool enable: true}) {
+  // Try fast path first.
+  if (testCases.length > id && testCases[id].id == id) {
+    environment.testCases[id].enabled = enable;
+  } else {
+    for (var i = 0; i < testCases.length; i++) {
+      if (testCases[i].id != id) continue;
+      environment.testCases[i].enabled = enable;
+      break;
+    }
+  }
+}
+
+/// Throws a [StateError] if tests are running.
+void _requireNotRunning() {
+  if (environment.currentTestCaseIndex == -1) return;
+  throw new StateError('Not allowed when tests are running.');
+}
+
+/// Creates 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 tests.
+withTestEnvironment(callback()) {
+  return runZoned(callback,
+      zoneValues: {#unittest.environment: new TestEnvironment()});
+}