CARGO-SUBUNIT(1)

💖 CARGO-SUBUNIT 💖

okay bestie, so this is cargo-subunit — a manual page from the User Commands section, and honestly? it's giving ✨test infrastructure but make it cute✨. stay with me.

---

🌸 NAME 🌸

cargo-subunit — run Rust tests and spit the results out in subunit format. that's it, that's the whole vibe.

---

🦋 SYNOPSIS 🦋

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

like literally just cargo subunit and then whatever else you want to throw at it. she's flexible 💅

---

🎀 DESCRIPTION 🎀

cargo-subunit is a Cargo extension that runs your Rust tests and outputs the results in subunit v2 format. why do you care? because this is what lets your test results talk to subunit tools and test runners like testrepository(1). it's a whole ecosystem and we're integrating with it, no cap.

the way it works: the tool uses cargo test's unstable JSON output format to capture test events, and then converts those into subunit v2 format. so basically it's a lil translator 🧚 that lets all these subunit-compatible tools consume your test results for analysis, reporting, and test management. periodt.

heads up: that's cargo test's unstable JSON output it's leaning on — that's what the page says, so don't come for me.

---

✨ OPTIONS ✨

• --list — list every available test without running them. each test gets output as a subunit "exists" event with its fully-qualified name (like module::submodule::test_name). window shopping, but for tests 👀
• --load-list FILE — load test names from FILE (one test name per line) and run only those tests. empty lines? ignored. queen of efficiency.
• --help — display help info and dip out.
• --version — display version info and dip out.

---

🌈 ARGUMENTS 🌈

• CARGO_ARGS — args you pass along to cargo test, like package selection flags (--package, --workspace), feature flags (--features, --no-default-features), or compilation options (--release). all your faves 💖
• TEST_ARGS — args passed to the test binary, and these must be preceded by --. common ones include --nocapture (show stdout/stderr, we love a chatty test), --test-threads (number of parallel test threads), and test name filters.

---

💅 OUTPUT FORMAT 💅

cargo-subunit writes subunit v2 binary format to stdout. you can redirect that to a file or pipe it into subunit analysis tools. chef's kiss 🍓

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

for actually running tests, here's the event lineup:

• an "inprogress" event when the test starts
• a "success", "fail", or "skip" event when it's complete
• for failures, stdout/stderr get attached as file content

---

⭐ EXAMPLES ⭐

list all the available tests:

cargo subunit --list

run everything and get 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 extra cargo test args:

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

run tests in release mode:

cargo subunit --release

---

🧚 INTEGRATION WITH TESTREPOSITORY 🧚

cargo-subunit plays nice with testrepository(1) for tracking test history and running tests efficiently. it's a situationship that actually works 🫶

make 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 the testrepository commands:

• testr run — run all tests and record results
• testr run --failing — run only the 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

---

and that's the whole page bestie, fr fr. this manual documents cargo-subunit 0.1.1, dated 2025-11-12, and it lives in the CARGO-SUBUNIT(1) section of the manual. go forth and slay your test suite 💅✨🦋