X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=COMPILER_TESTS.md;h=1cae4ef090fe0b6fa6d9a69bfbaa5c5533eadfe4;hb=1f0d928de88f2e87512bfff4f61c663eca10e712;hp=e4acf230e7211cdee947f0fa565e0ef89b95e306;hpb=d2e13e822a73e0ea46ae9e21afdd3155fc997f6d;p=rust.git

diff --git a/COMPILER_TESTS.md b/COMPILER_TESTS.md
index e4acf230e72..1cae4ef090f 100644
--- a/COMPILER_TESTS.md
+++ b/COMPILER_TESTS.md
@@ -1,6 +1,6 @@
 # Compiler Test Documentation
 
-In the Rust project, we use a special set of comands imbedded in
+In the Rust project, we use a special set of commands embedded in
 comments to test the Rust compiler. There are two groups of commands:
 
 1. Header commands
@@ -24,16 +24,17 @@ are expecting.
   `~^^^^^^^` is seven lines up.
 
 The error levels that you can have are:
+
 1. `ERROR`
 2. `WARNING`
 3. `NOTE`
 4. `HELP` and `SUGGESTION`*
 
-\* **Note**: `SUGGESTION` must follow emediatly after `HELP`.
+\* **Note**: `SUGGESTION` must follow immediately after `HELP`.
 
 ## Summary of Header Commands
 
-Header commands specify something about the entire test file, as a
+Header commands specify something about the entire test file as a
 whole, instead of just a few lines inside the test.
 
 * `ignore-X` where `X` is an architecture, OS or stage will ignore the test accordingly
@@ -41,3 +42,43 @@ whole, instead of just a few lines inside the test.
 * `ignore-test` always ignores the test
 * `ignore-lldb` and `ignore-gdb` will skip the debuginfo tests
 * `min-{gdb,lldb}-version`
+* `should-fail` indicates that the test should fail; used for "meta testing",
+  where we test the compiletest program itself to check that it will generate
+  errors in appropriate scenarios. This header is ignored for pretty-printer tests.
+
+## Revisions
+
+Certain classes of tests support "revisions" (as of the time of this
+writing, this includes run-pass, compile-fail, run-fail, and
+incremental, though incremental tests are somewhat
+different). Revisions allow a single test file to be used for multiple
+tests. This is done by adding a special header at the top of the file:
+
+```
+// revisions: foo bar baz
+```
+
+This will result in the test being compiled (and tested) three times,
+once with `--cfg foo`, once with `--cfg bar`, and once with `--cfg
+baz`. You can therefore use `#[cfg(foo)]` etc within the test to tweak
+each of these results.
+
+You can also customize headers and expected error messages to a particular
+revision. To do this, add `[foo]` (or `bar`, `baz`, etc) after the `//`
+comment, like so:
+
+```
+// A flag to pass in only for cfg `foo`:
+//[foo]compile-flags: -Z verbose
+
+#[cfg(foo)]
+fn test_foo() {
+    let x: usize = 32_u32; //[foo]~ ERROR mismatched types
+}
+```
+
+Note that not all headers have meaning when customized too a revision.
+For example, the `ignore-test` header (and all "ignore" headers)
+currently only apply to the test as a whole, not to particular
+revisions. The only headers that are intended to really work when
+customized to a revision are error patterns and compiler flags.