New expectation functions plus convert old tests to use these.

lib/unittest/unittest.dart

Index: lib/unittest/unittest.dart
===================================================================
--- lib/unittest/unittest.dart	(revision 8345)
+++ lib/unittest/unittest.dart	(working copy)
@@ -5,19 +5,20 @@
 /**
  * A library for writing dart unit tests.
  *
- * To import this library, specify the relative path to 
+ * 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.
+ *  * Checks: Test expectations can be specified via [expect]
+ *  * Matchers: [expect] assertions are written declaratively using [Matcher]s
  *  * 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##
  *
@@ -27,7 +28,7 @@
  *     main() {
  *       test('this is a test', () {
  *         int x = 2 + 3;
- *         expect(x).equals(5);
+ *         expect(x, equals(5));
  *       });
  *     }
  *
@@ -37,11 +38,11 @@
  *     main() {
  *       test('this is a test', () {
  *         int x = 2 + 3;
- *         expect(x).equals(5);
+ *         expect(x, equals(5));
  *       });
  *       test('this is another test', () {
  *         int x = 2 + 3;
- *         expect(x).equals(5);
+ *         expect(x, equals(5));
  *       });
  *     }
  *
@@ -52,22 +53,26 @@
  *       group('group A', () {
  *         test('test A.1', () {
  *           int x = 2 + 3;
- *           expect(x).equals(5);
+ *           expect(x, equals(5));
  *         });
  *         test('test A.2', () {
  *           int x = 2 + 3;
- *           expect(x).equals(5);
+ *           expect(x, equals(5));
  *         });
  *       });
  *       group('group B', () {
  *         test('this B.1', () {
  *           int x = 2 + 3;
- *           expect(x).equals(5);
+ *           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');
@@ -77,20 +82,28 @@
  *         // the callback takes 0 arguments...
  *         window.setTimeout(expectAsync0(() {
  *           int x = 2 + 3;
- *           expect(x).equals(5);
+ *           expect(x, equals(5));
  *         }), 0);
  *       });
  *
  *       test('calllback is executed twice', () {
  *         var callback = expectAsync0(() {
  *           int x = 2 + 3;
- *           expect(x).equals(5);
+ *           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
@@ -113,7 +126,7 @@
  *           // correctly
  *           guardAsync(() {
  *             int x = 2 + 3;
- *             expect(x).equals(5);
+ *             expect(x, equals(5));
  *           });
  *           // indicate that the asynchronous callback was invoked.
  *           async.complete();
@@ -125,8 +138,17 @@
 
 #import('dart:isolate');
 
+#source('collection_matchers.dart');
 #source('config.dart');
-#source('expectation.dart');
+#source('core_matchers.dart');
+#source('description.dart');
+#source('expect.dart');
+#source('interfaces.dart');
+#source('map_matchers.dart');
+#source('matcher.dart');
+#source('numeric_matchers.dart');
+#source('operator_matchers.dart');
+#source('string_matchers.dart');
 #source('test_case.dart');
 
 /** [Configuration] used by the unittest library. */
@@ -179,14 +201,11 @@
 /** If set, then all other test cases will be ignored. */
 TestCase _soloTest;
 
-/** Creates an expectation for the given value. */
-Expectation expect(value) => new Expectation(value);
-
 /**
- * Evaluates the [function] and validates that it throws an exception. If
- * [callback] is provided, then it will be invoked with the thrown exception.
- * The callback may do any validation it wants. In addition, if it returns
- * `false`, that also indicates an expectation failure.
+ * (Deprecated) Evaluates the [function] and validates that it throws an
+ * exception. If [callback] is provided, then it will be invoked with the
+ * thrown exception. The callback may do any validation it wants. In addition,
+ * if it returns `false`, that also indicates an expectation failure.
  */
 void expectThrow(function, [bool callback(exception)]) {
   bool threw = false;
@@ -222,9 +241,9 @@
 }
 
 /**
- * Creates a new async test case with the given description and body. The
- * description will include the descriptions of any surrounding group()
- * calls.
+ * (Deprecated) 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) {
@@ -334,7 +353,7 @@
     calls++;
     if (calls > expectedCalls) {
       testCase.error(
-         'Callback called more times than expected ($expectedCalls)',
+         'Callback called more times than expected ($calls > $expectedCalls)',
          '');
       _state = _UNCAUGHT_ERROR;
       return false;
@@ -408,8 +427,8 @@
 /** Called by subclasses to indicate that an asynchronous test completed. */
 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 
+  // 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.
@@ -425,7 +444,9 @@
         _state = _UNCAUGHT_ERROR;
       } else if ((_callbacksCalled == testCase.callbacks) &&
           (_state != _RUNNING_TEST)) {
-        if (testCase.result == null) testCase.pass();
+        if (testCase.result == null) {
+          testCase.pass();
+        }
         _currentTest++;
         _testRunner();
       }
@@ -433,7 +454,10 @@
   });
 }
 
-/** 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];