udpate docs for the compiler option (#1916)

Author: jakemac53

pkgs/test/README.md

@@ -10,6 +10,7 @@
   * [Collecting Code Coverage](#collecting-code-coverage)
   * [Restricting Tests to Certain Platforms](#restricting-tests-to-certain-platforms)
   * [Platform Selectors](#platform-selectors)
+  * [Compiler Selectors](#compiler-selectors)
   * [Running Tests on Node.js](#running-tests-on-nodejs)
 * [Asynchronous Tests](#asynchronous-tests)
   * [Stream Matchers](#stream-matchers)
@@ -184,6 +185,12 @@ reported on the command line just like for VM tests. In fact, you can even run
 tests on both platforms with a single command: `dart test -p "chrome,vm"
 path/to/test.dart`.
 
+By default each platform has a default compiler, but some of them support
+more than one compiler. You can choose which compiler to use by passing
+`dart test -c source`, which would run all VM tests from source instead of
+compiling them to kernel. This also supports targetting a specific platform
+using normal platform selectors, like this `dart test -c vm:source`.
+
 ### Test Path Queries
 
 Some query parameters are supported on test paths, which allow you to filter the
@@ -381,6 +388,14 @@ only supports boolean operations. The following identifiers are defined:
 * `posix`: Whether the test is running on a POSIX operating system. This is
   equivalent to `!windows`.
 
+* `dart2js`: Whether the test has been compiled with Dart2Js.
+
+* `dart2wasm`: Whether the test has been compiled with Dart2Wasm.
+
+* `kernel`: Whether the test has been compiled to kernel.
+
+* `source`: Whether the test has been run with no compiler (from source).
+
 For example, if you wanted to run a test on every browser but Chrome, you would
 write `@TestOn('browser && !chrome')`.
 

pkgs/test/doc/configuration.md

@@ -121,14 +121,14 @@ verbose_trace: true
 
 ### `chain_stack_traces`
 
-This boolean field controls whether or not stack traces are chained. 
+This boolean field controls whether or not stack traces are chained.
 Disabling [`stack trace chaining`][stack trace chaining] will improve
-performance for heavily asynchronous code at the cost of debuggability. 
+performance for heavily asynchronous code at the cost of debuggability.
 
 [stack trace chaining]: https://github.com/dart-lang/stack_trace/blob/master/README.md#stack-chains
 
 ```yaml
-chain_stack_traces: false 
+chain_stack_traces: false
 ```
 
 ### `js_trace`
@@ -163,7 +163,7 @@ This field is not supported in the
 
 ### `retry`
 
-This int field controls how many times a test is retried upon failure. 
+This int field controls how many times a test is retried upon failure.
 
 ```yaml
 tags:
@@ -417,6 +417,19 @@ platforms:
 - firefox
 ```
 
+### `compilers`
+
+This field indicates which compilers tests should be compiled with by default.
+It allows the same compiler selectors that can be passed to `--compiler`. If
+a given platform has no supported compiler configured, it will use its default.
+
+```yaml
+compilers: [source]
+
+compilers:
+- source
+```
+
 ### `concurrency`
 
 This field indicates the default number of test suites to run in parallel. More
@@ -511,8 +524,8 @@ package are folded.
 ```yaml
 fold_stack_frames:
   except:
-  - test 
-  - stream_channel 
+  - test
+  - stream_channel
 ```
 
 Sample stack trace, note the absence of `package:test`