setUp/tearDown functions can now be asynchronous.

pkg/unittest/lib/unittest.dart

 // Copyright (c) 2011, 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, use the pub package manager.
  * Create a pubspec.yaml file in your project and add
  * a dependency on unittest with the following lines:
@@ skipping 311 matching lines @@
 // TODO(sigmund): remove this class and simply use a closure with named
 // arguments (if still applicable).
 class _SpreadArgsHelper {
   Function _callback;
   int _expectedCalls;
   int _actualCalls = 0;
   int _testNum;
   TestCase _testCase;
   Function _shouldCallBack;
   Function _isDone;
+  String _id;
   static const _sentinel = const _Sentinel();
 
   _init(Function callback, Function shouldCallBack, Function isDone,
        [expectedCalls = 0]) {
     ensureInitialized();
     if (!(_currentTest >= 0 &&
            _currentTest < _tests.length &&
            _tests[_currentTest] != null)) {
       print("No valid test, did you forget to run your test inside a call "
           "to test()?");
     }
     assert(_currentTest >= 0 &&
            _currentTest < _tests.length &&
            _tests[_currentTest] != null);
     _callback = callback;
     _shouldCallBack = shouldCallBack;
     _isDone = isDone;
     _expectedCalls = expectedCalls;
     _testNum = _currentTest;
     _testCase = _tests[_currentTest];
     if (expectedCalls > 0) {
       _testCase.callbackFunctionsOutstanding++;
     }
+    _id = '';
   }
 
   _SpreadArgsHelper(callback, shouldCallBack, isDone) {
     _init(callback, shouldCallBack, isDone);
   }
 
-  _SpreadArgsHelper.fixedCallCount(callback, expectedCalls) {
+  _SpreadArgsHelper.fixedCallCount(callback, expectedCalls, id) {
     _init(callback, _checkCallCount, _allCallsDone, expectedCalls);
+    if (id != null) {
+      _id = "$id ";
+    }
   }
 
   _SpreadArgsHelper.variableCallCount(callback, isDone) {
     _init(callback, _always, isDone, 1);
    }
 
   _SpreadArgsHelper.optionalCalls(callback) {
     _init(callback, _always, () => false, 0);
    }
 
   _after() {
     if (_isDone()) {
-      _handleCallbackFunctionComplete(_testNum);
+      _handleCallbackFunctionComplete(_testNum, _id);
     }
   }
 
   _allCallsDone() => _actualCalls == _expectedCalls;
 
   _always() {
     // Always run except if the test is done.
     if (_testCase.isComplete) {
       _testCase.error(
-          'Callback called after already being marked as done ($_actualCalls).',
+          'Callback ${_id}called after already being marked '
+          'as done ($_actualCalls).',
           '');
       return false;
     } else {
       return true;
     }
   }
 
   invoke([arg0 = _sentinel, arg1 = _sentinel, arg2 = _sentinel,
           arg3 = _sentinel, arg4 = _sentinel]) {
     return guardAsync(() {
@@ skipping 49 matching lines @@
           if (_shouldCallBack()) {
             return _callback(arg1, arg2);
           }
         },
         _after, _testNum);
   }
 
   /** Returns false if we exceded the number of expected calls. */
   bool _checkCallCount() {
     if (_actualCalls > _expectedCalls) {
-      _testCase.error('Callback called more times than expected '
+      _testCase.error('Callback ${_id}called more times than expected '
              '($_actualCalls > $_expectedCalls).', '');
       return false;
     }
     return true;
   }
 }
 
 /**
  * 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).
+ * 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}) {
-  return new _SpreadArgsHelper.fixedCallCount(callback, count).invoke;
+Function _expectAsync(Function callback, {int count: 1, String id}) {
+  return new _SpreadArgsHelper.
+      fixedCallCount(callback, count, 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).
+ * arguments are not supported). [id] can be used to provide more
+ * descriptive error messages if the callback is called more often than
+ * expected.
  */
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
-Function expectAsync0(Function callback, {int count: 1}) {
-  return new _SpreadArgsHelper.fixedCallCount(callback, count).invoke0;
+Function expectAsync0(Function callback, {int count: 1, String id}) {
+  return new _SpreadArgsHelper.
+      fixedCallCount(callback, count, id).invoke0;
 }
 
 /** Like [expectAsync0] but [callback] should take 1 positional argument. */
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
-Function expectAsync1(Function callback, {int count: 1}) {
-  return new _SpreadArgsHelper.fixedCallCount(callback, count).invoke1;
+Function expectAsync1(Function callback, {int count: 1, String id}) {
+  return new _SpreadArgsHelper.
+      fixedCallCount(callback, count, id).invoke1;
 }
 
 /** 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}) {
-  return new _SpreadArgsHelper.fixedCallCount(callback, count).invoke2;
+Function expectAsync2(Function callback, {int count: 1, String id}) {
+  return new _SpreadArgsHelper.
+      fixedCallCount(callback, count, 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).
  */
@@ skipping 103 matching lines @@
     // Now that the group is over, restore the previous one.
     _currentGroup = parentGroup;
     _testSetup = parentSetup;
     _testTeardown = parentTeardown;
   }
 }
 
 /**
  * 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 [setUp] function will be run.
+ * 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].
+ * calls to [test]. The [setupTest] function can be asynchronous; in this
+ * case it must return a [Future].
  */
 void setUp(Function setupTest) {
   _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 [tearDown] function will be run.
+ * 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].
+ * calls to [test]. The [teardownTest] function can be asynchronous; in this
+ * case it must return a [Future].
  */
 void tearDown(Function teardownTest) {
   _testTeardown = teardownTest;
 }
 
 /**
  * Called when one of the callback functions is done with all expected
  * calls.
  */
-void _handleCallbackFunctionComplete(testNum) {
+void _handleCallbackFunctionComplete(testNum, [id = '']) {
   // TODO (gram): we defer this to give the nextBatch recursive
   // stack a chance to unwind. This is a temporary hack but
   // really a bunch of code here needs to be fixed. We have a
   // single array that is being iterated through by nextBatch(),
   // which is recursively invoked in the case of async tests that
   // run synchronously. Bad things can then happen.
   _defer(() {
     if (_currentTest != testNum) {
-      if (_tests[testNum].result == PASS) {
-        _tests[testNum].error("Unexpected extra callbacks", '');
+      if (_tests[testNum].result == PASS &&
+          // This next test is a bit of a kludge, but saves us 
+          // adding some other way of identifying that this callback
+          // is an asyn teardown (which would have already advanced

[justinfagnani, 2013/02/08 01:36:48]

asyn -> async

[gram, 2013/02/08 17:52:24]

Done.

+          // _currentTest).
+          id != '[Async tearDown completion handler] ') {
+        _tests[testNum].error("${id}Unexpected extra callbacks", '');

[justinfagnani, 2013/02/08 01:36:48]

add space between ${id} and Unexpected?

[gram, 2013/02/08 17:52:24]

id already has a space if it is non-empty; this allows me to avoid conditional
formatting logic here.

       }
       return; // Extraneous callback.
     }
     if (_currentTest < _tests.length) {
       final testCase = _tests[_currentTest];
       --testCase.callbackFunctionsOutstanding;
       if (testCase.callbackFunctionsOutstanding < 0) {
         // TODO(gram): Check: Can this even happen?
         testCase.error(
             'More calls to _handleCallbackFunctionComplete() than expected.',
              '');
-      } else if (testCase.callbackFunctionsOutstanding == 0) {
-        if (!testCase.isComplete) {
-          testCase.pass();
-        }
-        _nextTestCase();
+      } else if (testCase.callbackFunctionsOutstanding == 0 &&
+                 !testCase.isComplete) {
+        testCase.pass();
       }
     }
   });
 }
 
 /** Advance to the next test case. */

[justinfagnani, 2013/02/08 01:36:48]

Maybe explain that the test is deferred? When I saw calls to _nextTestCase() I
wondered if they were happening too soon, before an async tearDown() was
finished

[gram, 2013/02/08 17:52:24]

I don't believe _nextTestCase can be called before an async teardown is
complete. It certainly isn't supposed to with this CL. Can you explain what made
you think that?

[justinfagnani, 2013/02/08 18:36:57]

I missed a return statement in test_case. Curious: why _defer() now?

[gram, 2013/02/08 18:43:15]

Without _defer, we can build up a very deep stack. _defer gives the stack a
chance to unwind.

 void _nextTestCase() {
-  _currentTest++;
-  _testRunner();
+  _defer(() {
+    _currentTest++;
+    _testRunner();
+  });
 }
 
 /**
  * Temporary hack: expose old API.
  * TODO(gram) remove this when WebKit tests are working with new framework
  */
 void callbackDone() {
   _handleCallbackFunctionComplete(_currentTest);
 }
 
 /**
  * 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 (_currentTest < _tests.length) {
     final testCase = _tests[_currentTest];
     testCase.error(msg, trace);
-    if (testCase.callbackFunctionsOutstanding > 0) {
-      _nextTestCase();
-    }
   } else {
     _uncaughtErrorMessage = "$msg: $trace";
   }
 }
 
 /** Runs [callback] at the end of the event loop. */
 _defer(void callback()) {
   // Exploit isolate ports as a platform-independent mechanism to queue a
   // message at the end of the event loop.
   // TODO(sigmund): expose this functionality somewhere in our libraries.
@@ skipping 72 matching lines @@
  * Registers that an exception was caught for the current test.
  */
 _registerException(testNum, e, [trace]) {
   trace = trace == null ? '' : trace.toString();
   if (_tests[testNum].result == null) {
     String message = (e is ExpectException) ? e.message : 'Caught $e';
     _tests[testNum].fail(message, trace);
   } else {
     _tests[testNum].error('Caught $e', trace);
   }
-  if (testNum == _currentTest &&
-      _tests[testNum].callbackFunctionsOutstanding > 0) {
-    _nextTestCase();
-  }
 }
 
 /**
  * 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.
  */
 _nextBatch() {
-  while (_currentTest < _tests.length) {
+  if (_currentTest >= _tests.length) {
+    _completeTests();
+  } else {
     final testCase = _tests[_currentTest];
     guardAsync(() {
       testCase.run();
       if (!testCase.isComplete && testCase.callbackFunctionsOutstanding == 0) {
         testCase.pass();
       }
     }, null, _currentTest);
-
-    if (!testCase.isComplete &&
-        testCase.callbackFunctionsOutstanding > 0) return;
-    _currentTest++;
   }
-
-  _completeTests();
 }
 
 /** Publish results on the page and notify controller. */
 _completeTests() {
   if (!_initialized) return;
   int passed = 0;
   int failed = 0;
   int errors = 0;
 
   for (TestCase t in _tests) {
@@ skipping 71 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 void TestFunction();