CARGO-SUBUNIT(1)

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 Vernooĳ <jelmer@jelmer.uk>

LICENSE
Apache-2.0