arbitrary

arbitrary is a Rust library providing the Arbitrary trait, which constructs well-typed, structured values from the raw, untyped byte buffers produced by fuzzers. It bridges coverage-guided, mutation-based fuzzers such as libFuzzer, cargo-fuzz, and AFL with structure-aware test-case generation, so your fuzz targets receive valid instances of your own types instead of shapeless bytes.

The crate ships a derive macro that generates Arbitrary implementations automatically for structs and enums, along with an Unstructured input reader that gives fine-grained control over how bytes are consumed. It is a foundational dependency across the Rust fuzzing and property-testing ecosystem.

What You Get

• The Arbitrary trait with implementations for standard library types
• A derive macro to auto-generate Arbitrary for your own structs and enums
• An Unstructured reader for precise, low-level control over byte consumption
• Size-hint machinery so fuzzers can budget input efficiently
• Seamless integration with cargo-fuzz, libFuzzer, and AFL

Common Use Cases

• Turning fuzzer byte buffers into typed inputs for structure-aware fuzzing
• Generating random valid instances of custom types in property-based tests
• Fuzzing parsers, codecs, and state machines with well-formed structured data
• Deriving Arbitrary automatically across large domains of application types

Under The Hood

Architecture - The core is the Arbitrary trait in src/lib.rs, whose arbitrary method reads bytes from an Unstructured cursor (src/unstructured.rs) to build a value. size_hint.rs lets implementations report how many bytes they need so fuzzers can plan input, and foreign/ supplies implementations for standard and third-party types. A companion proc-macro crate under derive/ generates trait impls for user types.

Tech Stack - Pure Rust with no required runtime dependencies; the optional derive feature pulls in the arbitrary-derive proc-macro crate built on syn/quote. Managed with Cargo, with fuzz targets under fuzz/ and runnable examples under examples/.

Code Quality - The crate is mature and heavily depended upon (over 130M downloads), with an integration test suite in tests/, inline unit tests, a maintained CHANGELOG, and its own fuzz targets exercising the generation logic.

API Design - Deriving #[derive(Arbitrary)] makes adoption nearly zero-boilerplate, while the Unstructured API remains available for authors who need manual control. Method naming and the trait contract are consistent and well documented on docs.rs.