Struct Dicetest

pub struct Dicetest { /* private fields */ }

Front end for configuring and running a test with pseudorandomly generated test data.

You can set the test parameters via source code or environment variables.

Examples

Runs the test repeatedly with default config:

use dicetest::Dicetest;

Dicetest::repeatedly().run(|_fate| {
    // Put your test here.
});

Runs the test repeatedly with custom config:

use dicetest::Dicetest;

Dicetest::repeatedly().passes(42).run(|_fate| {
    // Put your test here.
});

Runs the test once with the given run code (printed when a test had failed):

use dicetest::Dicetest;

Dicetest::debug("ABIDje/+CYVkmmCVTwKJ2go6VrzZWMjO2Bqc9m3b3h0DAAAAAAAAAA==").run(|_fate| {
    // Put your test here.
});

Implementations

impl Dicetest

pub fn debug(run_code: &str) -> Self

Configuration for running the test in debug mode.

In this mode the test will be run once. The parameters for pseudorandom value generation will be extracted from the given run code.

Panics

Panics if the run code is invalid.

Environment

You can set this mode with DICETEST_DEBUG=<run code>. The value <run code> must be a valid run code.

pub fn once() -> Self

Configuration for running the test in run-once mode.

In this mode the test will be run once. In contrast to debug mode, the Seed and Limit can be set separately via Dicetest::seed and Dicetest::once_limit.

Environment

You can set this mode via DICETEST_MODE=once.

pub fn repeatedly() -> Self

Configuration for running the test in run-repeatedly mode.

In this mode the test will be run repeatedly until the configured number of passes has been reached or the test has panicked. If the test has panicked, a counterexample has been found. The counterexample can be debugged using the debug mode, see Dicetest::debug.

Environment

You can set this mode via DICETEST_MODE=repeatedly.

pub fn seed(self, seed: Option<Seed>) -> Self

Sets the initial Seed for the pseudorandom value generation.

It’s only used in run-once and run-repeatedly mode and is None by default. In case of None the Seed will be randomly generated.

Environment

You can set this parameter via DICETEST_SEED=<seed>. The value <seed> must be either none or <u64>.

pub fn once_limit(self, once_limit: Limit) -> Self

Sets the upper limit for the length of generated dynamic data structures.

It’s only used in run-once mode and is 100 by default.

Environment

You can set this parameter via DICETEST_ONCE_LIMIT=<u64>.

pub fn start_limit(self, start_limit: Limit) -> Self

Sets the initial upper limit for the length of generated dynamic data structures.

It will be used for the first test run. The following test runs use an interpolated limit, see Dicetest::end_limit. It’s only used in run-repeatedly mode and is 0 by default.

Environment

You can set this parameter via DICETEST_START_LIMIT=<u64>.

pub fn end_limit(self, end_limit: Limit) -> Self

Sets the final upper limit for the length of generated dynamic data structures.

It will be used for the last test run. The previous test runs use an interpolated limit, see Dicetest::start_limit. It’s only used in run-repeatedly mode and is 100 by default.

Environment

You can set this parameter via DICETEST_END_LIMIT=<u64>.

pub fn limit_multiplier(self, limit_multiplier: Option<f64>) -> Self

Sets the multiplier for the Limit.

It will be applied to the values that can be set via Dicetest::once_limit, Dicetest::start_limit and Dicetest::end_limit before running the test.

Environment

You can set this parameter via DICETEST_LIMIT_MULTIPLIER=<factor>. The value <factor> must be either none or <f64>.

pub fn passes(self, passes: u64) -> Self

Sets how many times the test needs to be run without failing.

It’s only used in run-repeatedly mode and is 200 by default.

Environment

You can set this parameter via DICETEST_PASSES=<u64>.

pub fn passes_multiplier(self, passes_multiplier: Option<f64>) -> Self

Sets the multiplier for the number of passes.

It will be applied to the value that can be set via Dicetest::passes before running the test.

Environment

You can set this parameter via DICETEST_PASSES_MULTIPLIER=<factor>. The value <factor> must be either none or <f64>.

pub fn hints_enabled(self, hints_enabled: bool) -> Self

Sets whether hints are collected during the test run.

In run-once and debug mode hints are collected during the single test run. In run-repeatedly mode hints are only collected if a counterexample has been found. The counterexample will be rerun to collect the hints. Rerunning the counterexample can fail if the test is not deterministic.

This parameter is true by default. It works only work if the feature hints is present.

Environment

You can set this parameter via DICETEST_HINTS_ENABLED=<bool>.

pub fn stats_enabled(self, stats_enabled: bool) -> Self

Sets whether stats are collected during the test runs.

In run-once and debug mode stats are collected during the single test run. In run-repeatedly mode stats are collected during all test runs (except the rerun of the counterexample).

This parameter is false by default. It works only work if the feature stats is present.

Environment

You can set this parameter via DICETEST_STATS_ENABLED=<bool>.

pub fn stats_max_value_count(self, stats_max_value_count: Option<usize>) -> Self

Sets the maximum numbers of values per key that will be used when formatting the stats.

If None all values will be present in the result. This parameter is Some(20) by default.

Environment

You can set this parameter via DICETEST_STATS_MAX_VALUE_COUNT=<max_value_count>. The value <max_value_count> must be either none or <usize>.

pub fn stats_percent_precision(self, stats_percent_precision: usize) -> Self

Sets the number of decimal places for percent values that will be used when formatting the stats.

This parameter is 2 by default.

Environment

You can set this parameter via DICETEST_STATS_PERCENT_PRECISION=<usize>.

pub fn env_enabled(self, env_enabled: bool) -> Self

Sets whether test parameters can be overridden via environment variables.

If set to true and special environment variables are present, Dicetest::run will parse their values and override the corresponding test parameters before running the test. This parameter is true by default.

pub fn run<T>(self, test: T)

where T: Fn(Fate<'_>) + UnwindSafe + RefUnwindSafe,

Runs the test with the given configuration and prints the result to stdout.

If special environment variables are present, this function will parse their values and override the corresponding test parameters before running the test. This can be disabled via Dicetest::env_enabled.

Panics

Panics if parsing a present environment variable has failed or the test has panicked during a test run.

Trait Implementations

impl Clone for Dicetest

fn clone(&self) -> Dicetest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Dicetest

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

Formats the value using the given formatter.