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(); this takes a callback as the first

[Siggi Cherem (dart-lang), 2013/02/26 00:25:29]

80 col

[gram, 2013/03/04 19:51:52]

Done.

+ * 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 via an [Isolate] (for example, with Timer.run()],

[Siggi Cherem (dart-lang), 2013/02/26 00:25:29]

rephrase: 'via an [Isolate]' sounds strange.

In the browser for example Timer.run uses window.setTimout. You also have
futures for XHR requests. 

How about  'may be in voked from a top-level context'?

[gram, 2013/03/04 19:51:52]

Done.

+ * as the Future exception handler will 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());

[Siggi Cherem (dart-lang), 2013/02/26 00:25:29]

I wonder if anything depends on the old behavior here.

In dart2js this will do a setTimeout(0) -- (which I hope gets fixed soon), but
that will be at the beginning of the next eventloop. The old logic with ports
was guaranteed to be at the end of the same event-loop. 

[gram, 2013/03/04 19:51:52]

I've run all tests in vm (checked/unchecked) and all unchecked in dart2js/d8 and
dart2js/drt, plus quite a few in dart2js/drt checked, with no issues.

 }
 
 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();