Removed asyncTest and improved comments.

lib/unittest/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, specify the relative path to 
  * lib/unittest/unittest.dart.
  *
  * ##Concepts##
  *
  *  * Tests: Tests are specified via the top-level function [test], they can be
  *    organized together using [group].
  *  * Checks: Test expectations can be specified via [expect] (see methods in
  *    [Expectation]), [expectThrow], or using assertions with the [Expect]
  *    class.
  *  * Configuration: The framework can be adapted by calling [configure] with a
  *    [Configuration].  Common configurations can be found in this package
- *    under: 'dom\_config.dart', 'html\_config.dart', and 'vm\_config.dart'.
+ *    under: 'dom\_config.dart' (deprecated), 'html\_config.dart' (for running
+ *    tests compiled to Javascript in a browser), and 'vm\_config.dart' (for
+ *    running native Dart tests on the VM).
  *
  * ##Examples##
  *
  * A trivial test:
  *
  *     #import('path-to-dart/lib/unittest/unitest.dart');
  *     main() {
  *       test('this is a test', () {
  *         int x = 2 + 3;
  *         expect(x).equals(5);
@@ skipping 29 matching lines @@
  *         });
  *       });
  *       group('group B', () {
  *         test('this B.1', () {
  *           int x = 2 + 3;
  *           expect(x).equals(5);
  *         });
  *       });
  *     }
  *
- * Asynchronous tests: if callbacks expect between 0 and 2 positional arguments.
+ * Asynchronous tests: if callbacks expect between 0 and 2 positional arguments,
+ * depending on the suffix of expectAsyncX(). expectAsyncX() will wrap a
+ * function into a new callback and will not consider the test complete until
+ * that callback is run. A count argument can be provided to specify the number
+ * of times the callback should be called (the default is 1).
  *
  *     #import('path-to-dart/lib/unittest/unitest.dart');
  *     #import('dart:dom_deprecated');
  *     main() {
  *       test('calllback is executed once', () {
  *         // wrap the callback of an asynchronous call with [expectAsync0] if
  *         // the callback takes 0 arguments...
  *         window.setTimeout(expectAsync0(() {
  *           int x = 2 + 3;
  *           expect(x).equals(5);
  *         }), 0);
  *       });
  *
  *       test('calllback is executed twice', () {
  *         var callback = expectAsync0(() {
  *           int x = 2 + 3;
  *           expect(x).equals(5);
  *         }, count: 2); // <-- we can indicate multiplicity to [expectAsync0]
  *         window.setTimeout(callback, 0);
  *         window.setTimeout(callback, 0);
  *       });
  *     }
  *
+ * 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.
+ *
  * 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 111 matching lines @@
  * description will include the descriptions of any surrounding group()
  * calls.
  */
 void test(String spec, TestFunction body) {
   ensureInitialized();
 
   _tests.add(new TestCase(_tests.length + 1, _fullSpec(spec), body, 0));
 }
 
 /**
- * Creates a new async test case with the given description and body. The
- * description will include the descriptions of any surrounding group()
- * calls.
- */
-// TODO(sigmund): deprecate this API
-void asyncTest(String spec, int callbacks, TestFunction body) {
-  ensureInitialized();
-
-  final testCase = new TestCase(
-      _tests.length + 1, _fullSpec(spec), body, callbacks);
-  _tests.add(testCase);
-
-  if (callbacks < 1) {
-    testCase.error(
-        'Async tests must wait for at least one callback ', '');
-  }
-}
-
-/**
  * Creates a new test case with the given description and body. The
  * description will include the descriptions of any surrounding group()
  * calls.
  *
  * "solo_" means that this will be the only test that is run. All other tests
  * will be skipped. This is a convenience function to let you quickly isolate
  * a single test by adding "solo_" before it to temporarily disable all other
  * tests.
  */
 void solo_test(String spec, TestFunction body) {
@@ skipping 47 matching lines @@
       } else if (arg3 == _sentinel) {
         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',
            '');
         _state = _UNCAUGHT_ERROR;
       }
-    }, () { if (calls == expectedCalls) callbackDone(); });
+    }, () { if (calls == expectedCalls) _callbackDone(); });
   }
 
   invoke0() {
     return guardAsync(
         () => _incrementCall() ? callback() : null,
-        () { if (calls == expectedCalls) callbackDone(); });
+        () { if (calls == expectedCalls) _callbackDone(); });
   }
 
   invoke1(arg1) {
     return guardAsync(
         () => _incrementCall() ? callback(arg1) : null,
-        () { if (calls == expectedCalls) callbackDone(); });
+        () { if (calls == expectedCalls) _callbackDone(); });
   }
 
   invoke2(arg1, arg2) {
     return guardAsync(
         () => _incrementCall() ? callback(arg1, arg2) : null,
-        () { if (calls == expectedCalls) callbackDone(); });
+        () { if (calls == expectedCalls) _callbackDone(); });
   }
 
   /** Returns false if we exceded the number of expected calls. */
   bool _incrementCall() {
     calls++;
     if (calls > expectedCalls) {
       testCase.error(
          'Callback called more times than expected ($expectedCalls)',
          '');
       _state = _UNCAUGHT_ERROR;
@@ skipping 59 matching lines @@
 
   try {
     body();
   } finally {
     // Now that the group is over, restore the previous one.
     _currentGroup = oldGroup;
   }
 }
 
 /** Called by subclasses to indicate that an asynchronous test completed. */
-void callbackDone() {
+void _callbackDone() {
   // 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(() {
     _callbacksCalled++;
     if (_currentTest < _tests.length) {
       final testCase = _tests[_currentTest];
       if (_callbacksCalled > testCase.callbacks) {
         final expected = testCase.callbacks;
         testCase.error(
-            'More calls to callbackDone() than expected. '
+            'More calls to _callbackDone() than expected. '
             'Actual: ${_callbacksCalled}, expected: ${expected}', '');
         _state = _UNCAUGHT_ERROR;
       } else if ((_callbacksCalled == testCase.callbacks) &&
           (_state != _RUNNING_TEST)) {
         if (testCase.result == null) testCase.pass();
         _currentTest++;
         _testRunner();
       }
     }
   });
 }
 
-/** Menchanism to notify that an error was caught outside of this library. */
+/**
+ * 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);
     _state = _UNCAUGHT_ERROR;
     if (testCase.callbacks > 0) {
       _currentTest++;
       _testRunner();
     }
   } else {
@@ skipping 133 matching lines @@
   }
   _config.onInit();
 
   // Immediately queue the suite up. It will run after a timeout (i.e. after
   // main() has returned).
   _defer(_runTests);
 }
 
 /** Signature for a test function. */
 typedef void TestFunction();