COMPILER_TESTS.md

   1 # Compiler Test Documentation
   2
   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:
   5
   6 1. Header commands
   7 2. Error info commands
   8
   9 Both types of commands are inside comments, but header commands should
  10 be in a comment before any code.
  11
  12 ## Summary of Error Info Commands
  13
  14 Error commands specify something about certain lines of the
  15 program. They tell the test what kind of error and what message you
  16 are expecting.
  17
  18 * `~`: Associates the following error level and message with the
  19   current line
  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.
  25
  26 The error levels that you can have are:
  27
  28 1. `ERROR`
  29 2. `WARNING`
  30 3. `NOTE`
  31 4. `HELP` and `SUGGESTION`*
  32
  33 \* **Note**: `SUGGESTION` must follow immediately after `HELP`.
  34
  35 ## Summary of Header Commands
  36
  37 Header commands specify something about the entire test file as a
  38 whole, instead of just a few lines inside the test.
  39
  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.
  48 * `gate-test-X` where `X` is a feature marks the test as "gate test" for feature X.
  49   Such tests are supposed to ensure that the compiler errors when usage of a gated
  50   feature is attempted without the proper `#![feature(X)]` tag.
  51   Each unstable lang feature is required to have a gate test.
  52
  53 ## Revisions
  54
  55 Certain classes of tests support "revisions" (as of the time of this
  56 writing, this includes run-pass, compile-fail, run-fail, and
  57 incremental, though incremental tests are somewhat
  58 different). Revisions allow a single test file to be used for multiple
  59 tests. This is done by adding a special header at the top of the file:
  60
  61 ```
  62 // revisions: foo bar baz
  63 ```
  64
  65 This will result in the test being compiled (and tested) three times,
  66 once with `--cfg foo`, once with `--cfg bar`, and once with `--cfg
  67 baz`. You can therefore use `#[cfg(foo)]` etc within the test to tweak
  68 each of these results.
  69
  70 You can also customize headers and expected error messages to a particular
  71 revision. To do this, add `[foo]` (or `bar`, `baz`, etc) after the `//`
  72 comment, like so:
  73
  74 ```
  75 // A flag to pass in only for cfg `foo`:
  76 //[foo]compile-flags: -Z verbose
  77
  78 #[cfg(foo)]
  79 fn test_foo() {
  80     let x: usize = 32_u32; //[foo]~ ERROR mismatched types
  81 }
  82 ```
  83
  84 Note that not all headers have meaning when customized to a revision.
  85 For example, the `ignore-test` header (and all "ignore" headers)
  86 currently only apply to the test as a whole, not to particular
  87 revisions. The only headers that are intended to really work when
  88 customized to a revision are error patterns and compiler flags.