Rollup merge of #89082 - smoelius:master, r=kennytm

Implement #85440 (Random test ordering)

This PR adds `--shuffle` and `--shuffle-seed` options to `libtest`. The options are similar to the [`-shuffle` option](https://github.com/golang/go/blob/c894b442d1e5e150ad33fa3ce13dbfab1c037b3a/src/testing/testing.go#L1482-L1499) that was recently added to Go.

Here are the relevant parts of the help message:
```
        --shuffle       Run tests in random order
        --shuffle-seed SEED
                        Run tests in random order; seed the random number
                        generator with SEED
...
By default, the tests are run in alphabetical order. Use --shuffle or set
RUST_TEST_SHUFFLE to run the tests in random order. Pass the generated
"shuffle seed" to --shuffle-seed (or set RUST_TEST_SHUFFLE_SEED) to run the
tests in the same order again. Note that --shuffle and --shuffle-seed do not
affect whether the tests are run in parallel.
```
Is an RFC needed for this?

1 files changed, 35 insertions, 1 deletions

diff --git a/src/doc/rustc/src/tests/index.md b/src/doc/rustc/src/tests/index.md
index 04e20fdd41c..23a9f31e8e7 100644
--- a/src/doc/rustc/src/tests/index.md
+++ b/src/doc/rustc/src/tests/index.md
@@ -181,6 +181,40 @@ unstable-options` flag. See [tracking issue
 #64888](https://github.com/rust-lang/rust/issues/64888) and the [unstable
 docs](../../unstable-book/compiler-flags/report-time.html) for more information.
 
+#### `--shuffle`
+
+Runs the tests in random order, as opposed to the default alphabetical order.
+
+This may also be specified by setting the `RUST_TEST_SHUFFLE` environment
+variable to anything but `0`.
+
+The random number generator seed that is output can be passed to
+[`--shuffle-seed`](#--shuffle-seed-seed) to run the tests in the same order
+again.
+
+Note that `--shuffle` does not affect whether the tests are run in parallel. To
+run the tests in random order sequentially, use `--shuffle --test-threads 1`.
+
+⚠️ 🚧 This option is [unstable](#unstable-options), and requires the `-Z
+unstable-options` flag. See [tracking issue
+#89583](https://github.com/rust-lang/rust/issues/89583) for more information.
+
+#### `--shuffle-seed` _SEED_
+
+Like [`--shuffle`](#--shuffle), but seeds the random number generator with
+_SEED_. Thus, calling the test harness with `--shuffle-seed` _SEED_ twice runs
+the tests in the same order both times.
+
+_SEED_ is any 64-bit unsigned integer, for example, one produced by
+[`--shuffle`](#--shuffle).
+
+This can also be specified with the `RUST_TEST_SHUFFLE_SEED` environment
+variable.
+
+⚠️ 🚧 This option is [unstable](#unstable-options), and requires the `-Z
+unstable-options` flag. See [tracking issue
+#89583](https://github.com/rust-lang/rust/issues/89583) for more information.
+
 ### Output options
 
 The following options affect the output behavior.
@@ -197,7 +231,7 @@ to the console. Usually the output is captured, and only displayed if the test
 fails.
 
 This may also be specified by setting the `RUST_TEST_NOCAPTURE` environment
-variable set to anything but `0`.
+variable to anything but `0`.
 
 #### `--show-output`