Crate hegel

Expand description

Hegel is a property-based testing library for Rust. Hegel is based on Hypothesis, using the Hegel protocol.

§Getting started

This guide walks you through the basics of installing Hegel and writing your first tests.

§Install Hegel

Add hegel-rust to your Cargo.toml as a dev dependency using cargo:

cargo add --dev hegeltest

§Write your first test

You’re now ready to write your first test. We’ll use Cargo as a test runner for the purposes of this guide. Create a new test in the project’s tests/ directory:

use hegel::TestCase;
use hegel::generators as gs;

#[hegel::test]
fn test_integer_self_equality(tc: TestCase) {
    let n = tc.draw(gs::integers::<i32>());
    assert_eq!(n, n); // integers should always be equal to themselves
}

Now run the test using cargo test --test <filename>. You should see that this test passes.

Let’s look at what’s happening in more detail. The #[hegel::test] attribute runs your test many times (100, by default). The test function (in this case test_integer_self_equality) takes a TestCase parameter, which provides a draw method for drawing different values. This test draws a random integer and checks that it should be equal to itself.

Next, try a test that fails:

#[hegel::test]
fn test_integers_always_below_50(tc: TestCase) {
    let n = tc.draw(gs::integers::<i32>());
    assert!(n < 50); // this will fail!
}

This test asserts that any integer is less than 50, which is obviously incorrect. Hegel will find a test case that makes this assertion fail, and then shrink it to find the smallest counterexample — in this case, n = 50.

To fix this test, you can constrain the integers you generate with the min_value and max_value functions:

#[hegel::test]
fn test_bounded_integers_always_below_50(tc: TestCase) {
    let n = tc.draw(gs::integers::<i32>()
        .min_value(0)
        .max_value(49));
    assert!(n < 50);
}

Run the test again. It should now pass.

§Use generators

Hegel provides a rich library of generators that you can use out of the box. There are primitive generators, such as integers, floats, and text, and combinators that allow you to make generators out of other generators, such as vecs and tuples.

For example, you can use vecs to generate a vector of integers:

use hegel::generators as gs;

#[hegel::test]
fn test_append_increases_length(tc: TestCase) {
    let mut vector = tc.draw(gs::vecs(gs::integers::<i32>()));
    let initial_length = vector.len();
    vector.push(tc.draw(gs::integers::<i32>()));
    assert!(vector.len() > initial_length);
}

This test checks that appending an element to a random vector of integers should always increase its length.

You can also define custom generators. For example, say you have a Person struct that we want to generate:

#[derive(Debug)]
struct Person {
    age: i32,
    name: String,
}

#[hegel::composite]
fn generate_person(tc: &TestCase) -> Person {
    let age = tc.draw(gs::integers::<i32>());
    let name = tc.draw(gs::text());
    Person { age, name }
}

Note that you can feed the results of a draw to subsequent calls. For example, say that you extend the Person struct to include a driving_license boolean field:

#[derive(Debug)]
struct Person {
    age: i32,
    name: String,
    driving_license: bool,
}

#[hegel::composite]
fn generate_person(tc: &TestCase) -> Person {
    let age = tc.draw(gs::integers::<i32>());
    let name = tc.draw(gs::text());
    let driving_license = if age >= 18 {
        tc.draw(gs::booleans())
    } else {
         false
    };
    Person { age, name, driving_license }
}

§Debug your failing test cases

Use the note method to attach debug information:

#[hegel::test]
fn test_with_notes(tc: TestCase) {
    let x = tc.draw(gs::integers::<i32>());
    let y = tc.draw(gs::integers::<i32>());
    tc.note(&format!("x + y = {}, y + x = {}", x + y, y + x));
    assert_eq!(x + y, y + x);
}

Notes only appear when Hegel replays the minimal failing example.

§Change the number of test cases

By default Hegel runs 100 test cases. To override this, pass the test_cases argument to the test attribute:

#[hegel::test(test_cases = 500)]
fn test_integers_many(tc: TestCase) {
    let n = tc.draw(gs::integers::<i32>());
    assert_eq!(n, n);
}

To override the number of test cases at runtime — for the whole suite, without editing source — set the HEGEL_TEST_CASES environment variable:

HEGEL_TEST_CASES=10000 cargo test

When set and non-empty, it takes precedence over any value configured in source, including explicit test_cases attributes.

To see what a test actually generates, record events with TestCase::event and TestCase::event_value and enable the end-of-run statistics report with the HEGEL_STATISTICS environment variable (or Settings::show_statistics):

HEGEL_STATISTICS=1 cargo test my_test -- --nocapture

§Threading

TestCase is Send but not Sync: you can clone it and move the clone to another thread to drive generation from there.

use hegel::TestCase;
use hegel::generators as gs;

#[hegel::test]
fn test_with_worker_thread(tc: TestCase) {
    let tc_worker = tc.clone();
    let handle = std::thread::spawn(move || {
        tc_worker.draw(gs::vecs(gs::integers::<i32>()).max_size(10))
    });
    let xs = handle.join().unwrap();
    let more: bool = tc.draw(gs::booleans());
    let _ = (xs, more);
}

Clones share the test case’s outcome — the whole family passes, fails, or is rejected as one test case — but each clone draws from its own independent, deterministic stream of choices, so several threads can generate concurrently without perturbing each other’s values and the same seed replays the same values on every stream.

In a failing example’s report, a clone’s drawn values appear together, at the point where the clone was created — not interleaved by wall-clock timing — so the report is deterministic no matter how the threads were scheduled.

Determinism extends only as far as your own code’s determinism: if your threads race on shared state, Hegel replays each stream faithfully but the test may still behave differently run to run — see TestCase’s documentation for the full contract and the patterns that are safe to rely on.

§Learning more

Browse the generators module for the full list of available generators.
See Settings for more configuration settings to customise how your test runs.

Re-exports§

pub use generators::Generator;
pub use generators::PrintableGenerator;
pub use pretty::Document;
pub use pretty::PrettyPrintable;
pub use pretty::PrettyPrinter;

Modules§

extras: Integrations with third-party libraries.
generators: Generators for producing test data.
pretty: Pretty-printing of generated values.
stateful: Stateful (model-based) testing support.

Macros§

compose: Create a generator from imperative code that draws from other generators.
derive_generator: Derive a generator for a struct defined in another crate.
one_of: Choose from any number of generators of the same type.
pretty_print_as_debug: Implement PrettyPrintable for one or more local Debug types by printing their {:?} representation through print_debug_repr, so derived-Debug output wraps like a native implementation.
tuples: Creates a tuple generator from 0–12 component generators.

Structs§

ExplicitTestCase: A test case with pre-defined values for explicit/example-based testing.
Settings: Configuration for a Hegel test run.
TestCase: A handle to the current test case.

Enums§

Backend: Selects the source of randomness the engine draws from.
HealthCheck: Health checks that can be suppressed during test execution.
Phase: Controls which phases of the test lifecycle are executed.
Verbosity: Controls how much output Hegel produces during test runs.

Attribute Macros§

composite: Define a composite generator from a function.
concurrent_state_machine: Derive a ConcurrentStateMachine implementation from an impl block, for concurrent stateful testing via stateful::run_concurrent.
explicit_test_case: Define an explicit test case to run before the property-based test.
main: Turn a function into a standalone Hegel binary entry point.
reproduce_failure: Replay a single failing example from a base64 failure blob.
standalone_function: Rewrite a function taking a TestCase plus additional arguments into one that takes just those arguments and internally runs Hegel.
state_machine: Derive a StateMachine implementation from an impl block.
test: The main entrypoint into Hegel.

Derive Macros§

DefaultGenerator: Derive a generator for a struct or enum.
PrettyPrintable: Derive PrettyPrintable for a struct or enum.

Crate hegel

Crate hegel Copy item path

§Getting started

§Install Hegel

§Write your first test

§Use generators

§Debug your failing test cases

§Change the number of test cases

§Threading

§Learning more

Re-exports§

Modules§

Macros§

Structs§

Enums§

Attribute Macros§

Derive Macros§

Crate hegel