Crate libtest_mimic

source ·
Expand description

Write your own tests and benchmarks that look and behave like built-in tests!

This is a simple and small test harness that mimics the original libtest (used by cargo test/rustc --test). That means: all output looks pretty much like cargo test and most CLI arguments are understood and used. With that plumbing work out of the way, your test runner can focus on the actual testing.

For a small real world example, see examples/tidy.rs.

Usage

To use this, you most likely want to add a manual [[test]] section to Cargo.toml and set harness = false. For example:

[[test]]
name = "mytest"
path = "tests/mytest.rs"
harness = false

And in tests/mytest.rs you would call run in the main function:

use libtest_mimic::{Arguments, Trial};


// Parse command line arguments
let args = Arguments::from_args();

// Create a list of tests and/or benchmarks (in this case: two dummy tests).
let tests = vec![
    Trial::test("succeeding_test", move || Ok(())),
    Trial::test("failing_test", move || Err("Woops".into())),
];

// Run all tests and exit the application appropriatly.
libtest_mimic::run(&args, tests).exit();

Instead of returning Ok or Err directly, you want to actually perform your tests, of course. See Trial::test for more information on how to define a test. You can of course list all your tests manually. But in many cases it is useful to generate one test per file in a directory, for example.

You can then run cargo test --test mytest to run it. To see the CLI arguments supported by this crate, run cargo test --test mytest -- -h.

Known limitations and differences to the official test harness

libtest-mimic works on a best-effort basis: it tries to be as close to libtest as possible, but there are differences for a variety of reasons. For example, some rarely used features might not be implemented, some features are extremely difficult to implement, and removing minor, unimportant differences is just not worth the hassle.

Some of the notable differences:

  • Output capture and --nocapture: simply not supported. The official libtest uses internal std functions to temporarily redirect output. libtest-mimic cannot use those. See this issue for more information.
  • --format=json|junit

Structs

  • Arguments
    Command line arguments.
  • Conclusion
    Contains information about the entire test run. Is returned byrun.
  • Failed
    Indicates that a test/benchmark has failed. Optionally carries a message.
  • Measurement
    Output of a benchmark.
  • Trial
    A single test or benchmark.

Enums

Functions

  • run
    Runs all given trials (tests & benchmarks).