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 (with optional derive macro for Arbitrary)
• 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 only outputs values for visible test case runs.

veprintln

eprintln wrapper that only outputs values for visible test case runs.

vprintln

println wrapper that only outputs values for visible test case runs.

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

checkstd

Check that property holds (does not panic).

fuzz_checkstd

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

fuzz_mutatestd

Mutate fuzzer input.

fuzz_mutate_crossoverstd

Cross-over two fuzzer inputs.

fuzz_write_seedstd

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

should_log

Determine whether debug output should be emitted for the current test-case run.

Derive Macros

Arbitraryderive

Derive chaos_theory::Arbitrary.