Add notes about running the UI test suite

1 files changed, 37 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/src/tests/running.md b/src/doc/rustc-dev-guide/src/tests/running.md
index 5e18b8a9599..15f11cb472d 100644
--- a/src/doc/rustc-dev-guide/src/tests/running.md
+++ b/src/doc/rustc-dev-guide/src/tests/running.md
@@ -59,6 +59,43 @@ Likewise, you can test a single file by passing its path:
 ./x.py test src/test/ui/const-generics/const-test.rs
 ```
 
+### Run the UI test suite
+
+The UI test suite is special in that it tests the command-line output
+of the compiler, e.g. the wording and formatting of warnings and errors.
+Every UI test file such as `foo.rs` will have a corresponding file
+`foo.stderr` describing its expected output.
+
+Similar to any other test suite, the UI test suite can be run with:
+
+```bash
+./x.py test src/test/ui
+```
+
+If you have made a change to the way that the compiler formats its output,
+it would be extraordinarily tedious to have to reformat every `*.stderr`
+file manually. Fortunately there exists a flag that will allow you to
+"bless" the current output of the compiler as the expected output.
+When using this flag with the test runner, any UI tests that would
+ordinarily fail will instead have their `*.stderr` files overwritten
+with whatever output the compiler produces:
+
+```bash
+./x.py test src/test/ui --bless
+```
+
+Some UI tests will have different output depending on which "mode" that
+the compiler is in. Specifically, the compiler may have different output
+depending on whether the feature "non-lexical lifetimes" (NLL) is enabled.
+Any UI test such as `foo.rs` whose output differs with NLL enabled will
+have both a `foo.stderr` file and a `foo.nll.stderr` file.
+By default, the UI test suite will not be run in NLL mode.
+To run the UI test suite in NLL mode, use the following:
+
+```bash
+./x.py test src/test/ui --compare-mode=nll
+```
+
 ### Run only the tidy script
 
 ```bash