Add built-in timeouts to 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 timeouts to scheduled tests.
 // 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
 /// "schedule", then executing those tasks in order. This allows the tests to
 /// read like synchronous, linear code, despite executing asynchronously.
 ///
 /// The `scheduled_test` package is built on top of `unittest`, and should be
@@ skipping 116 matching lines @@
 ///     void main() {
 ///       test('sendRequest sends a request', () {
 ///         startServer(wrapAsync((request) {
 ///           expect(request.body, equals('payload'));
 ///           request.response.close();
 ///         }));
 ///
 ///         schedule(() => sendRequest('payload'));
 ///       });
 ///     }
+///
+/// ## Timeouts
+///
+/// `scheduled_test` has a built-in timeout of 30 seconds (configurable via
+/// [Schedule.timeoutLength]). 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
+/// [Schedule] that it's making progress by calling [Schedule.ping], which will
+/// reset the timeout whenever it's called.
 library scheduled_test;
 
 import 'dart:async';
 
 import 'package:unittest/unittest.dart' as unittest;
 
 import 'src/schedule.dart';
 import 'src/schedule_error.dart';
 import 'src/utils.dart';
 
@@ skipping 131 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);
   };
 }