Skip to content

Commit c262603

Browse files
committed
Deprecate option --test-args in favor of new insta-stable option --test-arg
1 parent 58c2dd9 commit c262603

35 files changed

+86
-52
lines changed

Diff for: src/doc/rustdoc/src/command-line-arguments.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -194,14 +194,14 @@ $ rustdoc src/lib.rs --test
194194
This flag will run your code examples as tests. For more, see [the chapter
195195
on documentation tests](write-documentation/documentation-tests.md).
196196

197-
See also `--test-args` and `--test-run-directory`.
197+
See also `--test-arg` and `--test-run-directory`.
198198

199-
## `--test-args`: pass options to test runner
199+
## `--test-arg`: pass an option to the test runner
200200

201201
Using this flag looks like this:
202202

203203
```bash
204-
$ rustdoc src/lib.rs --test --test-args ignored
204+
$ rustdoc src/lib.rs --test --test-arg ignored --test-arg --show-output
205205
```
206206

207207
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
431431
an empty option. The file can use Unix or Windows style line endings, and must be
432432
encoded as UTF-8.
433433

434+
## `--test-args`: pass options to the test runner
435+
436+
This flag is **deprecated**, use `--test-arg` instead.
437+
434438
## `--passes`: add more rustdoc passes
435439

436440
This flag is **deprecated**.

Diff for: src/librustdoc/config.rs

+11-3
Original file line numberDiff line numberDiff line change
@@ -618,9 +618,17 @@ impl Options {
618618
)
619619
.collect();
620620

621-
let test_args = matches.opt_strs("test-args");
622-
let test_args: Vec<String> =
623-
test_args.iter().flat_map(|s| s.split_whitespace()).map(|s| s.to_string()).collect();
621+
let mut test_args = matches.opt_strs("test-arg");
622+
623+
// FIXME: Emit a (hard) deprecation warning in a few releases from the time of writing
624+
// once at least Cargo has had a good chance to migrate to the new flag.
625+
test_args.extend(
626+
matches
627+
.opt_strs("test-args")
628+
.iter()
629+
.flat_map(|s| s.split_whitespace())
630+
.map(|s| s.to_string()),
631+
);
624632

625633
let should_test = matches.opt_present("test");
626634
let no_run = matches.opt_present("no-run");

Diff for: src/librustdoc/lib.rs

+16-1
Original file line numberDiff line numberDiff line change
@@ -267,7 +267,14 @@ fn opts() -> Vec<RustcOptGroup> {
267267
"",
268268
),
269269
opt(Stable, FlagMulti, "", "test", "run code examples as tests", ""),
270-
opt(Stable, Multi, "", "test-args", "arguments to pass to the test runner", "ARGS"),
270+
opt(
271+
Stable,
272+
Multi,
273+
"",
274+
"test-arg",
275+
"One argument (of possibly many) to pass to the test runner",
276+
"ARG",
277+
),
271278
opt(
272279
Stable,
273280
Opt,
@@ -659,6 +666,14 @@ fn opts() -> Vec<RustcOptGroup> {
659666
"",
660667
),
661668
// deprecated / removed options
669+
opt(
670+
Stable,
671+
Multi,
672+
"",
673+
"test-args",
674+
"Arguments to pass to the test runner. This option is deprecated, use `--test-arg` instead",
675+
"ARGS",
676+
),
662677
opt(
663678
Stable,
664679
Multi,

Diff for: tests/run-make/doctests-merge/rmake.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ fn test_and_compare(input_file: &str, stdout_file: &str, edition: &str, dep: &Pa
99
.input(input_file)
1010
.arg("--test")
1111
.edition(edition)
12-
.arg("--test-args=--test-threads=1")
12+
.arg("--test-arg=--test-threads=1")
1313
.extern_("foo", dep.display().to_string())
1414
.env("RUST_BACKTRACE", "short")
1515
.run();

Diff for: tests/run-make/rustdoc-default-output/output-default.stdout

+5-2
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@ Options:
3434
--document-hidden-items
3535
document items that have doc(hidden)
3636
--test run code examples as tests
37-
--test-args ARGS
38-
arguments to pass to the test runner
37+
--test-arg ARG One argument (of possibly many) to pass to the test
38+
runner
3939
--test-run-directory PATH
4040
The working directory in which to run tests
4141
--target TRIPLE target triple to document
@@ -196,6 +196,9 @@ Options:
196196
--disable-minification
197197
disable the minification of CSS/JS files
198198
(perma-unstable, do not use with cached files)
199+
--test-args ARGS
200+
Arguments to pass to the test runner. This option is
201+
deprecated, use `--test-arg` instead
199202
--plugin-path DIR
200203
removed, see issue #44136
201204
<https://github.com/rust-lang/rust/issues/44136> for

Diff for: tests/rustdoc-ui/2024-doctests-checks.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//@ check-pass
22
//@ edition: 2024
3-
//@ compile-flags: --test --test-args=--test-threads=1
3+
//@ compile-flags: --test --test-arg=--test-threads=1
44
//@ normalize-stdout: "tests/rustdoc-ui" -> "$$DIR"
55
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
66
//@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

Diff for: tests/rustdoc-ui/2024-doctests-crate-attribute.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//@ check-pass
22
//@ edition: 2024
3-
//@ compile-flags: --test --test-args=--test-threads=1
3+
//@ compile-flags: --test --test-arg=--test-threads=1
44
//@ normalize-stdout: "tests/rustdoc-ui" -> "$$DIR"
55
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
66
//@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

Diff for: tests/rustdoc-ui/doctest/cfg-test.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//@ check-pass
2-
//@ compile-flags:--test --test-args --test-threads=1
2+
//@ compile-flags:--test --test-arg --test-threads=1
33
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
44
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
55

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

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

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
// It checks that even if there are comments in the attributes, the attributes
33
// will still be generated correctly (and therefore fail in this test).
44

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

Diff for: tests/rustdoc-ui/doctest/display-output.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
//@ check-pass
44
//@ edition:2018
5-
//@ compile-flags:--test --test-args=--show-output
5+
//@ compile-flags:--test --test-arg=--show-output
66
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
77
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
88

Diff for: tests/rustdoc-ui/doctest/doctest-multiline-crate-attribute.rs

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

Diff for: tests/rustdoc-ui/doctest/doctest-output-include-fail.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//@ edition:2024
2-
//@ compile-flags:--test --test-args=--test-threads=1
2+
//@ compile-flags:--test --test-arg=--test-threads=1
33
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
44
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
55
//@ failure-status: 101
+3-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11

22
running 3 tests
3-
test $DIR/doctest-output.rs - (line 12) ... ok
4-
test $DIR/doctest-output.rs - ExpandedStruct (line 28) ... ok
5-
test $DIR/doctest-output.rs - foo::bar (line 22) ... ok
3+
test $DIR/doctest-output.rs - (line 10) ... ok
4+
test $DIR/doctest-output.rs - ExpandedStruct (line 26) ... ok
5+
test $DIR/doctest-output.rs - foo::bar (line 20) ... ok
66

77
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
88

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11

22
running 3 tests
3-
test $DIR/doctest-output.rs - (line 12) ... ok
4-
test $DIR/doctest-output.rs - ExpandedStruct (line 28) ... ok
5-
test $DIR/doctest-output.rs - foo::bar (line 22) ... ok
3+
test $DIR/doctest-output.rs - (line 10) ... ok
4+
test $DIR/doctest-output.rs - ExpandedStruct (line 26) ... ok
5+
test $DIR/doctest-output.rs - foo::bar (line 20) ... ok
66

77
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
88

Diff for: tests/rustdoc-ui/doctest/doctest-output.rs

+4-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
//@ revisions: edition2015 edition2024
2-
//@[edition2015]edition:2015
3-
//@[edition2015]aux-build:extern_macros.rs
4-
//@[edition2015]compile-flags:--test --test-args=--test-threads=1
5-
//@[edition2024]edition:2024
6-
//@[edition2024]aux-build:extern_macros.rs
7-
//@[edition2024]compile-flags:--test --test-args=--test-threads=1
2+
//@[edition2015] edition: 2015
3+
//@[edition2024] edition: 2024
4+
//@ aux-build:extern_macros.rs
5+
//@ compile-flags:--test --test-arg=--test-threads=1
86
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
97
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
108
//@ check-pass

Diff for: tests/rustdoc-ui/doctest/extern-crate.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//@ check-pass
2-
//@ compile-flags:--test --test-args=--test-threads=1
2+
//@ compile-flags:--test --test-arg=--test-threads=1
33
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
44
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
55

Diff for: tests/rustdoc-ui/doctest/failed-doctest-output-windows.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
// FIXME: if/when the output of the test harness can be tested on its own, this test should be
66
// adapted to use that, and that normalize line can go away
77

8-
//@ compile-flags:--test --test-args --test-threads=1
8+
//@ compile-flags:--test --test-arg --test-threads=1
99
//@ rustc-env:RUST_BACKTRACE=0
1010
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
1111
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

Diff for: tests/rustdoc-ui/doctest/failed-doctest-output.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
// FIXME: if/when the output of the test harness can be tested on its own, this test should be
66
// adapted to use that, and that normalize line can go away
77

8-
//@ compile-flags:--test --test-args --test-threads=1
8+
//@ compile-flags:--test --test-arg --test-threads=1
99
//@ rustc-env:RUST_BACKTRACE=0
1010
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
1111
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"

Diff for: tests/rustdoc-ui/doctest/merged-ignore-no_run.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//@ edition: 2024
2-
//@ compile-flags:--test --test-args=--test-threads=1
2+
//@ compile-flags:--test --test-arg=--test-threads=1
33
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
44
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
55
//@ check-pass

Diff for: tests/rustdoc-ui/doctest/nested-main.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//@ check-pass
2-
//@ compile-flags:--test --test-args=--test-threads=1
2+
//@ compile-flags:--test --test-arg=--test-threads=1
33
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
44
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
55

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// test the behavior of the --no-run flag without the --test flag
22

3-
//@ compile-flags:-Z unstable-options --no-run --test-args=--test-threads=1
3+
//@ compile-flags:-Z unstable-options --no-run --test-arg=--test-threads=1
44

55
pub fn f() {}
66

Diff for: tests/rustdoc-ui/doctest/no-run-flag.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// test the behavior of the --no-run flag
22

33
//@ check-pass
4-
//@ compile-flags:-Z unstable-options --test --no-run --test-args=--test-threads=1
4+
//@ compile-flags:-Z unstable-options --test --no-run --test-arg=--test-threads=1
55
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
66
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
77

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
//@ edition:2018
33
//@ failure-status: 101
44
//@ aux-build:pub_trait.rs
5-
//@ compile-flags: --test --test-args --test-threads=1
5+
//@ compile-flags: --test --test-arg --test-threads=1
66
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
77
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
88

Diff for: tests/rustdoc-ui/doctest/non_local_defs.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//@ check-pass
2-
//@ compile-flags:--test --test-args --test-threads=1 --nocapture -Zunstable-options
2+
//@ compile-flags:--test --test-arg --test-threads=1 --test-arg --nocapture -Zunstable-options
33
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
44
//@ normalize-stderr: "tests/rustdoc-ui/doctest" -> "$$DIR"
55
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11

22
running 1 test
3-
test $DIR/relative-path-include-bytes-132203.rs - (line 18) ... FAILED
3+
test $DIR/relative-path-include-bytes-132203.rs - (line 17) ... FAILED
44

55
failures:
66

7-
---- $DIR/relative-path-include-bytes-132203.rs - (line 18) stdout ----
7+
---- $DIR/relative-path-include-bytes-132203.rs - (line 17) stdout ----
88
error: couldn't read `$DIR/relative-dir-empty-file`: $FILE_NOT_FOUND_MSG (os error 2)
9-
--> $DIR/relative-path-include-bytes-132203.rs:19:9
9+
--> $DIR/relative-path-include-bytes-132203.rs:18:9
1010
|
1111
LL | let x = include_bytes!("relative-dir-empty-file");
1212
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -16,7 +16,7 @@ error: aborting due to 1 previous error
1616
Couldn't compile the test.
1717

1818
failures:
19-
$DIR/relative-path-include-bytes-132203.rs - (line 18)
19+
$DIR/relative-path-include-bytes-132203.rs - (line 17)
2020

2121
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
2222

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

+1-2
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,9 @@
22
//@[edition2015]edition:2015
33
//@[edition2015]check-fail
44
//@[edition2015]failure-status: 101
5-
//@[edition2015]compile-flags:--test --test-args=--test-threads=1
65
//@[edition2024]edition:2024
76
//@[edition2024]check-pass
8-
//@[edition2024]compile-flags:--test --test-args=--test-threads=1
7+
//@ compile-flags:--test --test-arg=--test-threads=1
98
//@ normalize-stdout: "tests.rustdoc-ui.doctest." -> "$$DIR/"
109
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
1110
//@ normalize-stdout: "`: .* \(os error 2\)" -> "`: $$FILE_NOT_FOUND_MSG (os error 2)"

Diff for: tests/rustdoc-ui/doctest/test-type.rs

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

Diff for: tests/rustdoc-ui/doctest/wrong-ast-2024.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
//@ edition: 2024
2-
//@ compile-flags:--test --test-args=--test-threads=1
2+
//@ compile-flags:--test --test-arg=--test-threads=1
33
//@ normalize-stdout: "tests/rustdoc-ui/doctest" -> "$$DIR"
44
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
55
//@ normalize-stdout: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"

Diff for: tests/rustdoc-ui/doctest/wrong-ast.rs

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

Diff for: tests/rustdoc-ui/issues/issue-91134.rs

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

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

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

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
// adapted to use that, and that normalize line can go away
33

44
//@ failure-status: 101
5-
//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
5+
//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-arg --test-threads=1
66
//@ rustc-env:RUST_BACKTRACE=0
77
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
88
//@ normalize-stdout: "exit (status|code): 101" -> "exit status: 101"

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
// adapted to use that, and that normalize line can go away
33

44
//@ failure-status: 101
5-
//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
5+
//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-arg --test-threads=1
66
//@ rustc-env:RUST_BACKTRACE=0
77
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
88

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
// FIXME: if/when the output of the test harness can be tested on its own, this test should be
55
// adapted to use that, and that normalize line can go away
66

7-
//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-args --test-threads=1
7+
//@ compile-flags:--test -Z unstable-options --remap-path-prefix={{src-base}}=remapped_path --test-arg --test-threads=1
88
//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
99

1010
// doctest passes at runtime

0 commit comments

Comments
 (0)