rustdoc: Deprecate option --test-args in favor of new insta-stable option --test-arg

src/doc/rustdoc/src/command-line-arguments.md

@@ -194,14 +194,14 @@ $ rustdoc src/lib.rs --test
 This flag will run your code examples as tests. For more, see [the chapter
 on documentation tests](write-documentation/documentation-tests.md).
 
-See also `--test-args` and `--test-run-directory`.
+See also `--test-arg` and `--test-run-directory`.
 
-## `--test-args`: pass options to test runner
+## `--test-arg`: pass an option to the test runner
 
 Using this flag looks like this:
 
 ```bash
-$ rustdoc src/lib.rs --test --test-args ignored
+$ rustdoc src/lib.rs --test --test-arg ignored --test-arg --show-output
 ```
 
 This flag will pass options to the test runner when running documentation tests.
@@ -431,6 +431,10 @@ command line options from it. These options are one per line; a blank line indic
 an empty option. The file can use Unix or Windows style line endings, and must be
 encoded as UTF-8.
 
+## `--test-args`: pass options to the test runner
+
+This flag is **deprecated**, use `--test-arg` instead.
+
 ## `--passes`: add more rustdoc passes
 
 This flag is **deprecated**.

src/librustdoc/config.rs

@@ -618,9 +618,17 @@ impl Options {
             )
             .collect();
 
-        let test_args = matches.opt_strs("test-args");
-        let test_args: Vec<String> =
-            test_args.iter().flat_map(|s| s.split_whitespace()).map(|s| s.to_string()).collect();
+        let mut test_args = matches.opt_strs("test-arg");
+
+        // FIXME: Emit a (hard) deprecation warning in a few releases from the time of writing
+        //        once at least Cargo has had a good chance to migrate to the new flag.
+        test_args.extend(
+            matches
+                .opt_strs("test-args")
+                .iter()
+                .flat_map(|s| s.split_whitespace())
+                .map(|s| s.to_string()),
+        );
 
         let should_test = matches.opt_present("test");
         let no_run = matches.opt_present("no-run");

src/librustdoc/lib.rs

@@ -267,7 +267,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "",
         ),
         opt(Stable, FlagMulti, "", "test", "run code examples as tests", ""),
-        opt(Stable, Multi, "", "test-args", "arguments to pass to the test runner", "ARGS"),
+        opt(
+            Stable,
+            Multi,
+            "",
+            "test-arg",
+            "One argument (of possibly many) to pass to the test runner",
+            "ARG",
+        ),
         opt(
             Stable,
             Opt,
@@ -659,6 +666,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "",
         ),
         // deprecated / removed options
+        opt(
+            Stable,
+            Multi,
+            "",
+            "test-args",
+            "Arguments to pass to the test runner. This option is deprecated, use `--test-arg` instead",
+            "ARGS",
+        ),
         opt(
             Stable,
             Multi,

tests/run-make/doctests-merge/rmake.rs

@@ -9,7 +9,7 @@ fn test_and_compare(input_file: &str, stdout_file: &str, edition: &str, dep: &Pa
         .input(input_file)
         .arg("--test")
         .edition(edition)
-        .arg("--test-args=--test-threads=1")
+        .arg("--test-arg=--test-threads=1")
         .extern_("foo", dep.display().to_string())
         .env("RUST_BACKTRACE", "short")
         .run();

tests/run-make/rustdoc-default-output/output-default.stdout

@@ -34,8 +34,8 @@ Options:
         --document-hidden-items 
                         document items that have doc(hidden)
         --test          run code examples as tests
-        --test-args ARGS
-                        arguments to pass to the test runner
+        --test-arg ARG  One argument (of possibly many) to pass to the test
+                        runner
         --test-run-directory PATH
                         The working directory in which to run tests
         --target TRIPLE target triple to document
@@ -196,6 +196,9 @@ Options:
         --disable-minification 
                         disable the minification of CSS/JS files
                         (perma-unstable, do not use with cached files)
+        --test-args ARGS
+                        Arguments to pass to the test runner. This option is
+                        deprecated, use `--test-arg` instead
         --plugin-path DIR
                         removed, see issue #44136
                         <https://github.com/rust-lang/rust/issues/44136> for

tests/rustdoc-ui/2024-doctests-checks.rs

@@ -1,6 +1,6 @@
 //@ check-pass
 //@ edition: 2024
-//@ compile-flags: --test --test-args=--test-threads=1
+//@ compile-flags: --test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

tests/rustdoc-ui/2024-doctests-crate-attribute.rs

@@ -1,6 +1,6 @@
 //@ check-pass
 //@ edition: 2024
-//@ compile-flags: --test --test-args=--test-threads=1
+//@ compile-flags: --test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

tests/rustdoc-ui/doctest/cfg-test.rs

@@ -1,5 +1,5 @@
 //@ check-pass
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/doctest/comment-in-attr-134221-2.rs

@@ -1,4 +1,4 @@
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ failure-status: 101
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

tests/rustdoc-ui/doctest/comment-in-attr-134221.rs

@@ -2,7 +2,7 @@
 // It checks that even if there are comments in the attributes, the attributes
 // will still be generated correctly (and therefore fail in this test).
 
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ failure-status: 101
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

tests/rustdoc-ui/doctest/display-output.rs

@@ -2,7 +2,7 @@
 
 //@ check-pass
 //@ edition:2018
-//@ compile-flags:--test --test-args=--show-output
+//@ compile-flags:--test --test-arg=--show-output
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/doctest/doctest-multiline-crate-attribute.rs

@@ -1,4 +1,4 @@
-//@ compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ check-pass

tests/rustdoc-ui/doctest/doctest-output-include-fail.rs

@@ -1,5 +1,5 @@
 //@ edition:2024
-//@ compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ failure-status: 101

tests/rustdoc-ui/doctest/doctest-output.edition2015.stdout

@@ -1,8 +1,8 @@
 
 running 3 tests
-test $DIR/doctest-output.rs - (line 12) ... ok
-test $DIR/doctest-output.rs - ExpandedStruct (line 28) ... ok
-test $DIR/doctest-output.rs - foo::bar (line 22) ... ok
+test $DIR/doctest-output.rs - (line 10) ... ok
+test $DIR/doctest-output.rs - ExpandedStruct (line 26) ... ok
+test $DIR/doctest-output.rs - foo::bar (line 20) ... ok
 
 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
 

tests/rustdoc-ui/doctest/doctest-output.edition2024.stdout

@@ -1,8 +1,8 @@
 
 running 3 tests
-test $DIR/doctest-output.rs - (line 12) ... ok
-test $DIR/doctest-output.rs - ExpandedStruct (line 28) ... ok
-test $DIR/doctest-output.rs - foo::bar (line 22) ... ok
+test $DIR/doctest-output.rs - (line 10) ... ok
+test $DIR/doctest-output.rs - ExpandedStruct (line 26) ... ok
+test $DIR/doctest-output.rs - foo::bar (line 20) ... ok
 
 test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
 

tests/rustdoc-ui/doctest/doctest-output.rs

@@ -1,10 +1,8 @@
 //@ revisions: edition2015 edition2024
-//@[edition2015]edition:2015
-//@[edition2015]aux-build:extern_macros.rs
-//@[edition2015]compile-flags:--test --test-args=--test-threads=1
-//@[edition2024]edition:2024
-//@[edition2024]aux-build:extern_macros.rs
-//@[edition2024]compile-flags:--test --test-args=--test-threads=1
+//@[edition2015] edition: 2015
+//@[edition2024] edition: 2024
+//@ aux-build:extern_macros.rs
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ check-pass

tests/rustdoc-ui/doctest/extern-crate.rs

@@ -1,5 +1,5 @@
 //@ check-pass
-//@ compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/doctest/failed-doctest-output-windows.rs

@@ -5,7 +5,7 @@
 // FIXME: if/when the output of the test harness can be tested on its own, this test should be
 // adapted to use that, and that normalize line can go away
 
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ rustc-env:RUST_BACKTRACE=0
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

tests/rustdoc-ui/doctest/failed-doctest-output.rs

@@ -5,7 +5,7 @@
 // FIXME: if/when the output of the test harness can be tested on its own, this test should be
 // adapted to use that, and that normalize line can go away
 
-//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:--test --test-arg --test-threads=1
 //@ rustc-env:RUST_BACKTRACE=0
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

tests/rustdoc-ui/doctest/merged-ignore-no_run.rs

@@ -1,5 +1,5 @@
 //@ edition: 2024
-//@ compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ check-pass

tests/rustdoc-ui/doctest/nested-main.rs

@@ -1,5 +1,5 @@
 //@ check-pass
-//@ compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/doctest/no-run-flag-error.rs

@@ -1,6 +1,6 @@
 // test the behavior of the --no-run flag without the --test flag
 
-//@ compile-flags:-Z unstable-options --no-run --test-args=--test-threads=1
+//@ compile-flags:-Z unstable-options --no-run --test-arg=--test-threads=1
 
 pub fn f() {}
 

tests/rustdoc-ui/doctest/no-run-flag.rs

@@ -1,7 +1,7 @@
 // test the behavior of the --no-run flag
 
 //@ check-pass
-//@ compile-flags:-Z unstable-options --test --no-run --test-args=--test-threads=1
+//@ compile-flags:-Z unstable-options --test --no-run --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/doctest/non-local-defs-impl.rs

@@ -2,7 +2,7 @@
 //@ edition:2018
 //@ failure-status: 101
 //@ aux-build:pub_trait.rs
-//@ compile-flags: --test --test-args --test-threads=1
+//@ compile-flags: --test --test-arg --test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/doctest/non_local_defs.rs

@@ -1,5 +1,5 @@
 //@ check-pass
-//@ compile-flags:--test --test-args --test-threads=1 --nocapture -Zunstable-options
+//@ compile-flags:--test --test-arg --test-threads=1 --test-arg --nocapture -Zunstable-options
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stderr: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

tests/rustdoc-ui/doctest/relative-path-include-bytes-132203.edition2015.stdout

@@ -1,12 +1,12 @@
 
 running 1 test
-test $DIR/relative-path-include-bytes-132203.rs - (line 18) ... FAILED
+test $DIR/relative-path-include-bytes-132203.rs - (line 17) ... FAILED
 
 failures:
 
----- $DIR/relative-path-include-bytes-132203.rs - (line 18) stdout ----
+---- $DIR/relative-path-include-bytes-132203.rs - (line 17) stdout ----
 error: couldn't read `$DIR/relative-dir-empty-file`: $FILE_NOT_FOUND_MSG (os error 2)
-  --> $DIR/relative-path-include-bytes-132203.rs:19:9
+  --> $DIR/relative-path-include-bytes-132203.rs:18:9
    |
 LL | let x = include_bytes!("relative-dir-empty-file");
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -16,7 +16,7 @@ error: aborting due to 1 previous error
 Couldn't compile the test.
 
 failures:
-    $DIR/relative-path-include-bytes-132203.rs - (line 18)
+    $DIR/relative-path-include-bytes-132203.rs - (line 17)
 
 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
 

tests/rustdoc-ui/doctest/relative-path-include-bytes-132203.rs

@@ -2,10 +2,9 @@
 //@[edition2015]edition:2015
 //@[edition2015]check-fail
 //@[edition2015]failure-status: 101
-//@[edition2015]compile-flags:--test --test-args=--test-threads=1
 //@[edition2024]edition:2024
 //@[edition2024]check-pass
-//@[edition2024]compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests.rustdoc-ui.doctest." -> "$$DIR/"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: "`: .* \(os error 2\)" -> "`: $$FILE_NOT_FOUND_MSG (os error 2)"

tests/rustdoc-ui/doctest/test-type.rs

@@ -1,4 +1,4 @@
-//@ compile-flags: --test --test-args=--test-threads=1
+//@ compile-flags: --test --test-arg=--test-threads=1
 //@ check-pass
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

tests/rustdoc-ui/doctest/wrong-ast-2024.rs

@@ -1,5 +1,5 @@
 //@ edition: 2024
-//@ compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

tests/rustdoc-ui/doctest/wrong-ast.rs

@@ -1,4 +1,4 @@
-//@ compile-flags:--test --test-args=--test-threads=1
+//@ compile-flags:--test --test-arg=--test-threads=1
 //@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ failure-status: 101

tests/rustdoc-ui/issues/issue-91134.rs

@@ -1,4 +1,4 @@
-//@ compile-flags: --test --crate-name=empty_fn --extern=empty_fn --test-args=--test-threads=1
+//@ compile-flags: --test --crate-name=empty_fn --extern=empty_fn --test-arg=--test-threads=1
 //@ aux-build:empty-fn.rs
 //@ check-pass
 //@ normalize-stdout: "tests/rustdoc-ui/issues" -> "$$DIR"

tests/rustdoc-ui/opt-test-args-is-deprecated.rs

@@ -0,0 +1,7 @@
+//! Option `--test-args ARGS` has been deprecated in favor of `--test-arg ARG`.
+//! Test that it's still accepted.
+// FIXME: Use this test to check that using this flag will emit a
+//        (hard) deprecation warning once it does.
+
+//@ compile-flags: --test-args argument
+//@ check-pass

tests/rustdoc-ui/remap-path-prefix-failed-doctest-output.rs

@@ -2,7 +2,7 @@
 // adapted to use that, and that normalize line can go away
 
 //@ failure-status: 101
-//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
+//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-arg --test-threads=1
 //@ rustc-env:RUST_BACKTRACE=0
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 //@ normalize-stdout: "exit (status|code): 101" -> "exit status: 101"

tests/rustdoc-ui/remap-path-prefix-invalid-doctest.rs

@@ -2,7 +2,7 @@
 // adapted to use that, and that normalize line can go away
 
 //@ failure-status: 101
-//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
+//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-arg --test-threads=1
 //@ rustc-env:RUST_BACKTRACE=0
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 

tests/rustdoc-ui/remap-path-prefix-passed-doctest-output.rs

@@ -4,7 +4,7 @@
 // FIXME: if/when the output of the test harness can be tested on its own, this test should be
 // adapted to use that, and that normalize line can go away
 
-//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
+//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-arg --test-threads=1
 //@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
 
 // doctest passes at runtime