Ability to guard callbacks that may never get called.

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.
  *
@@ skipping 305 matching lines @@
 // as default values to named arguments.
 final _sentinel = const _Sentinel();
 
 /** Simulates spread arguments using named arguments. */
 // TODO(sigmund): remove this class and simply use a closure with named
 // arguments (if still applicable).
 class _SpreadArgsHelper {
   Function _callback;
   int _expectedCalls;
   int _calls = 0;
+  int _testNum;
   TestCase _testCase;
   Function _shouldCallBack;
   Function _isDone;
 
   _init(Function callback, Function shouldCallBack, Function isDone,
        [expectedCalls = 0]) {
     ensureInitialized();
     assert(_currentTest < _tests.length);
     _callback = callback;
     _shouldCallBack = shouldCallBack;
     _isDone = isDone;
     _expectedCalls = expectedCalls;
+    _testNum = _currentTest;
     _testCase = _tests[_currentTest];
     if (expectedCalls > 0) {
       _testCase.callbacks++;
     }
   }
 
   _SpreadArgsHelper(callback, shouldCallBack, isDone) {
     _init(callback, shouldCallBack, isDone);
   }
 
   _SpreadArgsHelper.fixedCallCount(callback, expectedCalls) {
     _init(callback, _checkCallCount, _allCallsDone, expectedCalls);
   }
 
   _SpreadArgsHelper.variableCallCount(callback, isDone) {
     _init(callback, _always, isDone, 1);
    }
 
+  _SpreadArgsHelper.optionalCalls(callback) {
+    _init(callback, _always, () => false, 0);
+   }
+
   _after() {
     if (_isDone()) {
       _handleAllCallbacksDone();
     }
   }
 
   _allCallsDone() => _calls == _expectedCalls;
 
   _always() {
     // Always run except if the test is done.
@@ skipping 25 matching lines @@
       } 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;
       }
     },
-    _after);
+    _after, _testNum);
   }
 
   invoke0() {
     return guardAsync(
         () {
           ++_calls;
           if (_shouldCallBack()) {
             return _callback();
           }
         },
-        _after);
+        _after, _testNum);
   }
 
   invoke1(arg1) {
     return guardAsync(
         () {
           ++_calls;
           if (_shouldCallBack()) {
             return _callback(arg1);
           }
         },
-        _after);
+        _after, _testNum);
   }
 
   invoke2(arg1, arg2) {
     return guardAsync(
         () {
           ++_calls;
           if (_shouldCallBack()) {
             return _callback(arg1, arg2);
           }
         },
-        _after);
+        _after, _testNum);
   }
 
   /** Returns false if we exceded the number of expected calls. */
   bool _checkCallCount() {
     if (_calls > _expectedCalls) {
       _testCase.error(
           'Callback called more times than expected '
              '($_calls > $_expectedCalls).',
           '');
       _state = _UNCAUGHT_ERROR;
@@ skipping 75 matching lines @@
 
 /**
  * Like [expectAsyncUntil0] but [callback] should take 2 positional arguments.
  */
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
 Function expectAsyncUntil2(Function callback, Function isDone) {
   return new _SpreadArgsHelper.variableCallCount(callback, isDone).invoke2;
 }
 
 /**
+ * Wraps the [callback] in a new function and returns that function. The new
+ * function will be able to handle exceptions by directing them to the correct
+ * test. This is thus similar to expectAsync0. Use it to wrap any callbacks that
+ * might optionally be called but may never be called during the test.
+ * [callback] should take between 0 and 4 positional arguments (named arguments
+ * are not supported).
+ */
+Function _protectAsync(Function callback) {
+  return new _SpreadArgsHelper.optionalCalls(callback).invoke;
+}
+
+/**
+ * Wraps the [callback] in a new function and returns that function. The new
+ * function will be able to handle exceptions by directing them to the correct
+ * test. This is thus similar to expectAsync0. Use it to wrap any callbacks that
+ * might optionally be called but may never be called during the test.
+ * [callback] should take 0 positional arguments (named arguments are not
+ * supported).
+ */
+// TODO(sigmund): deprecate this API when issue 2706 is fixed.
+Function protectAsync0(Function callback) {
+  return new _SpreadArgsHelper.optionalCalls(callback).invoke0;
+}
+
+/**
+ * Like [protectAsync0] but [callback] should take 1 positional argument.
+ */
+// TODO(sigmund): deprecate this API when issue 2706 is fixed.
+Function protectAsync1(Function callback) {
+  return new _SpreadArgsHelper.optionalCalls(callback).invoke1;
+}
+
+/**
+ * Like [protectAsync0] but [callback] should take 2 positional arguments.
+ */
+// TODO(sigmund): deprecate this API when issue 2706 is fixed.
+Function protectAsync2(Function callback) {
+  return new _SpreadArgsHelper.optionalCalls(callback).invoke2;
+}
+
+/**
  * Creates a new named group of tests. Calls to group() or test() within the
  * body of the function passed to this will inherit this group's description.
  */
 void group(String description, void body()) {
   ensureInitialized();
 
   // Concatenate the new group.
   final parentGroup = _currentGroup;
   if (_currentGroup != '') {
     // Add a space.
@@ skipping 142 matching lines @@
   for (var i = 0; i < _tests.length; i++) {
     _tests[i].callbacks = 0; // Note - won't work with old asyncTests.
   }
   runTests();
 }
 
 /**
  * Run [tryBody] guarded in a try-catch block. If an exception is thrown, update
  * the [_currentTest] status accordingly.
  */
-guardAsync(tryBody, [finallyBody]) {
+guardAsync(tryBody, [finallyBody, testNum = -1]) {
+  if (testNum < 0) testNum = _currentTest;
   try {
     return tryBody();
   } catch (var e, var trace) {
-    registerException(e, trace);
+    registerException(testNum, e, trace);
   } finally {
     _state = _READY;
     if (finallyBody != null) finallyBody();
   }
 }
 
 /**
  * Registers that an exception was caught for the current test.
  */
-registerException(e, [trace]) {
-  if (e is ExpectException) {
-    Expect.isTrue(_currentTest < _tests.length);
-    if (_state != _UNCAUGHT_ERROR) {
-      _tests[_currentTest].fail(e.message,
-          trace == null ? '' : trace.toString());
+registerException(testNum, e, [trace]) {
+  if (_tests[testNum].result == null) {
+    if (e is ExpectException) {
+      _tests[testNum].fail(e.message, trace == null ? '' : trace.toString());
+    } else {
+      _tests[testNum].fail('Caught $e', trace == null ? '' : trace.toString());
     }
   } else {
-    if (_state == _RUNNING_TEST) {
-      // If a random exception is thrown from within a test, we consider that
-      // a test failure too. A test case implicitly has an expectation that it
-      // will run to completion without an uncaught exception being thrown.
-      _tests[_currentTest].fail('Caught $e',
-          trace == null ? '' : trace.toString());
-    } else if (_state != _UNCAUGHT_ERROR) {
-      _tests[_currentTest].error('Caught $e',
-          trace == null ? '' : trace.toString());
-    }
+    _tests[testNum].error('Caught $e', trace == null ? '' : trace.toString());
   }
-  _nextTestCase();
+  if (testNum == _currentTest) {
+    _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) {
     final testCase = _tests[_currentTest];
@@ skipping 97 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();