pkg/unittest: Types, deprecations, docs

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 184 matching lines @@
  */
 String _currentGroup = '';
 
 /** Separator used between group names and test names. */
 String groupSep = ' ';
 
 /** Tests executed in this suite. */
 List<TestCase> _tests;
 
 /** Get the list of tests. */
-get testCases => _tests;
+List<TestCase> get testCases => _tests;
 
 /**
  * Callback used to run tests. Entrypoints can replace this with their own
  * if they want.
  */
 Function _testRunner;
 
 /** Setup function called before each test in a group */
 Function _testSetup;
 
@@ skipping 86 matching lines @@
   int actualCalls = 0;
   TestCase testCase;
   bool complete;
   static const sentinel = const _Sentinel();
 
   _SpreadArgsHelper(Function callback, int minExpected, int maxExpected,
       Function isDone, String id)
       : this.callback = callback,
         minExpectedCalls = minExpected,
         maxExpectedCalls = (maxExpected == 0 && minExpected > 0)
-            ? minExpected 
+            ? minExpected
             : maxExpected,
         this.isDone = isDone,
         testNum = _currentTest,
         this.id = _makeCallbackId(id, callback) {
     ensureInitialized();
     if (!(_currentTest >= 0 &&
            _currentTest < _tests.length &&
            _tests[_currentTest] != null)) {
       print("No valid test, did you forget to run your test inside a call "
           "to test()?");
@@ skipping 185 matching lines @@
   return new _SpreadArgsHelper(callback, 0, -1, isDone, id).invoke;
 }
 
 /**
  * Indicate that [callback] is expected to be called until [isDone] returns
  * true. The unittest framework check [isDone] after each callback and only
  * when it returns true will it continue with the following test. Using
  * [expectAsyncUntil0] will also ensure that errors that occur within
  * [callback] are tracked and reported. [callback] should take 0 positional
  * arguments (named arguments are not supported). [id] can be used to
- * identify the callback in error messages (for example if it is called 
+ * identify the callback in error messages (for example if it is called
  * after the test case is complete).
  */
 // TODO(sigmund): deprecate this API when issue 2706 is fixed.
 Function expectAsyncUntil0(Function callback, Function isDone, {String id}) {
   return new _SpreadArgsHelper(callback, 0, -1, isDone, id).invoke0;
 }
 
 /**
  * Like [expectAsyncUntil0] but [callback] should take 1 positional argument.
  */
@@ skipping 140 matching lines @@
  * 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()) {
   (new Future.immediate(null)).then((_) => callback());
 }
 
-rerunTests() {
+void 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
  * predicate function. This is different to enabling/disabling tests
  * in that it removes the tests completely.
  */
 void filterTests(testFilter) {
   var filterFunction;
   if (testFilter is String) {
     RegExp re = new RegExp(testFilter);
     filterFunction = (t) => re.hasMatch(t.description);
   } else if (testFilter is RegExp) {
     filterFunction = (t) => testFilter.hasMatch(t.description);
   } else if (testFilter is Function) {
     filterFunction = testFilter;
   }
   _tests.retainMatching(filterFunction);
 }
 
 /** Runs all queued tests, one at a time. */
-runTests() {
+void runTests() {
   _currentTest = 0;
   _currentGroup = '';
 
   // If we are soloing a test, remove all the others.
   if (_soloTest != null) {
     filterTests((t) => t == _soloTest);
   }
 
   _config.onStart();
 
   _defer(() {
     _testRunner();
   });
 }
 
 /**
- * Run [tryBody] guarded in a try-catch block. If an exception is thrown, update
- * the [_currentTest] status accordingly.
+ * Run [tryBody] guarded in a try-catch block. If an exception is thrown, it is
+ * passed to the corresponding test.
+ *
+ * The value returned by [tryBody] (if any) is returned by [guardAsync].
  */
-guardAsync(tryBody, [finallyBody, testNum = -1]) {
+guardAsync(Function tryBody, [Function finallyBody, int testNum = -1]) {
   if (testNum < 0) testNum = _currentTest;
   try {
     return tryBody();
   } catch (e, trace) {
     _registerException(testNum, e, trace);
   } finally {
     if (finallyBody != null) finallyBody();
   }
 }
 
 /**
  * Registers that an exception was caught for the current test.
  */
-registerException(e, [trace]) {
+void registerException(e, [trace]) {
   _registerException(_currentTest, e, trace);
 }
 
 /**
  * Registers that an exception was caught for the current test.
  */
 _registerException(testNum, e, [trace]) {
   trace = trace == null ? '' : trace.toString();
   String message = (e is TestFailure) ? e.message : 'Caught $e';
   if (_tests[testNum].result == null) {
@@ skipping 47 matching lines @@
 }
 
 String _fullSpec(String spec) {
   if (spec == null) return '$_currentGroup';
   return _currentGroup != '' ? '$_currentGroup$groupSep$spec' : spec;
 }
 
 /**
  * Lazily initializes the test library if not already initialized.
  */
-ensureInitialized() {
+void ensureInitialized() {
   if (_initialized) {
     return;
   }
   _initialized = true;
   // Hook our async guard into the matcher library.
   wrapAsync = expectAsync1;
 
   _tests = <TestCase>[];
   _testRunner = _nextBatch;
   _uncaughtErrorMessage = null;
@@ skipping 36 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 dynamic TestFunction();