Compiletest: Test Suites Overview

2nd chunk of `src/tests/compiletest.md`

2187070ab6d3b408dafece1d87891c6a5ffe5e4ad6242b530000000100000fde

| `ui-fulldeps`                             | `ui` tests which require a linkable build of `rustc` (such as using `extern crate rustc_span;` or used as a plugin) |
| [`pretty`](#pretty-printer-tests)         | Check pretty printing                                                                                               |
| [`incremental`](#incremental-tests)       | Check incremental compilation behavior                                                                              |
| [`debuginfo`](#debuginfo-tests)           | Check debuginfo generation running debuggers                                                                        |
| [`codegen`](#codegen-tests)               | Check code generation                                                                                               |
| [`codegen-units`](#codegen-units-tests)   | Check codegen unit partitioning                                                                                     |
| [`assembly`](#assembly-tests)             | Check assembly output                                                                                               |
| [`mir-opt`](#mir-opt-tests)               | Check MIR generation and optimizations                                                                              |
| [`coverage`](#coverage-tests)             | Check coverage instrumentation                                                                                      |
| [`coverage-run-rustdoc`](#coverage-tests) | `coverage` tests that also run instrumented doctests                                                                |

### General purpose test suite

[`run-make`](#run-make-tests) are general purpose tests using Rust programs.

### Rustdoc test suites

See [Rustdoc tests](../rustdoc.md#tests) for more details.

| Test suite       | Purpose                                                                  |
|------------------|--------------------------------------------------------------------------|
| `rustdoc`        | Check `rustdoc` generated files contain the expected documentation       |
| `rustdoc-gui`    | Check `rustdoc`'s GUI using a web browser                                |
| `rustdoc-js`     | Check `rustdoc` search is working as expected                            |
| `rustdoc-js-std` | Check rustdoc search is working as expected specifically on the std docs |
| `rustdoc-json`   | Check JSON output of `rustdoc`                                           |
| `rustdoc-ui`     | Check terminal output of `rustdoc`                                       |


### Pretty-printer tests

The tests in [`tests/pretty`] exercise the "pretty-printing" functionality of
`rustc`. The `-Z unpretty` CLI option for `rustc` causes it to translate the
input source into various different formats, such as the Rust source after macro
expansion.

The pretty-printer tests have several [directives](directives.md) described below.
These commands can significantly change the behavior of the test, but the
default behavior without any commands is to:

1. Run `rustc -Zunpretty=normal` on the source file.
2. Run `rustc -Zunpretty=normal` on the output of the previous step.
3. The output of the previous two steps should be the same.
4. Run `rustc -Zno-codegen` on the output to make sure that it can type check
   (this is similar to running `cargo check`).

If any of the commands above fail, then the test fails.

The directives for pretty-printing tests are:

- `pretty-mode` specifies the mode pretty-print tests should run in (that is,
  the argument to `-Zunpretty`). The default is `normal` if not specified.
- `pretty-compare-only` causes a pretty test to only compare the pretty-printed
  output (stopping after step 3 from above). It will not try to compile the
  expanded output to type check it. This is needed for a pretty-mode that does
  not expand to valid Rust, or for other situations where the expanded output
  cannot be compiled.
- `pp-exact` is used to ensure a pretty-print test results in specific output.

Title: Compiletest: Test Suites Overview

Summary

This section provides an overview of different test suites available within Compiletest. It outlines compiler-specific test suites like ui-fulldeps, pretty, incremental, debuginfo, codegen, codegen-units, assembly, mir-opt and coverage tests, detailing their purpose such as checking code generation, MIR optimization, and coverage instrumentation. It also covers general-purpose test suite (`run-make`) and Rustdoc test suites for checking documentation generation and search functionality, as well as the specifics of pretty-printer tests, which exercise the pretty-printing functionality of rustc with options to specify the pretty-printing mode and compare outputs.