Add an Engine class for running groups of test suites.

[email protected]
See #2

Review URL: https://codereview.chromium.org//891493004

Author: nex3

lib/src/engine.dart

@@ -0,0 +1,67 @@
+// Copyright (c) 2015, 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.
+
+library unittest.engine;
+
+import 'dart:async';
+import 'dart:collection';
+
+import 'live_test.dart';
+import 'state.dart';
+import 'suite.dart';
+import 'utils.dart';
+
+/// An [Engine] manages a run that encompasses multiple test suites.
+///
+/// The current status of every test is visible via [liveTests]. [onTestStarted]
+/// can also be used to be notified when a test is about to be run.
+///
+/// Suites will be run in the order they're provided to [new Engine]. Tests
+/// within those suites will likewise be run in the order of [Suite.tests].
+class Engine {
+  /// Whether [run] has been called yet.
+  var _runCalled = false;
+
+  /// An unmodifiable list of tests to run.
+  ///
+  /// These are [LiveTest]s, representing the in-progress state of each test.
+  /// Tests that have not yet begun running are marked [Status.pending]; tests
+  /// that have finished are marked [Status.complete].
+  ///
+  /// [LiveTest.run] must not be called on these tests.
+  final List<LiveTest> liveTests;
+
+  /// A stream that emits each [LiveTest] as it's about to start running.
+  ///
+  /// This is guaranteed to fire before [LiveTest.onStateChange] first fires.
+  Stream<LiveTest> get onTestStarted => _onTestStartedController.stream;
+  final _onTestStartedController = new StreamController<LiveTest>.broadcast();
+
+  /// Creates an [Engine] that will run all tests in [suites].
+  Engine(Iterable<Suite> suites)
+      : liveTests = new UnmodifiableListView(flatten(suites.map((suite) =>
+            suite.tests.map((test) => test.load(suite)))));
+
+  /// Runs all tests in all suites defined by this engine.
+  ///
+  /// This returns `true` if all tests succeed, and `false` otherwise. It will
+  /// only return once all tests have finished running.
+  Future<bool> run() {
+    if (_runCalled) {
+      throw new StateError("Engine.run() may not be called more than once.");
+    }
+    _runCalled = true;
+
+    return Future.forEach(liveTests, (liveTest) {
+      _onTestStartedController.add(liveTest);
+
+      // First, schedule a microtask to ensure that [onTestStarted] fires before
+      // the first [LiveTest.onStateChange] event. Once the test finishes, use
+      // [new Future] to do a coarse-grained event loop pump to avoid starving
+      // the DOM or other non-microtask events.
+      return new Future.microtask(liveTest.run).then((_) => new Future(() {}));
+    }).then((_) =>
+        liveTests.every((liveTest) => liveTest.state.result == Result.success));
+  }
+}

lib/src/utils.dart

@@ -56,3 +56,20 @@ Trace getTrace(stack, bool formatStacks, bool filterStacks) {
     return frame.package != 'unittest' || frame.member != 'TestCase._runTest';
   })).terse.foldFrames((frame) => frame.package == 'unittest' || frame.isCore);
 }
+
+/// Flattens nested [Iterable]s inside an [Iterable] into a single [List]
+/// containing only non-[Iterable] elements.
+List flatten(Iterable nested) {
+  var result = [];
+  helper(iter) {
+    for (var element in iter) {
+      if (element is Iterable) {
+        helper(element);
+      } else {
+        result.add(element);
+      }
+    }
+  }
+  helper(nested);
+  return result;
+}

test/engine_test.dart

@@ -0,0 +1,87 @@
+// Copyright (c) 2015, 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.
+
+import 'package:unittest/src/declarer.dart';
+import 'package:unittest/src/engine.dart';
+import 'package:unittest/src/state.dart';
+import 'package:unittest/src/suite.dart';
+import 'package:unittest/unittest.dart';
+
+void main() {
+  var declarer;
+  setUp(() => declarer = new Declarer());
+
+  test("runs each test in each suite in order", () {
+    var testsRun = 0;
+    for (var i = 0; i < 4; i++) {
+      declarer.test("test ${i + 1}", expectAsync(() {
+        expect(testsRun, equals(i));
+        testsRun++;
+      }, max: 1));
+    }
+
+    var engine = new Engine([
+      new Suite("suite 1", declarer.tests.take(2)),
+      new Suite("suite 2", declarer.tests.skip(2))
+    ]);
+
+    return engine.run().then((_) => expect(testsRun, equals(4)));
+  });
+
+  test("emits each test before it starts running and after the previous test "
+      "finished", () {
+    var testsRun = 0;
+    for (var i = 0; i < 3; i++) {
+      declarer.test("test ${i + 1}", expectAsync(() => testsRun++, max: 1));
+    }
+
+    var engine = new Engine([new Suite("suite", declarer.tests)]);
+    engine.onTestStarted.listen(expectAsync((liveTest) {
+      // [testsRun] should be one less than the test currently running.
+      expect(liveTest.test.name, equals("test ${testsRun + 1}"));
+
+      // [Engine.onTestStarted] is guaranteed to fire before the first
+      // [LiveTest.onStateChange].
+      expect(liveTest.onStateChange.first,
+          completion(equals(const State(Status.running, Result.success))));
+    }, count: 3, max: 3));
+
+    return engine.run();
+  });
+
+  test(".run() returns true if every test passes", () {
+    for (var i = 0; i < 2; i++) {
+      declarer.test("test ${i + 1}", () {});
+    }
+
+    var engine = new Engine([new Suite("suite", declarer.tests)]);
+    expect(engine.run(), completion(isTrue));
+  });
+
+  test(".run() returns false if any test fails", () {
+    for (var i = 0; i < 2; i++) {
+      declarer.test("test ${i + 1}", () {});
+    }
+    declarer.test("failure", () => throw new TestFailure("oh no"));
+
+    var engine = new Engine([new Suite("suite", declarer.tests)]);
+    expect(engine.run(), completion(isFalse));
+  });
+
+  test(".run() returns false if any test errors", () {
+    for (var i = 0; i < 2; i++) {
+      declarer.test("test ${i + 1}", () {});
+    }
+    declarer.test("failure", () => throw "oh no");
+
+    var engine = new Engine([new Suite("suite", declarer.tests)]);
+    expect(engine.run(), completion(isFalse));
+  });
+
+  test(".run() may not be called more than once", () {
+    var engine = new Engine([]);
+    expect(engine.run(), completes);
+    expect(() => engine.run(), throwsStateError);
+  });
+}