Repository files navigation

Arbitrary

The trait for generating structured data from arbitrary, unstructured input.

TheArbitrary crate lets you construct arbitrary instances of a type.

This crate is primarily intended to be combined with a fuzzer likelibFuzzerandcargo-fuzz orAFL, and to help you turn the raw,untyped byte buffers that they produce into well-typed, valid, structuredvalues. This allows you to combine structure-aware test case generation withcoverage-guided, mutation-based fuzzers.

Read the API documentation ondocs.rs!

Say you're writing a color conversion library, and you have anRgb struct torepresent RGB colors. You might want to implementArbitrary forRgb so thatyou could take arbitraryRgb instances in a test function that asserts someproperty (for example, asserting that RGB converted to HSL and converted back toRGB always ends up exactly where we started).

Automatically deriving theArbitrary trait is the recommended way to implementArbitrary for your types.

Automatically derivingArbitrary requires you to enable the"derive" cargofeature:

# Cargo.toml[dependencies]arbitrary = {version ="1",features = ["derive"] }

And then you can simply add#[derive(Arbitrary)] annotations to your types:

// rgb.rsuse arbitrary::Arbitrary;#[derive(Arbitrary)]pubstructRgb{pubr:u8,pubg:u8,pubb:u8,}

This can be particular handy if your structure uses a type that does not implementArbitrary or you want to have more customization for particular fields.

#[derive(Arbitrary)]pubstructRgba{// set `r` to Default::default()#[arbitrary(default)]pubr:u8,// set `g` to 255#[arbitrary(value =255)]pubg:u8,// Generate `b` with a custom function of type////    fn(&mut Unstructured) -> arbitrary::Result<T>//// where `T` is the field's type.#[arbitrary(with = arbitrary_b)]pubb:u8,// Generate `a` with a custom closure (shortcut to avoid a custom function)#[arbitrary(with = |u:&mutUnstructured| u.int_in_range(0..=64))]puba:u8,}fnarbitrary_b(u:&mutUnstructured) -> arbitrary::Result<u8>{    u.int_in_range(64..=128)}

Alternatively, you can write anArbitrary implementation by hand:

// rgb.rsuse arbitrary::{Arbitrary,Result,Unstructured};#[derive(Copy,Clone,Debug)]pubstructRgb{pubr:u8,pubg:u8,pubb:u8,}impl<'a>Arbitrary<'a>forRgb{fnarbitrary(u:&mutUnstructured<'a>) ->Result<Self>{let r = u8::arbitrary(u)?;let g = u8::arbitrary(u)?;let b = u8::arbitrary(u)?;Ok(Rgb{ r, g, b})}}

This crate is guaranteed to compile on stable Rust1.63.0 and up. It mightcompile with older versions but that may change in any new patch release.

We reserve the right to increment the MSRV on minor releases, however we willstrive to only do it deliberately and for good reasons.

Licensed under dual MIT or Apache-2.0 at your choice.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in this project by you, as defined in the Apache-2.0 license,shall be dual licensed as above, without any additional terms or conditions.