Add a LoadSuite class.

lib/src/runner/load_suite.dart

+// 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 test.runner.load_suite;
+
+import 'dart:async';
+
+import 'package:stack_trace/stack_trace.dart';
+
+import '../../test.dart';
+import '../backend/invoker.dart';
+import '../backend/metadata.dart';
+import '../backend/suite.dart';
+import '../utils.dart';
+import 'load_exception.dart';
+
+/// A [Suite] emitted by a [Loader] that provides a test-like interface for
+/// loading a test file.
+///
+/// This is used to expose the current status of test loading to the user. It's

[kevmoo, 2015/06/23 00:48:06]

Avoid starting doc sentences with 'This...'

instead

"Exposes the current status..."

[nweiz, 2015/06/23 19:38:54]

Why? This isn't mentioned in the doc comment guidelines, and it doesn't produce
complete sentences.

+/// important to provide users visibility into what's taking a long time and
+/// where failures occur. And since some tests may be loaded at the same time as
+/// others are run, it's useful to provide that visibility in the form of a test
+/// suite so that it can integrate well into the existing reporting interface
+/// without too much extra logic.

[kevmoo, 2015/06/23 00:48:06]

This paragraph feels like a justification for the feature instead of a
doc...maybe?

[nweiz, 2015/06/23 19:38:54]

It's important that users of a class understand why it exists. If a user
unfamiliar with the package were reading the Loader docs, they'd be curious why
it's necessary to have this intervening type of suite; this answers that
question.

+///
+/// A suite is constructed with logic necessary to produce a test suite. As with
+/// a normal test body, this logic isn't run until [LiveTest.run] is called. The
+/// suite itself is returned by [suite] once it's avaialble, but any errors or
+/// prints will be emitted through the running [LiveTest].
+class LoadSuite extends Suite {
+  /// A future that completes to the loaded suite once the suite's test has been
+  /// run and completed successfully.
+  ///
+  /// This will return `null` if the suite is unavailable for some reason (for
+  /// example if an error occurred while loading it).
+  final Future<Suite> suite;
+
+  /// Creates a load suite named [name] on [platform].
+  ///
+  /// [body] may return either a [Suite] or a [Future] that completes to a
+  /// [Suite]. Its return value is forwarded through [suite], although if it
+  /// throws an error that will be forwarded through the suite's test.
+  factory LoadSuite(String name, body(), {String platform}) {
+    var completer = new Completer.sync();
+    return new LoadSuite._(name, () {
+      var invoker = Invoker.current;
+      invoker.addOutstandingCallback();
+
+      invoke(() async {
+        try {
+          var suite = await body();
+          if (completer.isCompleted) return;
+          completer.complete(suite);
+          invoker.removeOutstandingCallback();
+        } catch (error, stackTrace) {
+          registerException(error, stackTrace);
+          if (!completer.isCompleted) completer.complete();
+        }
+      });
+
+      // If the test is forcibly closed, exit immediately. It doesn't have any
+      // cleanup to do that won't be handled by Loader.close.
+      invoker.onClose.then((_) {
+        if (completer.isCompleted) return;
+        completer.complete();
+        invoker.removeOutstandingCallback();
+      });
+    }, completer.future, platform: platform);
+  }
+
+  /// A utility constructor for a load suite that just throws [exception].
+  ///
+  /// The suite's name will be based on [exception]'s path.
+  factory LoadSuite.forLoadException(LoadException exception,
+      {StackTrace stackTrace, String platform}) {
+    if (stackTrace == null) stackTrace = new Trace.current();
+
+    return new LoadSuite("loading ${exception.path}", () {
+      return new Future.error(exception, stackTrace);
+    }, platform: platform);
+  }
+
+  /// A utility constructor for a load suite that just emits [suite].
+  factory LoadSuite.forSuite(Suite suite) {
+    return new LoadSuite("loading ${suite.path}", () => suite,
+        platform: suite.platform);
+  }
+
+  LoadSuite._(String name, void body(), this.suite, {String platform})
+      : super([
+        new LocalTest(name,
+            new Metadata(timeout: new Timeout(new Duration(minutes: 5))),
+            body)
+      ], platform: platform);
+
+  /// Runs the test and returns the suite.
+  ///
+  /// Rather than emitting errors through a [LiveTest], this just pipes them
+  /// through the return value.
+  Future<Suite> getSuite() async {
+    var liveTest = await tests.single.load(this);
+    liveTest.onPrint.listen(print);
+    await liveTest.run();
+
+    if (liveTest.errors.isEmpty) return await suite;
+
+    var error = liveTest.errors.first;
+    await new Future.error(error.error, error.stackTrace);
+    throw 'unreachable';
+  }
+}