Struct TestCase 

pub struct TestCase { /* private fields */ }

A handle to the current test case.

This is passed to #[hegel::test] functions and provides methods for drawing values, making assumptions, and recording notes.

Example

use hegel::generators as gs;

#[hegel::test]
fn my_test(tc: hegel::TestCase) {
    let x: i32 = tc.draw(gs::integers());
    tc.assume(x > 0);
    tc.note(&format!("x = {}", x));
}

Threading

TestCase is Send but not Sync. To drive generation from another thread, clone the test case and move the clone. Clones share the same underlying backend connection — they are views onto one test case, not independent test cases.

use hegel::generators as gs;

#[hegel::test]
fn my_test(tc: hegel::TestCase) {
    let tc_worker = tc.clone();
    let handle = std::thread::spawn(move || {
        tc_worker.draw(gs::integers::<i32>())
    });
    let n = handle.join().unwrap();
    let _b: bool = tc.draw(gs::booleans());
    let _ = n;
}

What is guaranteed

Individual backend operations (a single generate, start_span, stop_span, or pool/collection call) are serialised by a shared mutex, so the bytes on the wire to the backend stay well-formed no matter how clones are used across threads.

This is enough for patterns where threads do not race on generation — for example:

• Spawn a worker, let it draw, join it, then continue on the main thread.
• Repeatedly spawn-and-join one worker at a time.
• Any pattern where exactly one thread is drawing at a time, with a happens-before relationship (join, channel receive, barrier) between each thread’s work.

What is not guaranteed

Concurrent generation will get progressively better over time, but right now should be considered a borderline-internal feature. If you do not know exactly what you’re doing it probably won’t work.

Two or more threads drawing concurrently from clones of the same TestCase is allowed by the type system but is not deterministic: the order in which draws interleave depends on thread scheduling, and the backend has no way to reproduce that order on replay. Composite draws are also not atomic with respect to other threads — another thread’s draws can land between this thread’s start_span and stop_span, corrupting the shrink-friendly span structure. In practice this means such tests may:

• Produce different values on successive runs of the same seed.
• Shrink poorly or not at all.
• Surface backend errors (e.g. StopTest) in one thread caused by another thread’s draws exhausting the budget.

Panics inside spawned threads

If a worker thread panics with an assumption failure or a backend StopTest, that panic stays inside the thread’s JoinHandle until the main thread joins it. The main thread is responsible for propagating (or suppressing) the panic — typically by calling handle.join().unwrap(), which resumes the panic on the main thread so Hegel’s runner can observe it.

Implementations

impl TestCase

pub fn draw<T: Debug>(&self, generator: impl Generator<T>) -> T

Draw a value from a generator.

Example

use hegel::generators as gs;

#[hegel::test]
fn my_test(tc: hegel::TestCase) {
    let x: i32 = tc.draw(gs::integers());
    let s: String = tc.draw(gs::text());
}

Note: when run inside a #[hegel::test], draw() will typically be rewritten to __draw_named() with an appropriate variable name in order to give better test output.

Examples found in repository

examples/min_stack.rs (line 72)

    fn push(&mut self, tc: TestCase) {
        let element = tc.draw(gs::integers::<i32>());
        self.stack.push(element);
    }

examples/stack.rs (line 15)

    fn push(&mut self, tc: TestCase) {
        let integers = gs::integers::<i32>;
        let element = tc.draw(integers());
        self.stack.push(element);
    }

    #[rule]
    fn pop(&mut self, _: TestCase) {
        self.stack.pop();
    }

    #[rule]
    fn pop_push(&mut self, tc: TestCase) {
        let integers = gs::integers::<i32>;
        let element = tc.draw(integers());
        let initial = self.stack.clone();
        self.stack.push(element);
        let popped = self.stack.pop().unwrap();
        assert_eq!(popped, element);
        assert_eq!(self.stack, initial);
    }

examples/ledger.rs (line 51)

    fn create_account(&mut self, tc: TestCase) {
        let account = tc.draw(gs::text().min_size(1));
        tc.note(&format!("create account '{}'", account.clone()));
        self.accounts.add(account);
    }

    #[rule]
    fn credit(&mut self, tc: TestCase) {
        let account = self.accounts.draw().clone();
        let amount = tc.draw(gs::integers::<i64>().min_value(0).max_value(LIMIT));
        tc.note(&format!("credit '{}' with {}", account.clone(), amount));
        self.ledger.credit(account, amount);
    }

    #[rule]
    fn transfer(&mut self, tc: TestCase) {
        let from = self.accounts.draw().clone();
        let to = self.accounts.draw().clone();
        let amount = tc.draw(gs::integers::<i64>().min_value(0).max_value(LIMIT));
        tc.note(&format!(
            "transfer '{}' from {} to {}",
            amount,
            from.clone(),
            to.clone()
        ));
        self.ledger.transfer(from, to, amount);
    }

pub fn __draw_named<T: Debug>( &self, generator: impl Generator<T>, name: &str, repeatable: bool, ) -> T

Draw a value from a generator with a specific name for output.

When repeatable is true, a counter suffix is appended (e.g. x_1, x_2). When repeatable is false, reusing the same name panics.

Using the same name with different values of repeatable is an error.

On the final replay of a failing test case, this prints:

• let name = value; (when not repeatable)
• let name_N = value; (when repeatable)

Not intended for direct use. This is the target that #[hegel::test] rewrites draw() calls to where appropriate.

pub fn draw_silent<T>(&self, generator: impl Generator<T>) -> T

Draw a value from a generator without recording it in the output.

Unlike draw, this does not require T: Debug and will not print the value in the failing-test summary.

pub fn assume(&self, condition: bool)

Assume a condition is true. If false, reject the current test input.

Example

use hegel::generators as gs;

#[hegel::test]
fn my_test(tc: hegel::TestCase) {
    let age: u32 = tc.draw(gs::integers());
    tc.assume(age >= 18);
}

Examples found in repository

examples/stack.rs (line 39)

    fn push_pop(&mut self, tc: TestCase) {
        let initial = self.stack.clone();
        let element = self.stack.pop();
        tc.assume(element.is_some());
        let element = element.unwrap();
        self.stack.push(element);
        assert_eq!(self.stack, initial);
    }

pub fn reject(&self) -> !

Reject the current test input unconditionally.

Equivalent to assume(false), but with a ! return type so that code following the call is statically known to be unreachable.

Example

use hegel::generators as gs;

#[hegel::test]
fn my_test(tc: hegel::TestCase) {
    let n: i32 = tc.draw(gs::integers());
    let positive: u32 = match u32::try_from(n) {
        Ok(v) => v,
        Err(_) => tc.reject(),
    };
    let _ = positive;
}

pub fn note(&self, message: &str)

Note a message which will be displayed with the reported failing test case.

Only prints during the final replay of a failing test case.

Example

use hegel::generators as gs;

#[hegel::test]
fn my_test(tc: hegel::TestCase) {
    let x: i32 = tc.draw(gs::integers());
    tc.note(&format!("Generated x = {}", x));
}

Examples found in repository

examples/die_hard.rs (line 55)

    fn die_hard_problem_not_solved(&mut self, tc: TestCase) {
        tc.note(&format!("small / big = {0} / {1}", self.small, self.big));
        assert!(self.big != 4);
    }

examples/ledger.rs (line 52)

    fn create_account(&mut self, tc: TestCase) {
        let account = tc.draw(gs::text().min_size(1));
        tc.note(&format!("create account '{}'", account.clone()));
        self.accounts.add(account);
    }

    #[rule]
    fn credit(&mut self, tc: TestCase) {
        let account = self.accounts.draw().clone();
        let amount = tc.draw(gs::integers::<i64>().min_value(0).max_value(LIMIT));
        tc.note(&format!("credit '{}' with {}", account.clone(), amount));
        self.ledger.credit(account, amount);
    }

    #[rule]
    fn transfer(&mut self, tc: TestCase) {
        let from = self.accounts.draw().clone();
        let to = self.accounts.draw().clone();
        let amount = tc.draw(gs::integers::<i64>().min_value(0).max_value(LIMIT));
        tc.note(&format!(
            "transfer '{}' from {} to {}",
            amount,
            from.clone(),
            to.clone()
        ));
        self.ledger.transfer(from, to, amount);
    }

examples/min_stack.rs (line 81)

    fn pop(&mut self, tc: TestCase) {
        let element = self.stack.pop();
        match element {
            Some(element) => {
                tc.note(&format!("pop {}", element));
            }
            _ => {
                tc.note("pop nothing");
            }
        }
    }

pub fn repeat<F: FnMut()>(&self, body: F) -> !

Run body in a loop that should runs “logically infinitely” or until error. Roughly equivalent to a loop but with better interaction with the test runner: This loop will never exit until the test case completes.

At the start of each iteration a // Loop iteration N note is emitted into the failing-test replay output.

Example

use hegel::generators as gs;

#[hegel::test]
fn my_test(tc: hegel::TestCase) {
    let mut total: i32 = 0;
    tc.repeat(|| {
        let n: i32 = tc.draw(gs::integers().min_value(0).max_value(10));
        total += n;
        assert!(total >= 0);
    });
}

Trait Implementations

impl Clone for TestCase

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TestCase

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

Formats the value using the given formatter.