Rollup merge of #139224 - epage:nocapture, r=thomcc

fix(test): Expose '--no-capture' in favor of `--nocapture`

This improves consistency with commonly expected CLI conventions,
avoiding a common stutter people make when running tests (trying what
they expect and then having to check the docs to then user whats
accepted).

An alternative could have been to take a value, like `--capture <value>` (e.g. `pytest` does this).
Overall, we're shifting focus for features to custom test harnesses (see #134283).
Most of `pytest`s modes will likely be irrelevant in that situation.
As for the rest, its too early to tell which, if any, may be relevant,
so we're sticking with this small, quality of life improvement.

I expect we'll warn about `--nocapture` being deprecated in the future after a sufficient transition period has been allowed.
By deprecating `--nocapture`, we intend that custom test harnesses do
not need to support it for reasons outside of their own compatibility
requirements, much like the deprecation in #134283

I'm punting for now on the naming of `RUST_TEST_NOCAPTURE`.
I feel like T-testing-devex should do a wider look at environment
variables role in lib`test` before evaluating whether to
- Deprecate it in favor of the user passing CLI flags or the test runner
  providing its own config
- Deprecate in favor of `RUST_TEST_NO_CAPTURE`
- Deprecate in favor of `RUST_TEST_CAPTURE`

Other CLI flags were evaluated for casing consistency:
- `--logfile` has the same problem but was deprecated in #134283

Regarding the implementation, I moved `--nocapture` out of `optgroups()`, into `parse_opts()`, out of an abundance of caution in passing the options without a deprecated value to the usage generation.  However, the usage does not actually show optional flags, so this could potentially be dropped, simplifying the PR.

Note: `compiletest` added `--no-capture` instead of `--nocapture` in #134809

T-testing-devex FCP: https://github.com/rust-lang/rust/issues/133073#issuecomment-2486921104

Fixes #133073

2 files changed, 14 insertions, 9 deletions

diff --git a/library/test/src/cli.rs b/library/test/src/cli.rs
index ef6786f4316..8840714a662 100644
--- a/library/test/src/cli.rs
+++ b/library/test/src/cli.rs
@@ -61,7 +61,7 @@ fn optgroups() -> getopts::Options {
         .optopt("", "logfile", "Write logs to the specified file (deprecated)", "PATH")
         .optflag(
             "",
-            "nocapture",
+            "no-capture",
             "don't capture stdout/stderr of each \
              task, allow printing directly",
         )
@@ -172,7 +172,7 @@ tests in the same order again. Note that --shuffle and --shuffle-seed do not
 affect whether the tests are run in parallel.
 
 All tests have their standard output and standard error captured by default.
-This can be overridden with the --nocapture flag or setting RUST_TEST_NOCAPTURE
+This can be overridden with the --no-capture flag or setting RUST_TEST_NOCAPTURE
 environment variable to a value other than "0". Logging is not captured by default.
 
 Test Attributes:
@@ -199,7 +199,10 @@ Test Attributes:
 /// otherwise creates a `TestOpts` object and returns it.
 pub fn parse_opts(args: &[String]) -> Option<OptRes> {
     // Parse matches.
-    let opts = optgroups();
+    let mut opts = optgroups();
+    // Flags hidden from `usage`
+    opts.optflag("", "nocapture", "Deprecated, use `--no-capture`");
+
     let binary = args.first().map(|c| &**c).unwrap_or("...");
     let args = args.get(1..).unwrap_or(args);
     let matches = match opts.parse(args) {
@@ -210,7 +213,7 @@ pub fn parse_opts(args: &[String]) -> Option<OptRes> {
     // Check if help was requested.
     if matches.opt_present("h") {
         // Show help and do nothing more.
-        usage(binary, &opts);
+        usage(binary, &optgroups());
         return None;
     }
 
@@ -447,7 +450,7 @@ fn get_color_config(matches: &getopts::Matches) -> OptPartRes<ColorConfig> {
 }
 
 fn get_nocapture(matches: &getopts::Matches) -> OptPartRes<bool> {
-    let mut nocapture = matches.opt_present("nocapture");
+    let mut nocapture = matches.opt_present("nocapture") || matches.opt_present("no-capture");
     if !nocapture {
         nocapture = match env::var("RUST_TEST_NOCAPTURE") {
             Ok(val) => &val != "0",
diff --git a/src/doc/rustc/src/tests/index.md b/src/doc/rustc/src/tests/index.md
index d2026513d2f..12de69a4c9e 100644
--- a/src/doc/rustc/src/tests/index.md
+++ b/src/doc/rustc/src/tests/index.md
@@ -81,7 +81,7 @@ behavior.
 
 > Note: When running with [`cargo test`], the libtest CLI arguments must be
 > passed after the `--` argument to differentiate between flags for Cargo and
-> those for the harness. For example: `cargo test -- --nocapture`
+> those for the harness. For example: `cargo test -- --no-capture`
 
 ### Filters
 
@@ -225,7 +225,7 @@ The following options affect the output behavior.
 Displays one character per test instead of one line per test. This is an alias
 for [`--format=terse`](#--format-format).
 
-#### `--nocapture`
+#### `--no-capture`
 
 Does not capture the stdout and stderr of the test, and allows tests to print
 to the console. Usually the output is captured, and only displayed if the test
@@ -234,11 +234,13 @@ fails.
 This may also be specified by setting the `RUST_TEST_NOCAPTURE` environment
 variable to anything but `0`.
 
+`--nocapture` is a deprecated alias for `--no-capture`.
+
 #### `--show-output`
 
 Displays the stdout and stderr of successful tests after all tests have run.
 
-Contrast this with [`--nocapture`](#--nocapture) which allows tests to print
+Contrast this with [`--no-capture`](#--no-capture) which allows tests to print
 *while they are running*, which can cause interleaved output if there are
 multiple tests running in parallel, `--show-output` ensures the output is
 contiguous, but requires waiting for all tests to finish.
@@ -247,7 +249,7 @@ contiguous, but requires waiting for all tests to finish.
 
 Control when colored terminal output is used. Valid options:
 
-* `auto`: Colorize if stdout is a tty and [`--nocapture`](#--nocapture) is not
+* `auto`: Colorize if stdout is a tty and [`--no-capture`](#--no-capture) is not
   used. This is the default.
 * `always`: Always colorize the output.
 * `never`: Never colorize the output.