test(cli): Track --help output

This makes it easier to evaluate the usability of PRs, like #11905

tests/testsuite/cargo/help/mod.rs

@@ -0,0 +1,12 @@
+use cargo_test_support::curr_dir;
+use cargo_test_support::prelude::*;
+
+#[cargo_test]
+fn case() {
+    snapbox::cmd::Command::cargo_ui()
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout_matches_path(curr_dir!().join("stdout.log"))
+        .stderr_matches_path(curr_dir!().join("stderr.log"));
+}

tests/testsuite/cargo/help/stdout.log

@@ -0,0 +1,38 @@
+Rust's package manager
+
+Usage: cargo [+toolchain] [OPTIONS] [COMMAND]
+
+Options:
+  -V, --version             Print version info and exit
+      --list                List installed commands
+      --explain <CODE>      Run `rustc --explain CODE`
+  -v, --verbose...          Use verbose output (-vv very verbose/build.rs output)
+  -q, --quiet               Do not print cargo log messages
+      --color <WHEN>        Coloring: auto, always, never
+  -C <DIRECTORY>            Change to DIRECTORY before doing anything
+      --frozen              Require Cargo.lock and cache are up to date
+      --locked              Require Cargo.lock is up to date
+      --offline             Run without accessing the network
+      --config <KEY=VALUE>  Override a configuration value
+  -Z <FLAG>                 Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+  -h, --help                Print help
+
+Some common cargo commands are (see all commands with --list):
+    build, b    Compile the current package
+    check, c    Analyze the current package and report errors, but don't build object files
+    clean       Remove the target directory
+    doc, d      Build this package's and its dependencies' documentation
+    new         Create a new cargo package
+    init        Create a new cargo package in an existing directory
+    add         Add dependencies to a manifest file
+    remove      Remove dependencies from a manifest file
+    run, r      Run a binary or example of the local package
+    test, t     Run the tests
+    bench       Run the benchmarks
+    update      Update dependencies listed in Cargo.lock
+    search      Search registry for crates
+    publish     Package and upload this package to the registry
+    install     Install a Rust binary. Default location is $HOME/.cargo/bin
+    uninstall   Uninstall a Rust binary
+
+See 'cargo help <command>' for more information on a specific command.

tests/testsuite/cargo/mod.rs

@@ -0,0 +1 @@
+mod help;

tests/testsuite/cargo_add/help/mod.rs

@@ -0,0 +1,13 @@
+use cargo_test_support::curr_dir;
+use cargo_test_support::prelude::*;
+
+#[cargo_test]
+fn case() {
+    snapbox::cmd::Command::cargo_ui()
+        .arg("add")
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout_matches_path(curr_dir!().join("stdout.log"))
+        .stderr_matches_path(curr_dir!().join("stderr.log"));
+}

tests/testsuite/cargo_add/help/stdout.log

@@ -0,0 +1,117 @@
+Add dependencies to a Cargo.toml manifest file
+
+Usage: cargo add [OPTIONS] <DEP>[@<VERSION>] ...
+       cargo add [OPTIONS] --path <PATH> ...
+       cargo add [OPTIONS] --git <URL> ...
+
+Arguments:
+  [DEP_ID]...
+          Reference to a package to add as a dependency
+
+          You can reference a package by:
+          - `<name>`, like `cargo add serde` (latest version will be used)
+          - `<name>@<version-req>`, like `cargo add serde@1` or `cargo add serde@=1.0.38`
+
+Options:
+      --no-default-features
+          Disable the default features
+
+      --default-features
+          Re-enable the default features
+
+  -F, --features <FEATURES>
+          Space or comma separated list of features to activate
+
+      --optional
+          Mark the dependency as optional
+
+          The package name will be exposed as feature of your crate.
+
+  -v, --verbose...
+          Use verbose output (-vv very verbose/build.rs output)
+
+      --no-optional
+          Mark the dependency as required
+
+          The package will be removed from your features.
+
+      --color <WHEN>
+          Coloring: auto, always, never
+
+      --rename <NAME>
+          Rename the dependency
+
+          Example uses:
+          - Depending on multiple versions of a crate
+          - Depend on crates with the same name from different registries
+
+      --manifest-path <PATH>
+          Path to Cargo.toml
+
+      --frozen
+          Require Cargo.lock and cache are up to date
+
+  -p, --package [<SPEC>]
+          Package to modify
+
+      --locked
+          Require Cargo.lock is up to date
+
+  -q, --quiet
+          Do not print cargo log messages
+
+      --dry-run
+          Don't actually write the manifest
+
+      --offline
+          Run without accessing the network
+
+      --config <KEY=VALUE>
+          Override a configuration value
+
+  -Z <FLAG>
+          Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Source:
+      --path <PATH>
+          Filesystem path to local crate to add
+
+      --git <URI>
+          Git repository location
+
+          Without any other information, cargo will use latest commit on the main branch.
+
+      --branch <BRANCH>
+          Git branch to download the crate from
+
+      --tag <TAG>
+          Git tag to download the crate from
+
+      --rev <REV>
+          Git reference to download the crate from
+
+          This is the catch all, handling hashes to named references in remote repositories.
+
+      --registry <NAME>
+          Package registry for this dependency
+
+Section:
+      --dev
+          Add as development dependency
+
+          Dev-dependencies are not used when compiling a package for building, but are used for compiling tests, examples, and benchmarks.
+
+          These dependencies are not propagated to other packages which depend on this package.
+
+      --build
+          Add as build dependency
+
+          Build-dependencies are the only dependencies available for use by build scripts (`build.rs` files).
+
+      --target <TARGET>
+          Add as dependency to the given target platform
+
+Run `cargo help add` for more detailed information.

tests/testsuite/cargo_add/mod.rs

@@ -33,6 +33,7 @@ mod git_normalized_name;
 mod git_registry;
 mod git_rev;
 mod git_tag;
+mod help;
 mod infer_prerelease;
 mod invalid_arg;
 mod invalid_git_external;

tests/testsuite/cargo_bench/help/mod.rs

@@ -0,0 +1,13 @@
+use cargo_test_support::curr_dir;
+use cargo_test_support::prelude::*;
+
+#[cargo_test]
+fn case() {
+    snapbox::cmd::Command::cargo_ui()
+        .arg("bench")
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout_matches_path(curr_dir!().join("stdout.log"))
+        .stderr_matches_path(curr_dir!().join("stderr.log"));
+}

tests/testsuite/cargo_bench/help/stdout.log

@@ -0,0 +1,49 @@
+Execute all benchmarks of a local package
+
+Usage: cargo[EXE] bench [OPTIONS] [BENCHNAME] [-- [args]...]
+
+Arguments:
+  [BENCHNAME]  If specified, only run benches containing this string in their names
+  [args]...    Arguments for the bench binary
+
+Options:
+  -q, --quiet                   Do not print cargo log messages
+      --lib                     Benchmark only this package's library
+      --bin [<NAME>]            Benchmark only the specified binary
+      --bins                    Benchmark all binaries
+  -v, --verbose...              Use verbose output (-vv very verbose/build.rs output)
+      --example [<NAME>]        Benchmark only the specified example
+      --color <WHEN>            Coloring: auto, always, never
+      --examples                Benchmark all examples
+      --test [<NAME>]           Benchmark only the specified test target
+      --frozen                  Require Cargo.lock and cache are up to date
+      --tests                   Benchmark all tests
+      --bench [<NAME>]          Benchmark only the specified bench target
+      --locked                  Require Cargo.lock is up to date
+      --benches                 Benchmark all benches
+      --offline                 Run without accessing the network
+      --all-targets             Benchmark all targets
+      --config <KEY=VALUE>      Override a configuration value
+      --no-run                  Compile, but don't run benchmarks
+  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+  -p, --package [<SPEC>]        Package to run benchmarks for
+      --workspace               Benchmark all packages in the workspace
+      --exclude <SPEC>          Exclude packages from the benchmark
+      --all                     Alias for --workspace (deprecated)
+  -j, --jobs <N>                Number of parallel jobs, defaults to # of CPUs
+      --keep-going              Do not abort the build as soon as there is an error (unstable)
+      --profile <PROFILE-NAME>  Build artifacts with the specified profile
+  -F, --features <FEATURES>     Space or comma separated list of features to activate
+      --all-features            Activate all available features
+      --no-default-features     Do not activate the `default` feature
+      --target <TRIPLE>         Build for the target triple
+      --target-dir <DIRECTORY>  Directory for all generated artifacts
+      --manifest-path <PATH>    Path to Cargo.toml
+      --ignore-rust-version     Ignore `rust-version` specification in packages
+      --message-format <FMT>    Error format
+      --no-fail-fast            Run all benchmarks regardless of failure
+      --unit-graph              Output build graph in JSON (unstable)
+      --timings[=<FMTS>]        Timing output formats (unstable) (comma separated): html, json
+  -h, --help                    Print help
+
+Run `cargo help bench` for more detailed information.

tests/testsuite/cargo_bench/mod.rs

@@ -0,0 +1 @@
+mod help;

tests/testsuite/cargo_build/help/mod.rs

@@ -0,0 +1,13 @@
+use cargo_test_support::curr_dir;
+use cargo_test_support::prelude::*;
+
+#[cargo_test]
+fn case() {
+    snapbox::cmd::Command::cargo_ui()
+        .arg("build")
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout_matches_path(curr_dir!().join("stdout.log"))
+        .stderr_matches_path(curr_dir!().join("stderr.log"));
+}

tests/testsuite/cargo_build/help/stdout.log

@@ -0,0 +1,47 @@
+Compile a local package and all of its dependencies
+
+Usage: cargo[EXE] build [OPTIONS]
+
+Options:
+  -q, --quiet                   Do not print cargo log messages
+  -p, --package [<SPEC>]        Package to build (see `cargo help pkgid`)
+      --workspace               Build all packages in the workspace
+      --exclude <SPEC>          Exclude packages from the build
+  -v, --verbose...              Use verbose output (-vv very verbose/build.rs output)
+      --all                     Alias for --workspace (deprecated)
+      --color <WHEN>            Coloring: auto, always, never
+  -j, --jobs <N>                Number of parallel jobs, defaults to # of CPUs
+      --keep-going              Do not abort the build as soon as there is an error (unstable)
+      --frozen                  Require Cargo.lock and cache are up to date
+      --lib                     Build only this package's library
+      --bin [<NAME>]            Build only the specified binary
+      --locked                  Require Cargo.lock is up to date
+      --bins                    Build all binaries
+      --offline                 Run without accessing the network
+      --config <KEY=VALUE>      Override a configuration value
+      --example [<NAME>]        Build only the specified example
+      --examples                Build all examples
+  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+      --test [<NAME>]           Build only the specified test target
+      --tests                   Build all tests
+      --bench [<NAME>]          Build only the specified bench target
+      --benches                 Build all benches
+      --all-targets             Build all targets
+  -r, --release                 Build artifacts in release mode, with optimizations
+      --profile <PROFILE-NAME>  Build artifacts with the specified profile
+  -F, --features <FEATURES>     Space or comma separated list of features to activate
+      --all-features            Activate all available features
+      --no-default-features     Do not activate the `default` feature
+      --target <TRIPLE>         Build for the target triple
+      --target-dir <DIRECTORY>  Directory for all generated artifacts
+      --out-dir <PATH>          Copy final artifacts to this directory (unstable)
+      --manifest-path <PATH>    Path to Cargo.toml
+      --ignore-rust-version     Ignore `rust-version` specification in packages
+      --message-format <FMT>    Error format
+      --build-plan              Output the build plan in JSON (unstable)
+      --unit-graph              Output build graph in JSON (unstable)
+      --future-incompat-report  Outputs a future incompatibility report at the end of the build
+      --timings[=<FMTS>]        Timing output formats (unstable) (comma separated): html, json
+  -h, --help                    Print help
+
+Run `cargo help build` for more detailed information.

tests/testsuite/cargo_build/mod.rs

@@ -0,0 +1 @@
+mod help;

tests/testsuite/cargo_check/help/mod.rs

@@ -0,0 +1,13 @@
+use cargo_test_support::curr_dir;
+use cargo_test_support::prelude::*;
+
+#[cargo_test]
+fn case() {
+    snapbox::cmd::Command::cargo_ui()
+        .arg("check")
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout_matches_path(curr_dir!().join("stdout.log"))
+        .stderr_matches_path(curr_dir!().join("stderr.log"));
+}

tests/testsuite/cargo_check/help/stdout.log

@@ -0,0 +1,45 @@
+Check a local package and all of its dependencies for errors
+
+Usage: cargo[EXE] check [OPTIONS]
+
+Options:
+  -q, --quiet                   Do not print cargo log messages
+  -p, --package [<SPEC>]        Package(s) to check
+      --workspace               Check all packages in the workspace
+      --exclude <SPEC>          Exclude packages from the check
+  -v, --verbose...              Use verbose output (-vv very verbose/build.rs output)
+      --all                     Alias for --workspace (deprecated)
+      --color <WHEN>            Coloring: auto, always, never
+  -j, --jobs <N>                Number of parallel jobs, defaults to # of CPUs
+      --keep-going              Do not abort the build as soon as there is an error (unstable)
+      --frozen                  Require Cargo.lock and cache are up to date
+      --lib                     Check only this package's library
+      --bin [<NAME>]            Check only the specified binary
+      --locked                  Require Cargo.lock is up to date
+      --bins                    Check all binaries
+      --offline                 Run without accessing the network
+      --config <KEY=VALUE>      Override a configuration value
+      --example [<NAME>]        Check only the specified example
+      --examples                Check all examples
+  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+      --test [<NAME>]           Check only the specified test target
+      --tests                   Check all tests
+      --bench [<NAME>]          Check only the specified bench target
+      --benches                 Check all benches
+      --all-targets             Check all targets
+  -r, --release                 Check artifacts in release mode, with optimizations
+      --profile <PROFILE-NAME>  Check artifacts with the specified profile
+  -F, --features <FEATURES>     Space or comma separated list of features to activate
+      --all-features            Activate all available features
+      --no-default-features     Do not activate the `default` feature
+      --target <TRIPLE>         Check for the target triple
+      --target-dir <DIRECTORY>  Directory for all generated artifacts
+      --manifest-path <PATH>    Path to Cargo.toml
+      --ignore-rust-version     Ignore `rust-version` specification in packages
+      --message-format <FMT>    Error format
+      --unit-graph              Output build graph in JSON (unstable)
+      --future-incompat-report  Outputs a future incompatibility report at the end of the build
+      --timings[=<FMTS>]        Timing output formats (unstable) (comma separated): html, json
+  -h, --help                    Print help
+
+Run `cargo help check` for more detailed information.

tests/testsuite/cargo_check/mod.rs

@@ -0,0 +1 @@
+mod help;

tests/testsuite/cargo_clean/help/mod.rs

@@ -0,0 +1,13 @@
+use cargo_test_support::curr_dir;
+use cargo_test_support::prelude::*;
+
+#[cargo_test]
+fn case() {
+    snapbox::cmd::Command::cargo_ui()
+        .arg("clean")
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout_matches_path(curr_dir!().join("stdout.log"))
+        .stderr_matches_path(curr_dir!().join("stderr.log"));
+}