Add basic support for a configuration file.

doc/package_config.md

Index: doc/package_config.md
diff --git a/doc/package_config.md b/doc/package_config.md
new file mode 100644
index 0000000000000000000000000000000000000000..b0fb74e4cc78124b693ff99a756555a8dde25253
--- /dev/null
+++ b/doc/package_config.md
@@ -0,0 +1,116 @@
+Each package may include a configuration file that applies to the package as a
+whole. This file can be used to provide custom defaults for various options, to
+define configuration for multiple files, and more.
+
+The file is named `dart_test.yaml` and lives at the root of the package, next to
+the package's pubspec. Like the pubspec, it's a [YAML][] file. Here's an
+example:
+
+[YAML]: http://yaml.org/
+
+```yaml
+# This package's tests are very slow. Double the default timeout.
+timeout: 2x
+
+# This is a browser-only package, so test on content shell by default.
+platforms: [content-shell]
+```
+
+* [Config Fields](#config-fields)
+
+## Config Fields
+
+These fields directly affect the behavior of the test runner. They go at the
+root of the configuration file.
+
+### `platforms`
+
+This field indicates which platforms tests should run on by default. It allows
+the same paltform identifiers that can be passed to `--platform`. If multiple
+platforms are included, the test runner will default to running tests on all of
+them. This defaults to `[vm]`.
+
+```yaml
+platforms: [content_shell]
+
+platforms:
+- chrome
+- firefox
+```
+
+### `concurrency`
+
+This field indicates the default number of test suites to run in parallel. More
+parallelism can improve the overall speed of running tests up to a point, but
+eventually it just adds more memory overhead without any performance gain. This
+defaults to approximately half the number of processors on the current machine.
+If it's set to 1, only one test suite will run at a time.
+
+```yaml
+concurrency: 3
+```
+
+### `pub_serve`
+
+This field indicates that the test runner should run against a `pub serve`
+instance by default, and provides the port number for that instance. Note that
+if there is no `pub serve` instance running at that port, running the tests will
+fail by default.
+
+```yaml
+pub_serve: 8081
+```
+
+### `timeout`
+
+This field indicates how much time the test runner should allow a test to remain
+inactive before it considers that test to have failed. It has three possible
+formats:
+
+* The string "none" indicates that tests should never time out.
+
+* A number followed by a unit abbreviation indicates an exact time. For example,
+  "1m" means a timeout of one minute, and "30s" means a timeout of thirty
+  seconds. Multiple numbers can be combined, as in "1m 30s".
+
+* A number followed by "x" indicates a multiple. This is applied to the default
+  value of 30s.
+
+```yaml
+timeout: 1m
+```
+
+### `reporter`
+
+This field indicates the default reporter to use. It may be set to "compact",
+"expanded", or "json" (although why anyone would want to default to JSON is
+beyond me). It defaults to "expanded" on Windows and "compact" everywhere else.
+
+```yaml
+reporter: expanded
+```
+
+### `verbose_trace`
+
+This boolean field controls whether or not stack traces caused by errors are
+trimmed to remove internal stack frames. This includes frames from the Dart core
+libraries, the [`stack_trace`][stack_trace] package, and the `test` package
+itself. It defaults to `false`.
+
+[stack_trace]: https://pub.dartlang.org/packages/stack_trace
+
+```yaml
+verbose_trace: true
+```
+
+### `js_trace`
+
+This boolean field controls whether or not stack traces caused by errors that
+occur while running Dart compiled to JS are converted back to Dart style. This
+conversion uses the source map generated by `dart2js` to approximate the
+original Dart line, column, and in some cases member name for each stack frame.
+It defaults to `false`.
+
+```yaml
+js_trace: true
+```