Support a @Timeout annotation.

README.md

 `test` provides a standard way of writing and running tests in Dart.
 
 ## Writing Tests
 
 Tests are specified using the top-level [`test()`][test] function, and test
 assertions are made using [`expect()`][expect]:
 
 [test]: http://www.dartdocs.org/documentation/test/latest/index.html#test/test@id_test
 [expect]: http://www.dartdocs.org/documentation/test/latest/index.html#test/test@id_expect
 
@@ skipping 260 matching lines @@
 
     stream.listen(expectAsync((number) {
       expect(number, inInclusiveRange(1, 3));
     }, count: 3));
   });
 }
 ```
 
 [expectAsync]: http://www.dartdocs.org/documentation/test/latest/index.html#test/test@id_expectAsync
 
+## Configuring Tests
+
+### Timeouts
+
+By default, tests will time out after 30 seconds of inactivity. However, this
+can be configured on a per-test, -group, or -suite basis. To change the timeout
+for a test suite, put a `@Timeout` annotation at the top of the file:
+
+```dart
+@Timeout(new Duration(seconds: 45))
+
+import "package:test/test.dart";
+
+void main() {
+  // ...
+}
+```
+
+In addition to setting an absolute timeout, you can set the timeout relative to
+the default using `@Timeout.factor`. For example, `@Timeout.factor(1.5)` will
+set the timeout to one and a half times as long as the default—45 seconds.
+
+Timeouts can be set for tests and groups using the `timeout` parameter. This
+parameter takes a `Timeout` object just like the annotation. For example:
+
+```dart
+import "package:test/test.dart";
+
+void main() {
+  group("slow tests", () {
+    // ...
+
+    test("even slower test", () {
+      // ...
+    }, timeout: new Timeout.factor(2))
+  }, timeout: new Timeout(new Duration(minutes: 1)));
+}
+```
+
+Nested timeouts apply in order from outermost to innermost. That means that
+"even slower test" will take two minutes to time out, since it multiplies the
+group's timeout by 2.
+
 ## Testing With `barback`
 
 Packages using the `barback` transformer system may need to test code that's
 created or modified using transformers. The test runner handles this using the
 `--pub-serve` option, which tells it to load the test code from a `pub serve`
 instance rather than from the filesystem. **This feature is only supported on
 Dart `1.9.2` and higher.**
 
 Before using the `--pub-serve` option, add the `test/pub_serve` transformer to
 your `pubspec.yaml`. This transformer adds the necessary bootstrapping code that
@@ skipping 19 matching lines @@
 
 In this case, the port is `8081`. In another terminal, pass this port to
 `--pub-serve` and otherwise invoke `pub run test:test` as normal:
 
 ```shell
 $ pub run test:test --pub-serve=8081 -p chrome
 "pub serve" is compiling test/my_app_test.dart...
 "pub serve" is compiling test/utils_test.dart...
 00:00 +42: All tests passed!
 ```