Crate cargo_testdox 

Subscribe to learn Rust with me!

cargo-testdox

A Cargo subcommand to print your Rust test names as sentences.

Installation

cargo install cargo-testdox

Usage

In any Rust project with tests, run:

cargo testdox

cargo-testdox will first invoke cargo test to run your tests, with any extra arguments that you give it. It will then show the result for each test (passed, failed, or ignored), with the test name formatted as a sentence. That is, with underscores replaced by spaces.

For example, the following test:

#[test]
fn it_works() {}

will produce this output when run with cargo-testdox:

 ✔ it works

If the test were failing, it would produce:

 x it works

If the test were ignored, it would produce:

 ? it works

If the test were ignored with a reason ([ignore = "expensive"]), it would produce:

 ? [expensive] it works

If the test were in a module foo::bar, it would produce:

 ✔ foo::bar — it works

However, if the module path ends with test or tests, this part is omitted, and the name of the parent module (if there is one) is used instead. For example, if the module is foo::tests:

 ✔ foo — it works

Doctests are ignored, since they can’t currently be named (pending RFC #3311).

Function names with underscores

To avoid underscores in a snake-case function name from being replaced, put _fn_ after the function name:

#[test]
fn print_hello_world_fn_prints_hello_world() {}

becomes:

✔ print_hello_world prints hello world

Why

Because test names should be sentences.

Compare gotestdox, a similar tool for Go tests.

This is an example project from my book The Secrets of Rust: Tools.

Structs

TestResult

The (prettified) name and pass/fail status of a given test.

Enums

Status

The status of a given test, as reported by cargo test.

Functions

get_cargo_test_output

Runs cargo test with any supplied extra arguments, and returns the resulting standard output.

parse_line

Parses a line from the standard output of cargo test.

parse_test_results

Parses the standard output of cargo test into a vec of TestResult.

prettify

Formats the name of a test function as a sentence.