Support nested tasks in scheduled_test.

pkg/scheduled_test/lib/scheduled_test.dart

Index: pkg/scheduled_test/lib/scheduled_test.dart
diff --git a/pkg/scheduled_test/lib/scheduled_test.dart b/pkg/scheduled_test/lib/scheduled_test.dart
index 05fb9f0c5b5fc395249a516ea6a26110367f8941..456e50b3dfc7739ddb51f22875db3f55a51fe732 100644
--- a/pkg/scheduled_test/lib/scheduled_test.dart
+++ b/pkg/scheduled_test/lib/scheduled_test.dart
@@ -109,7 +109,8 @@
 /// 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
@@ -139,6 +140,25 @@
 ///       });
 ///     }
 ///
+/// [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 queue doesn't complete until the out-of-band chain has
+/// 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
@@ -244,7 +264,10 @@ void group(String description, void body()) {
 /// 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);
 
@@ -302,3 +325,18 @@ void _ensureInitialized() {
     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);
+}