Suggest tests tool

This chapter is about the internals of and contribution instructions for the suggest-tests tool. For a high-level overview of the tool, see this section. This tool is currently in a beta state and is tracked by this issue on Github. Currently the number of tests it will suggest are very limited in scope, we are looking to expand this (contributions welcome!).


The tool is defined in a separate crate (src/tools/suggest-tests) which outputs suggestions which are parsed by a shim in bootstrap (src/bootstrap/src/core/build_steps/ The only notable thing the bootstrap shim does is (when invoked with the --run flag) use bootstrap's internal mechanisms to create a new Builder and uses it to invoke the suggested commands. The suggest-tests crate is where the fun happens, two kinds of suggestions are defined: "static" and "dynamic" suggestions.

Static suggestions

Defined here. Static suggestions are simple: they are just globs which map to a x command. In suggest-tests, this is implemented with a simple macro_rules macro.

Dynamic suggestions

Defined here. These are more complicated than static suggestions and are implemented as functions with the following signature: fn(&Path) -> Vec<Suggestion>. In other words, each suggestion takes a path to a modified file and (after running arbitrary Rust code) can return any number of suggestions, or none. Dynamic suggestions are useful for situations where fine-grained control over suggestions is needed. For example, modifications to the compiler/xyz/ path should trigger the x test compiler/xyz suggestion. In the future, dynamic suggestions might even read file contents to determine if (what) tests should run.

Adding a suggestion

The following steps should serve as a rough guide to add suggestions to suggest-tests (very welcome!):

  1. Determine the rules for your suggestion. Is it simple and operates only on a single path or does it match globs? Does it need fine-grained control over the resulting command or does "one size fit all"?
  2. Based on the previous step, decide if your suggestion should be implemented as either static or dynamic.
  3. Implement the suggestion. If it is dynamic then a test is highly recommended, to verify that your logic is correct and to give an example of the suggestion. See the file.
  4. Open a PR implementing your suggestion. (TODO: add example PR)