Struct Trial

pub struct Trial { /* private fields */ }

A single test or benchmark.

The original libtest often calls benchmarks “tests”, which is a bit confusing. So in this library, it is called “trial”.

A trial is created via Trial::test or Trial::bench. The trial’s name is printed and used for filtering. The runner is called when the test/benchmark is executed to determine its outcome. If runner panics, the trial is considered “failed”. If you need the behavior of #[should_panic] you need to catch the panic yourself. You likely want to compare the panic payload to an expected value anyway.

Implementations

impl Trial

pub fn test<R>(name: impl Into<String>, runner: R) -> Self

where R: FnOnce() -> Result<(), Failed> + Send + 'static,

Creates a (non-benchmark) test with the given name and runner.

The runner returning Ok(()) is interpreted as the test passing. If the runner returns Err(_), the test is considered failed.

pub fn bench<R>(name: impl Into<String>, runner: R) -> Self

where R: FnOnce(bool) -> Result<Option<Measurement>, Failed> + Send + 'static,

Creates a benchmark with the given name and runner.

If the runner’s parameter test_mode is true, the runner function should run all code just once, without measuring, just to make sure it does not panic. If the parameter is false, it should perform the actual benchmark. If test_mode is true you may return Ok(None), but if it’s false, you have to return a Measurement, or else the benchmark is considered a failure.

test_mode is true if neither --bench nor --test are set, and false when --bench is set. If --test is set, benchmarks are not ran at all, and both flags cannot be set at the same time.

pub fn with_kind(self, kind: impl Into<String>) -> Self

Sets the “kind” of this test/benchmark. If this string is not empty, it is printed in brackets before the test name (e.g. test [my-kind] test_name). (Default: empty)

This is the only extension to the original libtest.

pub fn with_ignored_flag(self, is_ignored: bool) -> Self

Sets whether or not this test is considered “ignored”. (Default: false)

With the built-in test suite, you can annotate #[ignore] on tests to not execute them by default (for example because they take a long time or require a special environment). If the --ignored flag is set, ignored tests are executed, too.

pub fn name(&self) -> &str

Returns the name of this trial.

pub fn kind(&self) -> &str

Returns the kind of this trial. If you have not set a kind, this is an empty string.

pub fn has_ignored_flag(&self) -> bool

Returns whether this trial has been marked as ignored.

pub fn is_test(&self) -> bool

Returns true iff this trial is a test (as opposed to a benchmark).

pub fn is_bench(&self) -> bool

Returns true iff this trial is a benchmark (as opposed to a test).

Trait Implementations

impl Debug for Trial

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.