Added ability for test cases to return Futures.

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 95 matching lines @@
  *     }
  *
  * expectAsyncX() will wrap the callback code in a try/catch handler to handle
  * exceptions (treated as test failures). 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 expectAsync0((){}) and this can be called from
  * the real callback when it is finally complete. In this case the body of the
  * callback should be protected within a call to guardAsync(); this will ensure
  * that exceptions are properly handled.
  *
+ * A variation on this is expectAsyncUntilX(), 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. 
+ * It is still important to use expectAsync/guardAsync with any parts of the
+ * test that may be invoked from a top level context (for example, with
+ * Timer.run()], as the Future exception handler may not capture exceptions
+ * in such code.
+ *
  * Note: due to some language limitations we have to use different functions
  * depending on the number of positional arguments of the callback. In the
  * future, we plan to expose a single `expectAsync` function that can be used
  * regardless of the number of positional arguments. This requires new langauge
  * features or fixes to the current spec (e.g. see
  * [Issue 2706](http://dartbug.com/2706)).
  *
  * Meanwhile, we plan to add this alternative API for callbacks of more than 2
  * arguments or that take named parameters. (this is not implemented yet,
  * but will be coming here soon).
@@ skipping 545 matching lines @@
  */
 void _reportTestError(String msg, String trace) {
  if (_currentTest < _tests.length) {
     final testCase = _tests[_currentTest];
     testCase.error(msg, trace);
   } else {
     _uncaughtErrorMessage = "$msg: $trace";
   }
 }
 
-/** Runs [callback] at the end of the event loop. */
+/**
+ * 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()) {
-  // 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.
-  final port = new ReceivePort();
-  port.receive((msg, reply) {
-    callback();
-    port.close();
-  });
-  port.toSendPort().send(null, null);
+  (new Future.immediate(null)).then((_) => callback());
 }
 
 rerunTests() {
   _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
@@ skipping 72 matching lines @@
  */
 _nextBatch() {
   while (true) {
     if (_currentTest >= _tests.length) {
       _completeTests();
       break;
     }
     final testCase = _tests[_currentTest];
     var f = guardAsync(testCase.run, null, _currentTest);
     if (f != null) {
-      f.then((_){})
-       .catchError((e) {
-        testCase.error(e.toString(), e.stackTrace);
-      })
-      .whenComplete(() {
+      f.whenComplete(() {
         _nextTestCase(); // Schedule the next test.
       });
       break;
     }
     _currentTest++;
   }
 }
 
 /** Publish results on the page and notify controller. */
 _completeTests() {
@@ skipping 77 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();