src/test/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. They are normally put right after the copyright comment, e.g.:
  39
  40 ```Rust
  41 // Copyright blah blah blah
  42 // except according to those terms.
  43
  44 // ignore-test This doesn't actually work
  45 ```
  46
  47 ### Ignoring tests
  48
  49 These are used to ignore the test in some situations, which means the test won't
  50 be compiled or run.
  51
  52 * `ignore-X` where `X` is a target detail or stage will ignore the test accordingly (see below)
  53 * `ignore-pretty` will not compile the pretty-printed test (this is done to test the pretty-printer, but might not always work)
  54 * `ignore-test` always ignores the test
  55 * `ignore-lldb` and `ignore-gdb` will skip a debuginfo test on that debugger.
  56
  57 `only-X` is the opposite. The test will run only when `X` matches.
  58
  59 Some examples of `X` in `ignore-X`:
  60
  61 * Architecture: `aarch64`, `arm`, `asmjs`, `mips`, `wasm32`, `x86_64`, `x86`, ...
  62 * OS: `android`, `emscripten`, `freebsd`, `ios`, `linux`, `macos`, `windows`, ...
  63 * Environment (fourth word of the target triple): `gnu`, `msvc`, `musl`.
  64 * Pointer width: `32bit`, `64bit`.
  65 * Stage: `stage0`, `stage1`, `stage2`.
  66
  67 ### Other Header Commands
  68
  69 * `min-{gdb,lldb}-version`
  70 * `min-llvm-version`
  71 * `compile-pass` for UI tests, indicates that the test is supposed
  72   to compile, as opposed to the default where the test is supposed to error out.
  73 * `compile-flags` passes extra command-line args to the compiler,
  74   e.g. `compile-flags -g` which forces debuginfo to be enabled.
  75 * `should-fail` indicates that the test should fail; used for "meta testing",
  76   where we test the compiletest program itself to check that it will generate
  77   errors in appropriate scenarios. This header is ignored for pretty-printer tests.
  78 * `gate-test-X` where `X` is a feature marks the test as "gate test" for feature X.
  79   Such tests are supposed to ensure that the compiler errors when usage of a gated
  80   feature is attempted without the proper `#![feature(X)]` tag.
  81   Each unstable lang feature is required to have a gate test.
  82
  83 ## Revisions
  84
  85 Certain classes of tests support "revisions" (as of the time of this
  86 writing, this includes run-pass, compile-fail, run-fail, and
  87 incremental, though incremental tests are somewhat
  88 different). Revisions allow a single test file to be used for multiple
  89 tests. This is done by adding a special header at the top of the file:
  90
  91 ```
  92 // revisions: foo bar baz
  93 ```
  94
  95 This will result in the test being compiled (and tested) three times,
  96 once with `--cfg foo`, once with `--cfg bar`, and once with `--cfg
  97 baz`. You can therefore use `#[cfg(foo)]` etc within the test to tweak
  98 each of these results.
  99
 100 You can also customize headers and expected error messages to a particular
 101 revision. To do this, add `[foo]` (or `bar`, `baz`, etc) after the `//`
 102 comment, like so:
 103
 104 ```
 105 // A flag to pass in only for cfg `foo`:
 106 //[foo]compile-flags: -Z verbose
 107
 108 #[cfg(foo)]
 109 fn test_foo() {
 110     let x: usize = 32_u32; //[foo]~ ERROR mismatched types
 111 }
 112 ```
 113
 114 Note that not all headers have meaning when customized to a revision.
 115 For example, the `ignore-test` header (and all "ignore" headers)
 116 currently only apply to the test as a whole, not to particular
 117 revisions. The only headers that are intended to really work when
 118 customized to a revision are error patterns and compiler flags.
 119
 120 ## Guide to the UI Tests
 121
 122 The UI tests are intended to capture the compiler's complete output,
 123 so that we can test all aspects of the presentation. They work by
 124 compiling a file (e.g., `ui/hello_world/main.rs`), capturing the output,
 125 and then applying some normalization (see below). This normalized
 126 result is then compared against reference files named
 127 `ui/hello_world/main.stderr` and `ui/hello_world/main.stdout`. If either of
 128 those files doesn't exist, the output must be empty. If the test run
 129 fails, we will print out the current output, but it is also saved in
 130 `build/<target-triple>/test/ui/hello_world/main.stdout` (this path is
 131 printed as part of the test failure message), so you can run `diff` and
 132 so forth.
 133
 134 Normally, the test-runner checks that UI tests fail compilation. If you want
 135 to do a UI test for code that *compiles* (e.g. to test warnings, or if you
 136 have a collection of tests, only some of which error out), you can use the
 137 `// compile-pass` header command to have the test runner instead
 138 check that the test compiles successfully.
 139
 140 ### Editing and updating the reference files
 141
 142 If you have changed the compiler's output intentionally, or you are
 143 making a new test, you can pass `--bless` to the command you used to
 144 run the tests. This will then copy over the files
 145 from the build directory and use them as the new reference.
 146
 147 ### Normalization
 148
 149 The normalization applied is aimed at eliminating output difference
 150 between platforms, mainly about filenames:
 151
 152 - the test directory is replaced with `$DIR`
 153 - all backslashes (`\`) are converted to forward slashes (`/`) (for Windows)
 154 - all CR LF newlines are converted to LF
 155
 156 Sometimes these built-in normalizations are not enough. In such cases, you
 157 may provide custom normalization rules using the header commands, e.g.
 158
 159 ```
 160 // normalize-stdout-test: "foo" -> "bar"
 161 // normalize-stderr-32bit: "fn\(\) \(32 bits\)" -> "fn\(\) \($$PTR bits\)"
 162 // normalize-stderr-64bit: "fn\(\) \(64 bits\)" -> "fn\(\) \($$PTR bits\)"
 163 ```
 164
 165 This tells the test, on 32-bit platforms, whenever the compiler writes
 166 `fn() (32 bits)` to stderr, it should be normalized to read `fn() ($PTR bits)`
 167 instead. Similar for 64-bit. The replacement is performed by regexes using
 168 default regex flavor provided by `regex` crate.
 169
 170 The corresponding reference file will use the normalized output to test both
 171 32-bit and 64-bit platforms:
 172
 173 ```
 174 ...
 175    |
 176    = note: source type: fn() ($PTR bits)
 177    = note: target type: u16 (16 bits)
 178 ...
 179 ```
 180
 181 Please see `ui/transmute/main.rs` and `.stderr` for a concrete usage example.
 182
 183 Besides `normalize-stderr-32bit` and `-64bit`, one may use any target
 184 information or stage supported by `ignore-X` here as well (e.g.
 185 `normalize-stderr-windows` or simply `normalize-stderr-test` for unconditional
 186 replacement).