Revert r21707 "unittest: big cleanup, tightened test semantics"

pkg/unittest/lib/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.
 
 /**
  * A library for writing dart unit tests.
  *
  * To import this library, install the
  * [unittest package](http://pub.dartlang.org/packages/unittest) via the pub
  * package manager. See the [Getting Started](http://pub.dartlang.org/doc)
@@ skipping 193 matching lines @@
 // TODO(nweiz): present an unmodifiable view of this once issue 8321 is fixed.
 /** Tests executed in this suite. */
 final List<TestCase> testCases = new List<TestCase>();
 
 /** Setup function called before each test in a group */
 Function _testSetup;
 
 /** Teardown function called after each test in a group */
 Function _testTeardown;
 
-TestCase _currentTestCase = null;
+int _currentTestCaseIndex = 0;
 
 /** [TestCase] currently being executed. */
-TestCase get currentTestCase => _currentTestCase;
+TestCase get currentTestCase =>
+    (_currentTestCaseIndex >= 0 && _currentTestCaseIndex < testCases.length)
+        ? testCases[_currentTestCaseIndex]
+        : null;
 
 /** Whether the framework is in an initialized state. */
 bool _initialized = false;
 
 String _uncaughtErrorMessage = 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
@@ skipping 54 matching lines @@
 }
 
 /** Simulates spread arguments using named arguments. */
 // TODO(sigmund): remove this class and simply use a closure with named
 // arguments (if still applicable).
 class _SpreadArgsHelper {
   final Function callback;
   final int minExpectedCalls;
   final int maxExpectedCalls;
   final Function isDone;
-  final TestCase testCase;
+  final int testNum;
   final String id;
   int actualCalls = 0;
+  TestCase testCase;
   bool complete;
   static const sentinel = const _Sentinel();
 
   _SpreadArgsHelper(Function callback, int minExpected, int maxExpected,
       Function isDone, String id)
       : this.callback = callback,
         minExpectedCalls = minExpected,
         maxExpectedCalls = (maxExpected == 0 && minExpected > 0)
             ? minExpected
             : maxExpected,
         this.isDone = isDone,
-        this.testCase = currentTestCase,
+        testNum = _currentTestCaseIndex,
         this.id = _makeCallbackId(id, callback) {
-    if(testCase == null) {
-      throw new StateError("No valid test, did you forget to run your test "
-          "inside a call to test()?");
+    ensureInitialized();
+    if (!(_currentTestCaseIndex >= 0 &&
+           _currentTestCaseIndex < testCases.length &&
+           testCases[_currentTestCaseIndex] != null)) {
+      print("No valid test, did you forget to run your test inside a call "
+          "to test()?");
     }
-
+    assert(_currentTestCaseIndex >= 0 &&
+           _currentTestCaseIndex < testCases.length &&
+           testCases[_currentTestCaseIndex] != null);
+    testCase = testCases[_currentTestCaseIndex];
     if (isDone != null || minExpected > 0) {
       testCase._callbackFunctionsOutstanding++;
       complete = false;
     } else {
       complete = true;
     }
   }
 
   static _makeCallbackId(String id, Function callback) {
     // Try to create a reasonable id.
@@ skipping 63 matching lines @@
         return callback(arg0, arg1, arg2);
       } else if (arg4 == sentinel) {
         return callback(arg0, arg1, arg2, arg3);
       } else {
         testCase.error(
            'unittest lib does not support callbacks with more than'
               ' 4 arguments.',
            '');
       }
     },
-    after, testCase);
+    after, testNum);
   }
 
   invoke0() {
     return _guardAsync(
         () {
           if (shouldCallBack()) {
             return callback();
           }
         },
-        after, testCase);
+        after, testNum);
   }
 
   invoke1(arg1) {
     return _guardAsync(
         () {
           if (shouldCallBack()) {
             return callback(arg1);
           }
         },
-        after, testCase);
+        after, testNum);
   }
 
   invoke2(arg1, arg2) {
     return _guardAsync(
         () {
           if (shouldCallBack()) {
             return callback(arg1, arg2);
           }
         },
-        after, testCase);
+        after, testNum);
   }
 }
 
 /**
  * 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 between 0 and 4 positional
+ * arguments (named arguments are not supported here). [id] can be used
+ * to provide more descriptive error messages if the callback is called more
+ * often than expected.
+ */
+Function _expectAsync(Function callback,
+                     {int count: 1, int max: 0, String id}) {
+  return new _SpreadArgsHelper(callback, count, max, null, id).invoke;
+}
+
+/**
+ * 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
  * [expectAsync0] 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.
@@ skipping 13 matching lines @@
 
 /** Like [expectAsync0] but [callback] should take 2 positional arguments. */
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
 Function expectAsync2(Function callback,
                      {int count: 1, int max: 0, String id}) {
   return new _SpreadArgsHelper(callback, count, max, null, id).invoke2;
 }
 
 /**
  * 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 between 0 and
+ * 4 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).
+ */
+Function _expectAsyncUntil(Function callback, Function isDone, {String id}) {
+  return new _SpreadArgsHelper(callback, 0, -1, isDone, id).invoke;
+}
+
+/**
+ * Indicate that [callback] is expected to be called until [isDone] returns
  * true. The unittest framework check [isDone] after each callback and only
  * when it returns true will it continue with the following test. Using
  * [expectAsyncUntil0] 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).
  */
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
 Function expectAsyncUntil0(Function callback, Function isDone, {String id}) {
@@ skipping 14 matching lines @@
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
 Function expectAsyncUntil2(Function callback, Function isDone, {String id}) {
   return new _SpreadArgsHelper(callback, 0, -1, isDone, id).invoke2;
 }
 
 /**
  * Wraps the [callback] in a new function and returns that function. The new
  * function will be able to handle exceptions by directing them to the correct
  * test. This is thus similar to expectAsync0. Use it to wrap any callbacks that
  * might optionally be called but may never be called during the test.
+ * [callback] should take between 0 and 4 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).
+ */
+Function _protectAsync(Function callback, {String id}) {
+  return new _SpreadArgsHelper(callback, 0, -1, null, id).invoke;
+}
+
+/**
+ * Wraps the [callback] in a new function and returns that function. The new
+ * function will be able to handle exceptions by directing them to the correct
+ * test. This is thus similar to expectAsync0. Use it to wrap any callbacks that
+ * might optionally be called but may never be called during the test.
  * [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).
  */
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
 Function protectAsync0(Function callback, {String id}) {
   return new _SpreadArgsHelper(callback, 0, -1, null, id).invoke0;
 }
 
 /**
@@ skipping 50 matching lines @@
 
 /**
  * Register a [setUp] function for a test [group]. This function will
  * be called before each test in the group is run. Note that if groups
  * are nested only the most locally scoped [setUpTest] function will be 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();
   _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();
   _testTeardown = teardownTest;
 }
 
+/** Advance to the next test case. */
+void _nextTestCase() {
+  _defer(() {
+    _currentTestCaseIndex++;
+    _nextBatch();
+  });
+}
+
 /**
  * Utility function that can be used to notify the test framework that an
  *  error was caught outside of this library.
  */
 void _reportTestError(String msg, String trace) {
- if (currentTestCase != null) {
-   currentTestCase.error(msg, trace);
+ if (_currentTestCaseIndex < testCases.length) {
+    final testCase = testCases[_currentTestCaseIndex];
+    testCase.error(msg, trace);
   } else {
     _uncaughtErrorMessage = "$msg: $trace";
   }
 }
 
+/**
+ * Runs [callback] at the end of the event loop. Note that we don't wrap
+ * the callback in guardAsync; this is for test framework functions which
+ * should not be throwing unexpected exceptions that end up failing test
+ * cases! Furthermore, we need the final exception to be thrown but not
+ * caught by the test framework if any test cases failed. However, tests
+ * that make use of a similar defer function *should* wrap the callback
+ * (as we do in unitttest_test.dart).
+ */
+_defer(void callback()) {
+  (new Future.value()).then((_) => callback());
+}
+
 void rerunTests() {
-  assert(_uncaughtErrorMessage == null);
+  _uncaughtErrorMessage = null;
+  _initialized = true; // We don't want to reset the test array.
   runTests();
 }
 
 /**
  * Filter the tests. [testFilter] can be a [RegExp], a [String] or a
  * predicate function. This is different to enabling/disabling tests
  * in that it removes the tests completely.
  */
 void filterTests(testFilter) {
-  _requireNotRunning();
-  Function filterFunction;
+  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() {
   _ensureInitialized(false);
-  assert(_currentTestCase == null);
-
+  _currentTestCaseIndex = 0;
   _currentGroup = '';
 
   // If we are soloing a test, remove all the others.
   if (_soloTest != null) {
     filterTests((t) => t == _soloTest);
   }
 
   _config.onStart();
 
-  new Future(_nextBatch);
+  _defer(() {
+    _nextBatch();
+  });
 }
 
 /**
  * Run [tryBody] guarded in a try-catch block. If an exception is thrown, it is
  * passed to the corresponding test.
  *
  * The value returned by [tryBody] (if any) is returned by [guardAsync].
  */
 guardAsync(Function tryBody) {
-  return _guardAsync(tryBody, null, currentTestCase);
+  return _guardAsync(tryBody, null, _currentTestCaseIndex);
 }
 
-_guardAsync(Function tryBody, Function finallyBody, TestCase testCase) {
-  assert(testCase != null);
+_guardAsync(Function tryBody, Function finallyBody, int testNum) {
+  assert(testNum >= 0);
   try {
     return tryBody();
   } catch (e, trace) {
-    _registerException(testCase, e, trace);
+    _registerException(testNum, e, trace);
   } finally {
     if (finallyBody != null) finallyBody();
   }
 }
 
 /**
  * Registers that an exception was caught for the current test.
  */
 void registerException(e, [trace]) {
-  _registerException(currentTestCase, e, trace);
+  _registerException(_currentTestCaseIndex, e, trace);
 }
 
 /**
  * Registers that an exception was caught for the current test.
  */
-void _registerException(TestCase testCase, e, [trace]) {
-  assert(testCase != null);
+void _registerException(testNum, e, [trace]) {
   trace = trace == null ? '' : trace.toString();
   String message = (e is TestFailure) ? e.message : 'Caught $e';
-  if (testCase.result == null) {
-    testCase.fail(message, trace);
+  if (testCases[testNum].result == null) {
+    testCases[testNum].fail(message, trace);
   } else {
-    testCase.error(message, trace);
+    testCases[testNum].error(message, trace);
   }
 }
 
 /**
- * Executes tests in order starting with the provided index.
- * If a test is synchronous, the following test is executed immediately
- * For asynchronous tests, a Future is returned which completes with _nextBatch
- * starting at the next index.
- * Future.forEach is explicitly not used because it slows down synchronous tests
- * noticeably
+ * Runs a batch of tests, yielding whenever an asynchronous test starts
+ * running. Tests will resume executing when such asynchronous test calls
+ * [done] or if it fails with an exception.
  */
-Future _nextBatch([int index = 0]) {
-  for(int i = index; i < testCases.length; i++) {
-    _currentTestCase = testCases[i];
-
-    Future f = guardAsync(_currentTestCase._run);
-
-    if(f != null) {
-      return f.then((_) => _nextBatch(i + 1));
+void _nextBatch() {
+  while (true) {
+    if (_currentTestCaseIndex >= testCases.length) {
+      _completeTests();
+      break;
     }
+    final testCase = testCases[_currentTestCaseIndex];
+    var f = _guardAsync(testCase._run, null, _currentTestCaseIndex);
+    if (f != null) {
+      f.whenComplete(() {
+        _nextTestCase(); // Schedule the next test.
+      });
+      break;
+    }
+    _currentTestCaseIndex++;
   }
-  _currentTestCase = null;
-  return new Future(_completeTests);
 }
 
 /** Publish results on the page and notify controller. */
 void _completeTests() {
-  assert(_initialized);
-  assert(_currentTestCase == null);
-
+  if (!_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, _uncaughtErrorMessage);
   _config.onDone(passed > 0 && failed == 0 && errors == 0 &&
       _uncaughtErrorMessage == null);
-
-  _uncaughtErrorMessage = null;
+  _initialized = false;
 }
 
 String _fullSpec(String spec) {
   if (spec == null) return '$_currentGroup';
   return _currentGroup != '' ? '$_currentGroup$groupSep$spec' : spec;
 }
 
 /**
  * Lazily initializes the test library if not already initialized.
  */
 void ensureInitialized() {
   _ensureInitialized(true);
 }
 
-void _requireNotRunning() {
-  if(_currentTestCase != null) {
-    throw new StateError("A forbidden operation occured "
-        "while tests were running");
-  }
-}
-
 void _ensureInitialized(bool configAutoStart) {
-  _requireNotRunning();
   if (_initialized) {
     return;
   }
   _initialized = true;
   // Hook our async guard into the matcher library.
   wrapAsync = (f, [id]) => expectAsync1(f, id: id);
 
   _uncaughtErrorMessage = null;
 
   if (_config == null) {
     unittestConfiguration = new Configuration();
   }
   _config.onInit();
 
   if (configAutoStart && _config.autoStart) {
     // Immediately queue the suite up. It will run after a timeout (i.e. after
     // main() has returned).
-    new Future(runTests);
+    _defer(runTests);
   }
 }
 
 /** Select a solo test by ID. */
 void setSoloTest(int id) {
   for (var i = 0; i < testCases.length; i++) {
     if (testCases[i].id == id) {
       _soloTest = testCases[i];
       break;
     }
@@ skipping 16 matching lines @@
 }
 
 /** 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();