Support nested tasks in scheduled_test.

pkg/scheduled_test/lib/scheduled_test.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.
 
 // TODO(nweiz): Add support for calling [schedule] while the schedule is already
 // running.
 // TODO(nweiz): Port the non-Pub-specific scheduled test libraries from Pub.
 /// A package for writing readable tests of asynchronous behavior.
 ///
 /// This package works by building up a queue of asynchronous tasks called a
@@ skipping 91 matching lines @@
 ///         });
 ///       });
 ///     }
 ///
 /// ## Out-of-Band Callbacks
 ///
 /// Sometimes your tests will have callbacks that don't fit into the schedule.
 /// It's important that errors in these callbacks are still registered, though,
 /// and that [Schedule.onException] and [Schedule.onComplete] still run after
 /// they finish. When using `unittest`, you wrap these callbacks with
-/// `expectAsyncN`; when using `scheduled_test`, you use [wrapAsync].
+/// `expectAsyncN`; when using `scheduled_test`, you use [wrapAsync] or
+/// [wrapFuture].
 ///
 /// [wrapAsync] has two important functions. First, any errors that occur in it
 /// will be passed into the [Schedule] instead of causing the whole test to
 /// crash. They can then be handled by [Schedule.onException] and
 /// [Schedule.onComplete]. Second, a task queue isn't considered finished until
 /// all of its [wrapAsync]-wrapped functions have been called. This ensures that
 /// [Schedule.onException] and [Schedule.onComplete] will always run after all
 /// the test code in the main queue.
 ///
 /// Note that the [completes], [completion], and [throws] matchers use
 /// [wrapAsync] internally, so they're safe to use in conjunction with scheduled
 /// tests.
 ///
 /// Here's an example of a test using [wrapAsync] to catch errors thrown in the
 /// callback of a fictional `startServer` function:
 ///
 ///     import 'package:scheduled_test/scheduled_test.dart';
 ///
 ///     void main() {
 ///       test('sendRequest sends a request', () {
 ///         startServer(wrapAsync((request) {
 ///           expect(request.body, equals('payload'));
 ///           request.response.close();
 ///         }));
 ///
 ///         schedule(() => sendRequest('payload'));
 ///       });
 ///     }
 ///
+/// [wrapFuture] works similarly to [wrapAsync], but instead of wrapping a
+/// single callback it wraps a whole [Future] chain. Like [wrapAsync], it
+/// ensures that the task quque doesn't complete until the out-of-band chain has

[Bob Nystrom, 2013/02/19 23:15:04]

"quque" -> "queue"

[nweiz, 2013/02/20 00:23:12]

Done.

+/// finished, and that any errors in the chain are piped back into the scheduled
+/// test. For example:
+///
+///     import 'package:scheduled_test/scheduled_test.dart';
+///
+///     void main() {
+///       test('sendRequest sends a request', () {
+///         wrapFuture(server.nextRequest.then((request) {
+///           expect(request.body, equals('payload'));
+///           expect(request.headers['content-type'], equals('text/plain'));
+///         }));
+///
+///         schedule(() => sendRequest('payload'));
+///       });
+///     }
+///
 /// ## Timeouts
 ///
 /// `scheduled_test` has a built-in timeout of 30 seconds (configurable via
 /// [Schedule.timeout]). This timeout is aware of the structure of the schedule;
 /// this means that it will reset for each task in a queue, when moving between
 /// queues, or almost any other sort of interaction with [currentSchedule]. As
 /// long as the [Schedule] knows your test is making some sort of progress, it
 /// won't time out.
 ///
 /// If a single task might take a long time, you can also manually tell the
@@ skipping 85 matching lines @@
 /// [fn] returns a [Future], tasks after it won't be run until that [Future]
 /// completes.
 ///
 /// The return value will be completed once the scheduled task has finished
 /// running. Its return value is the same as the return value of [fn], or the
 /// value it completes to if it's a [Future].
 ///
 /// If [description] is passed, it's used to describe the task for debugging
 /// purposes when an error occurs.
 ///
-/// This function is identical to [currentSchedule.tasks.schedule].
+/// If this is called when a task queue is currently running, it will run [fn]
+/// on the next event loop iteration rather than adding it to a queue. The
+/// current task will not complete until [fn] (and any [Future] it returns) has
+/// finished running. Any errors in [fn] will automatically be handled.
 Future schedule(fn(), [String description]) =>
   currentSchedule.tasks.schedule(fn, description);
 
 /// Register a [setUp] function for a test [group]. This has the same semantics
 /// as [unittest.setUp]. Tasks may be scheduled using [schedule] within
 /// [setUpFn], and [currentSchedule] may be accessed as well.
 ///
 /// Note that there is no associated [tearDown] function. Instead, tasks should
 /// be scheduled for [currentSchedule.onComplete] or
 /// [currentSchedule.onException]. These tasks will be run after each test's
@@ skipping 37 matching lines @@
   unittest.ensureInitialized();
   unittest.wrapAsync = (f) {
     if (currentSchedule == null) {
       throw new StateError("Unexpected call to wrapAsync with no current "
           "schedule.");
     }
 
     return currentSchedule.wrapAsync(f);
   };
 }
+
+/// Like [wrapAsync], this ensures that the current task queue waits for
+/// out-of-band asynchronous code, and that errors raised in that code are
+/// handled correctly. However, [wrapFuture] wraps a [Future] chain rather than
+/// a single callback.
+///
+/// The returned [Future] completes to the same value or error as [future].
+Future wrapFuture(Future future) {
+  if (currentSchedule == null) {
+    throw new StateError("Unexpected call to wrapFuture with no current "
+        "schedule.");
+  }
+
+  return currentSchedule.wrapFuture(future);
+}