pkg/unittest: readonly view of testCase collection

pkg/unittest/lib/unittest.dart

 // Copyright (c) 2013, 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, install the
  * [unittest package](http://pub.dartlang.org/packages/unittest) via the pub
  * package manager. See the [Getting Started](http://pub.dartlang.org/doc)
@@ skipping 137 matching lines @@
  *           async.complete();
  *         });
  *       });
  *     }
  *
  */
 library unittest;
 
 import 'dart:async';
 import 'dart:isolate';
+import 'dart:collection';
 import 'matcher.dart';
 export 'matcher.dart';
 
 // TODO(amouravski): We should not need to import mock here, but it's necessary
 // to enable dartdoc on the mock library, as it's not picked up normally.
 import 'mock.dart';
 
 part 'src/config.dart';
 part 'src/test_case.dart';
 
@@ skipping 21 matching lines @@
 /**
  * Description text of the current test group. If multiple groups are nested,
  * this will contain all of their text concatenated.
  */
 String _currentGroup = '';
 
 /** Separator used between group names and test names. */
 String groupSep = ' ';
 
 /** Tests executed in this suite. */
-List<TestCase> _tests;
+final List<TestCase> _testCases = new List<TestCase>();
 
 /** Get the list of tests. */
-List<TestCase> get testCases => _tests;
+final List<TestCase> testCases = new UnmodifiableListView(_testCases);
 
 /** Setup function called before each test in a group */
 Function _testSetup;
 
 /** Teardown function called after each test in a group */
 Function _testTeardown;
 
-/** Current test being executed. */
-int _currentTest = 0;
-TestCase _currentTestCase;
+int _currentTestCaseIndex = 0;
 
+/** [TestCase] currently being executed. */
 TestCase get currentTestCase =>
-    (_currentTest >= 0 && _currentTest < _tests.length)
-        ? _tests[_currentTest]
+    (_currentTestCaseIndex >= 0 && _currentTestCaseIndex < _testCases.length)
+        ? _testCases[_currentTestCaseIndex]
         : null;
 
 /** Whether the framework is in an initialized state. */
 bool _initialized = false;
 
 String _uncaughtErrorMessage = null;
 
 /** Test case result strings. */
 // TODO(gram) we should change these constants to use a different string
 // (so that writing 'FAIL' in the middle of a test doesn't
@@ skipping 15 matching lines @@
  */
 Map testState = {};
 
 /**
  * Creates a new test case with the given description and body. The
  * description will include the descriptions of any surrounding group()
  * calls.
  */
 void test(String spec, TestFunction body) {
   ensureInitialized();
-  _tests.add(new TestCase._internal(_tests.length + 1, _fullSpec(spec), body));
+  _testCases.add(new TestCase._internal(_testCases.length + 1, _fullSpec(spec),
+                                        body));
 }
 
 /**
  * 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) {
   // TODO(rnystrom): Support multiple solos. If more than one test is solo-ed,
   // all of the solo-ed tests and none of the non-solo-ed ones should run.
   if (_soloTest != null) {
     throw new Exception('Only one test can be soloed right now.');
   }
 
   ensureInitialized();
 
-  _soloTest = new TestCase._internal(_tests.length + 1, _fullSpec(spec), body);
-  _tests.add(_soloTest);
+  _soloTest = new TestCase._internal(_testCases.length + 1, _fullSpec(spec), body);
+  _testCases.add(_soloTest);
 }
 
 /** Sentinel value for [_SpreadArgsHelper]. */
 class _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).
@@ skipping 10 matching lines @@
   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
             : maxExpected,
         this.isDone = isDone,
-        testNum = _currentTest,
+        testNum = _currentTestCaseIndex,
         this.id = _makeCallbackId(id, callback) {
     ensureInitialized();
-    if (!(_currentTest >= 0 &&
-           _currentTest < _tests.length &&
-           _tests[_currentTest] != null)) {
+    if (!(_currentTestCaseIndex >= 0 &&
+           _currentTestCaseIndex < _testCases.length &&
+           _testCases[_currentTestCaseIndex] != null)) {
       print("No valid test, did you forget to run your test inside a call "
           "to test()?");
     }
-    assert(_currentTest >= 0 &&
-           _currentTest < _tests.length &&
-           _tests[_currentTest] != null);
-    testCase = _tests[_currentTest];
+    assert(_currentTestCaseIndex >= 0 &&
+           _currentTestCaseIndex < _testCases.length &&
+           _testCases[_currentTestCaseIndex] != null);
+    testCase = _testCases[_currentTestCaseIndex];
     if (isDone != null || minExpected > 0) {
       testCase._callbackFunctionsOutstanding++;
       complete = false;
     } else {
       complete = true;
     }
   }
 
   static _makeCallbackId(String id, Function callback) {
     // Try to create a reasonable id.
@@ skipping 298 matching lines @@
  * calls to [test]. The [teardownTest] function can be asynchronous; in this
  * case it must return a [Future].
  */
 void tearDown(Function teardownTest) {
   _testTeardown = teardownTest;
 }
 
 /** Advance to the next test case. */
 void _nextTestCase() {
   _defer(() {
-    _currentTest++;
+    _currentTestCaseIndex++;
     _nextBatch();
   });
 }
 
 /**
  * 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];
+ if (_currentTestCaseIndex < _testCases.length) {
+    final testCase = _testCases[_currentTestCaseIndex];
     testCase.error(msg, trace);
   } else {
     _uncaughtErrorMessage = "$msg: $trace";
   }
 }
 
 /**
  * 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
@@ skipping 20 matching lines @@
 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.retainWhere(filterFunction);
+  _testCases.retainWhere(filterFunction);
 }
 
 /** Runs all queued tests, one at a time. */
 void runTests() {
-  _currentTest = 0;
+  _currentTestCaseIndex = 0;
   _currentGroup = '';
 
   // If we are soloing a test, remove all the others.
   if (_soloTest != null) {
     filterTests((t) => t == _soloTest);
   }
 
   _config.onStart();
 
   _defer(() {
     _nextBatch();
   });
 }
 
 /**
  * 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(Function tryBody) {
-  return _guardAsync(tryBody, null, _currentTest);
+  return _guardAsync(tryBody, null, _currentTestCaseIndex);
 }
 
 _guardAsync(Function tryBody, Function finallyBody, int testNum) {
   assert(testNum >= 0);
   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.
  */
 void registerException(e, [trace]) {
-  _registerException(_currentTest, e, trace);
+  _registerException(_currentTestCaseIndex, e, trace);
 }
 
 /**
  * Registers that an exception was caught for the current test.
  */
 void _registerException(testNum, e, [trace]) {
   trace = trace == null ? '' : trace.toString();
   String message = (e is TestFailure) ? e.message : 'Caught $e';
-  if (_tests[testNum].result == null) {
-    _tests[testNum].fail(message, trace);
+  if (_testCases[testNum].result == null) {
+    _testCases[testNum].fail(message, trace);
   } else {
-    _tests[testNum].error(message, trace);
+    _testCases[testNum].error(message, trace);
   }
 }
 
 /**
  * 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.
  */
 void _nextBatch() {
   while (true) {
-    if (_currentTest >= _tests.length) {
+    if (_currentTestCaseIndex >= _testCases.length) {
       _completeTests();
       break;
     }
-    final testCase = _tests[_currentTest];
-    var f = _guardAsync(testCase._run, null, _currentTest);
+    final testCase = _testCases[_currentTestCaseIndex];
+    var f = _guardAsync(testCase._run, null, _currentTestCaseIndex);
     if (f != null) {
       f.whenComplete(() {
         _nextTestCase(); // Schedule the next test.
       });
       break;
     }
-    _currentTest++;
+    _currentTestCaseIndex++;
   }
 }
 
 /** Publish results on the page and notify controller. */
 void _completeTests() {
   if (!_initialized) return;
   int passed = 0;
   int failed = 0;
   int errors = 0;
 
-  for (TestCase t in _tests) {
+  for (TestCase t in _testCases) {
     switch (t.result) {
       case PASS:  passed++; break;
       case FAIL:  failed++; break;
       case ERROR: errors++; break;
     }
   }
-  _config.onSummary(passed, failed, errors, _tests, _uncaughtErrorMessage);
+  _config.onSummary(passed, failed, errors, _testCases, _uncaughtErrorMessage);
   _config.onDone(passed > 0 && failed == 0 && errors == 0 &&
       _uncaughtErrorMessage == null);
   _initialized = false;
 }
 
 String _fullSpec(String spec) {
   if (spec == null) return '$_currentGroup';
   return _currentGroup != '' ? '$_currentGroup$groupSep$spec' : spec;
 }
 
 /**
  * Lazily initializes the test library if not already initialized.
  */
 void ensureInitialized() {
   if (_initialized) {
     return;
   }
   _initialized = true;
   // Hook our async guard into the matcher library.
   wrapAsync = (f, [id]) => expectAsync1(f, id: id);
 
-  _tests = <TestCase>[];
   _uncaughtErrorMessage = null;
 
   if (_config == null) {
     unittestConfiguration = new Configuration();
   }
   _config.onInit();
 
   if (_config.autoStart) {
     // Immediately queue the suite up. It will run after a timeout (i.e. after
     // main() has returned).
     _defer(runTests);
   }
 }
 
 /** Select a solo test by ID. */
 void setSoloTest(int id) {
-  for (var i = 0; i < _tests.length; i++) {
-    if (_tests[i].id == id) {
-      _soloTest = _tests[i];
+  for (var i = 0; i < _testCases.length; i++) {
+    if (_testCases[i].id == id) {
+      _soloTest = _testCases[i];
       break;
     }
   }
 }
 
 /** Enable/disable a test by ID. */
 void _setTestEnabledState(int testId, bool state) {
   // Try fast path first.
-  if (_tests.length > testId && _tests[testId].id == testId) {
-    _tests[testId].enabled = state;
+  if (_testCases.length > testId && _testCases[testId].id == testId) {
+    _testCases[testId].enabled = state;
   } else {
-    for (var i = 0; i < _tests.length; i++) {
-      if (_tests[i].id == testId) {
-        _tests[i].enabled = state;
+    for (var i = 0; i < _testCases.length; i++) {
+      if (_testCases[i].id == testId) {
+        _testCases[i].enabled = state;
         break;
       }
     }
   }
 }
 
 /** 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();