NAME¶

cargo-subunit - Run Rust tests and output results in subunit format

SYNOPSIS¶

cargo subunit [--list] [--load-list FILE] [CARGO_ARGS...] [-- TEST_ARGS...]

DESCRIPTION¶

cargo-subunit is a Cargo extension that runs Rust tests and outputs results in subunit v2 format. This enables integration with subunit tools and test runners like testrepository(1).

The tool uses cargo test's unstable JSON output format to capture test events, which are then converted to subunit v2 format. This allows test results to be consumed by various subunit-compatible tools for analysis, reporting, and test management.

OPTIONS¶

--list

List all available tests without running them. Each test is output as a subunit "exists" event with its fully-qualified name (e.g., module::submodule::test_name).

--load-list FILE

Load test names from FILE (one test name per line) and run only those tests. Empty lines are ignored.

--help

Display help information and exit.

--version

Display version information and exit.

ARGUMENTS¶

CARGO_ARGS

Arguments to pass to cargo test, such as package selection flags (--package, --workspace), feature flags (--features, --no-default-features), or compilation options (--release).

TEST_ARGS

Arguments to pass to the test binary, which must be preceded by --. Common test arguments include --nocapture (display stdout/stderr), --test-threads (number of parallel test threads), and test name filters.

OUTPUT FORMAT¶

cargo-subunit writes subunit v2 binary format to stdout. The output can be redirected to a file or piped to subunit analysis tools.

For --list mode, each test generates an "exists" event with the test ID.

For running tests, the following events are generated:

• An "inprogress" event when the test starts
• A "success", "fail", or "skip" event when complete
• For failures, stdout/stderr are attached as file content

EXAMPLES¶

List all available tests:

cargo subunit --list

Run all tests with subunit output:

cargo subunit > results.subunit

Run specific tests matching a pattern:

cargo subunit test_name
cargo subunit module::

Run tests from a file:

echo module::test_one > tests.txt
echo module::test_two >> tests.txt
cargo subunit --load-list tests.txt

Pass additional cargo test arguments:

cargo subunit -- --nocapture
cargo subunit -- --test-threads=1

Run tests in release mode:

cargo subunit --release

INTEGRATION WITH TESTREPOSITORY¶

cargo-subunit integrates with testrepository(1) for tracking test history and running tests efficiently.

Create a .testr.conf file in your project root:

[DEFAULT]
test_command=cargo subunit $LISTOPT $IDOPTION
test_id_option=--load-list $IDFILE
test_list_option=--list

Then use testrepository commands:

testr run

Run all tests and record results

testr run --failing

Run only failed tests from the last run

testr last

List test runs

testr last --subunit | subunit-stats

Show results from the last run

EXIT STATUS¶

cargo-subunit exits with the same status code as the underlying cargo test command. Typically:

0

All tests passed successfully

101

One or more tests failed

other

Compilation or other error occurred

REQUIREMENTS¶

• Rust 2021 edition or later
• The subunit crate for protocol serialization

SEE ALSO¶

cargo(1), cargo-test(1), testrepository(1), subunit-stats(1)

Subunit protocol specification: https://github.com/testing-cabal/subunit

Project repository: https://github.com/jelmer/cargo-subunit

AUTHOR¶

Written by Jelmer Vernooij <jelmer@jelmer.uk>

LICENSE¶

Apache-2.0