Enhance the Dart unittest library to support multiple invocations in the same application run.

pkg/unittest/lib/src/test_environment.dart

+// Copyright (c) 2014, 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.
+
+part of unittest;
+
+/// Class for encapsulating test environment state.

[nweiz, 2014/11/13 19:34:27]

The first sentence of a documentation comment should be its own paragraph, here
and elsewhere.

[wibling, 2014/11/14 10:09:48]

Done.

+/// This is used by the withTestEnvironment method to support multiple

[nweiz, 2014/11/13 19:34:27]

withTestEnvironment -> [withTestEnironment].

[wibling, 2014/11/14 10:09:48]

Done.

+/// invocations of the unittest library with the same application

[nweiz, 2014/11/13 19:34:27]

with -> within

[wibling, 2014/11/14 10:09:49]

Done.

[wibling, 2014/11/14 10:09:49]

Done.

+/// instance.
+class _TestEnvironment {
+  Configuration config = null;

[nweiz, 2014/11/13 19:34:27]

"= null" is unnecessary here and elsewhere.

[wibling, 2014/11/14 10:09:48]

Done.

[wibling, 2014/11/14 10:09:49]

Done.

+
+  // We use a 'dummy' context for the top level to eliminate null
+  // checks when querying the context. This allows us to easily
+  //  support top-level setUp/tearDown functions as well.

[nweiz, 2014/11/13 19:34:26]

setUp -> [setUp], tearDown -> [tearDown].

[wibling, 2014/11/14 10:09:49]

Done.

+  final rootContext = new _GroupContext();
+  _GroupContext currentContext;
+
+  /// Represents the index of the currently running test case

[nweiz, 2014/11/13 19:34:26]

Use complete sentences here, including periods at the end.

[wibling, 2014/11/14 10:09:48]

Done.

+  /// == -1 implies the test system is not running
+  /// == [number of test cases] is a short-lived state flagging that the last
+  ///    test has completed
+  int currentTestCaseIndex = -1;
+
+  /// Whether the framework is in an initialized state.

[nweiz, 2014/11/13 19:34:27]

"is in an initialized state" -> "has been initialized".

[wibling, 2014/11/14 10:09:49]

Done.

+  bool initialized = false;
+
+  /// Time since we last gave non-sync code a chance to be scheduled.

[nweiz, 2014/11/13 19:34:27]

"non-sync" -> "asynchronous"

[wibling, 2014/11/14 10:09:49]

Done.

+  int lastBreath = new DateTime.now().millisecondsSinceEpoch;
+
+  /// The set of tests to run can be restricted by using [solo_test] and
+  /// [solo_group].
+  /// As groups can be nested we use a counter to keep track of the nest level

[nweiz, 2014/11/13 19:34:27]

"nest level" -> "nesting level"

[wibling, 2014/11/14 10:09:49]

Done.

+  /// of soloing, and a flag to tell if we have seen any solo tests.
+  int soloNestingLevel = 0;
+  bool soloTestSeen = false;
+
+  final List<TestCase> testCases;

[nweiz, 2014/11/13 19:34:27]

Document this.

[wibling, 2014/11/14 10:09:48]

Done.

+  final UnmodifiableListView<TestCase> testCasesRO;

[nweiz, 2014/11/13 19:34:27]

We don't usually use suffixes like "RO". In general, we also dynamically create
unmodifiable views rather than storing a single instance. I'd change this back
to wrapping [testCases] in unittest.dart.

[wibling, 2014/11/14 10:09:48]

Okay, I will change it back to my previous version.

+
+  String uncaughtErrorMessage = null;

[nweiz, 2014/11/13 19:34:27]

Document this.

[wibling, 2014/11/14 10:09:48]

Done.

+
+  _TestEnvironment() : this._(new List<TestCase>());
+
+  _TestEnvironment._(List<TestCase> testCases)

[nweiz, 2014/11/13 19:34:27]

These two constructors are confusing; what's the point of having a constructor
named "_" when the class itself is private anyway? I'd just make a single
constructor that takes an optional List argument.

[wibling, 2014/11/14 10:09:48]

The list of tests is not optional. The reason for having the deferring
constructor is to enable setting both the testCases and the testCasesRO field as
final. Since I am moving the testCasesRO back to unittest.dart I can revert it
back to my previous version.

+      : this.testCases = testCases,
+        this.testCasesRO = new UnmodifiableListView(testCases) {
+    currentContext = rootContext;
+  }
+}