Crate chaos_theory 

chaos_theory is a modern property-based testing and structure-aware fuzzing library.

You drive tests using Source to get structured pseudo-random values and control flow, chaos_theory ensures that this exploration is efficient and any failures found are automatically minimized.

Quickstart

use chaos_theory::{check, make::string_matching};

#[test]
fn slug_and_id_roundtrip() {
    check(|src| {
        let slug = src.any_of("slug", string_matching("[a-z0-9]+(-[a-z0-9]+)*", true));
        let id: u32 = src.any("id");

        let s = format!("{slug}-{id}");
        let (slug_parsed, id_parsed) = s
            .rsplit_once('-')
            .map(|(s, i)| (s, i.parse::<u32>().unwrap()))
            .unwrap();

        assert_eq!(slug_parsed, slug);
        assert_eq!(id_parsed, id);
    });
}

When a failure happens, chaos_theory prints a CHAOS_THEORY_REPLAY=... string you can use to reproduce the case.

Highlights

• Property testing and structure-aware fuzzing in one library
• Efficient state space exploration:
  • bias towards small values and edge cases
  • structural mutations and crossover
  • example-guided generation
  • built-in swarm testing
• Macro-free, imperative API
• Zero unsafe code and zero required dependencies

Documentation

• FAQ
• Guide
• Changelog

Modules

_docs

Additional documentation.

make

Collection of built-in generator implementations.

Macros

assume

Mark the current test case as invalid if the expression is false.

fuzz_target_libfuzzer_sys

Define a libfuzzer_sys fuzz target.

vdbg

dbg wrapper that checks Source::should_log.

veprintln

eprintln wrapper that checks Source::should_log.

vprintln

println wrapper that checks Source::should_log.

Structs

Config

Custom configuration for Env.

Env

Environment and settings for chaos_theory magic.

Gen

Type-erased generator of T, implemented as a boxed trait object.

GenShared

Thread-safe type-erased generator of T, implemented as a boxed trait object.

Source

Primary interface for working with pseudo-random data and control flow.

SourceRaw

Lower-level variant of Source, primarily for use in Generator implementations.

Enums

Effect

Result of the Source::repeat or SourceRaw::repeat step.

MaybeOwned

Type that represents either owned or borrowed values.

Traits

Arbitrary

A trait for types that have a default Generator implementation.

Generator

A trait for types that describe composable generation of values.

OptionExt

Utility trait to give Option an OptionExt::assume_some helper.

Functions

check

Check that property holds (does not panic).

fuzz_check

Check that property holds (does not panic) on fuzzer-provided input.

fuzz_mutate

Mutate fuzzer input.

fuzz_mutate_crossover

Cross-over two fuzzer inputs.

fuzz_write_seed

Write seed input for the fuzzer. This can conveniently be done from an ignored test.