1 # Compiler Test Documentation
3 In the Rust project, we use a special set of commands embedded in
4 comments to test the Rust compiler. There are two groups of commands:
9 Both types of commands are inside comments, but header commands should
10 be in a comment before any code.
12 ## Summary of Error Info Commands
14 Error commands specify something about certain lines of the
15 program. They tell the test what kind of error and what message you
18 * `~`: Associates the following error level and message with the
20 * `~|`: Associates the following error level and message with the same
21 line as the previous comment
22 * `~^`: Associates the following error level and message with the
23 previous line. Each caret (`^`) that you add adds a line to this, so
24 `~^^^^^^^` is seven lines up.
26 The error levels that you can have are:
31 4. `HELP` and `SUGGESTION`*
33 \* **Note**: `SUGGESTION` must follow immediately after `HELP`.
35 ## Summary of Header Commands
37 Header commands specify something about the entire test file as a
38 whole, instead of just a few lines inside the test.
40 * `ignore-X` where `X` is an architecture, OS or stage will ignore the test accordingly
41 * `ignore-pretty` will not compile the pretty-printed test (this is done to test the pretty-printer, but might not always work)
42 * `ignore-test` always ignores the test
43 * `ignore-lldb` and `ignore-gdb` will skip the debuginfo tests
44 * `min-{gdb,lldb}-version`
45 * `should-fail` indicates that the test should fail; used for "meta testing",
46 where we test the compiletest program itself to check that it will generate
47 errors in appropriate scenarios. This header is ignored for pretty-printer tests.
51 Certain classes of tests support "revisions" (as of the time of this
52 writing, this includes run-pass, compile-fail, run-fail, and
53 incremental, though incremental tests are somewhat
54 different). Revisions allow a single test file to be used for multiple
55 tests. This is done by adding a special header at the top of the file:
58 // revisions: foo bar baz
61 This will result in the test being compiled (and tested) three times,
62 once with `--cfg foo`, once with `--cfg bar`, and once with `--cfg
63 baz`. You can therefore use `#[cfg(foo)]` etc within the test to tweak
64 each of these results.
66 You can also customize headers and expected error messages to a particular
67 revision. To do this, add `[foo]` (or `bar`, `baz`, etc) after the `//`
71 // A flag to pass in only for cfg `foo`:
72 //[foo]compile-flags: -Z verbose
76 let x: usize = 32_u32; //[foo]~ ERROR mismatched types
80 Note that not all headers have meaning when customized too a revision.
81 For example, the `ignore-test` header (and all "ignore" headers)
82 currently only apply to the test as a whole, not to particular
83 revisions. The only headers that are intended to really work when
84 customized to a revision are error patterns and compiler flags.