How to Build and Test a Cargo Subcommand

To make a command work as cargo <command>, build an executable named cargo-<command> and put it in a directory Cargo searches on PATH. Then verify Cargo’s argument and help conventions, test the logic and integration behavior, and run the package’s full test suite.

How Cargo finds and invokes an external subcommand

When a user runs cargo lint, for example, Cargo looks for an executable named cargo-lint. That executable must be in a directory on the user’s PATH. By default, Cargo gives executables in $CARGO_HOME/bin priority over other PATH directories; users can alter that precedence by adding $CARGO_HOME/bin to PATH. See the Cargo Book’s External tools reference.

#	Preview	Product	Price
1		Competitive Programming 4 - Book 2: The Lower Bound of Programming Contests in the 2020s	$24.00	Buy on Amazon
2		The C Programming Language	$9.80	Buy on Amazon

The executable receives arguments in a specific order: its own filename is argument one, the subcommand name is argument two, and arguments after the subcommand are forwarded unchanged. Check this convention in your argument parser rather than treating the first argument as a user-supplied option. Cargo also expects an external subcommand to display help when its third argument is --help; supporting this allows cargo help lint to request the tool’s help.

Build and inspect the subcommand

Compile the local package

Run cargo build to compile the selected local packages and their dependencies. This is the basic check that the executable builds. The Cargo build reference documents the command’s package and target selection options.

#1 Best Overall

Competitive Programming 4 - Book 2: The Lower Bound of Programming Contests in the 2020s

$24.00

Buy on Amazon

Use Cargo’s CLI for project information

If the subcommand needs workspace, package, or dependency details, prefer invoking Cargo through its command-line interface rather than linking the Cargo library. Use the CARGO environment variable to locate the Cargo executable. The Cargo library API is unstable, and its version can differ from the Cargo executable, so depending on it can create compatibility problems. For a machine-readable view of workspace members and resolved dependencies, run cargo metadata --format-version 1. Specifying the format version helps guard your tool against changes to the output format. See the cargo metadata reference.

Test the command at the right level

Keep unit and documentation tests with the code

Put unit tests alongside the source they exercise, and documentation tests with the relevant documentation. These tests are useful for checking argument parsing and internal logic without needing to invoke the command through Cargo.

Put integration tests in tests/

Integration tests belong under the package’s tests/ directory and should exercise behavior through the crate’s public interface. Run them with cargo test; Cargo normally builds and runs unit, integration, and documentation test targets. The Cargo Book explains the distinction in its tests guide.

If an integration test needs to run a binary built by the package, do not guess its location under target/. Cargo builds the required binary for a selected integration test and sets CARGO_BIN_EXE_<name>, which the test can use to locate it. The cargo test reference describes this environment variable and test target behavior.

Run tests, focus a target, or compile without running

Use cargo test for the normal run. Cargo accepts target selectors when you need to focus on a particular package or test target; consult its reference for the exact selector that fits your workspace. To check that test targets compile without executing them, use cargo test --no-run. Arguments placed after -- are passed to the test binary, while arguments before it are interpreted by Cargo—for example, test harness options belong after the separator.

Rank #2

The C Programming Language

$9.80

Buy on Amazon

A practical verification sequence

1. Build the package with cargo build and ensure the resulting executable is named cargo-<command>.

2. Place the executable in a directory Cargo searches on PATH, then invoke cargo <command> and confirm the tool receives its filename, command token, and forwarded arguments in the expected positions.

3. Check help handling by invoking cargo help <command> and confirming the subcommand prints its help when it receives --help as its third argument.

   ×Drivers · Free Tool

   Outdated Drivers Are Slowing You Down

   One free scan finds every outdated or missing driver and matches the right update for your exact hardware.

   Scan My Drivers Free →Free scan · exact hardware match

   Fix Windows issues →Stop driver crashes →
   Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

4. Run focused unit tests for argument parsing and internal behavior, followed by integration tests for the Cargo-facing behavior. Use CARGO_BIN_EXE_<name> in an integration test that must launch a package binary.

5. Run cargo test for the package’s usual test suite. Use cargo test --no-run when you only need to verify test compilation.

   Quick Recap

   Bestseller No. 1

   

   Competitive Programming 4 - Book 2: The Lower Bound of Programming Contests in the 2020s

   $24.00

   Bestseller No. 2

   

   The C Programming Language

   $9.80

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.