tag | 075780bcb81a72d8aed1bc9dde5d830416cbc47d | |
---|---|---|
tagger | The Android Open Source Project <initial-contribution@android.com> | Tue May 07 10:56:59 2024 -0700 |
object | 5cb5fc0ba68178261dc6d0e1dff27b0f1aa79ae2 |
Android 14.0.0 release 35
commit | 5cb5fc0ba68178261dc6d0e1dff27b0f1aa79ae2 | [log] [tgz] |
---|---|---|
author | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | Sat Oct 21 03:13:35 2023 +0000 |
committer | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | Sat Oct 21 03:13:35 2023 +0000 |
tree | dd35a6941b4bffa33e7aa6a31c19f1fb2e0b8325 | |
parent | 7d450fbeb40c2ba682c98cf73bfe914334320feb [diff] | |
parent | 5232af0c9d748a8c8a910c37dbb68e4ab8d00842 [diff] |
Snap for 10985023 from 5232af0c9d748a8c8a910c37dbb68e4ab8d00842 to 24Q1-release Change-Id: Id168278469d7fc082581300aea1fa20b3bb612ac
The Arbitrary
crate lets you construct arbitrary instances of a type.
This crate is primarily intended to be combined with a fuzzer like libFuzzer and cargo-fuzz
or AFL, and to help you turn the raw, untyped byte buffers that they produce into well-typed, valid, structured values. This allows you to combine structure-aware test case generation with coverage-guided, mutation-based fuzzers.
Read the API documentation on docs.rs
!
Say you're writing a color conversion library, and you have an Rgb
struct to represent RGB colors. You might want to implement Arbitrary
for Rgb
so that you could take arbitrary Rgb
instances in a test function that asserts some property (for example, asserting that RGB converted to HSL and converted back to RGB always ends up exactly where we started).
Arbitrary
Automatically deriving the Arbitrary
trait is the recommended way to implement Arbitrary
for your types.
Automatically deriving Arbitrary
requires you to enable the "derive"
cargo feature:
# Cargo.toml [dependencies] arbitrary = { version = "1", features = ["derive"] }
And then you can simply add #[derive(Arbitrary)]
annotations to your types:
// rgb.rs use arbitrary::Arbitrary; #[derive(Arbitrary)] pub struct Rgb { pub r: u8, pub g: u8, pub b: u8, }
This can be particular handy if your structure uses a type that does not implement Arbitrary
or you want to have more customization for particular fields.
#[derive(Arbitrary)] pub struct Rgba { // set `r` to Default::default() #[arbitrary(default)] pub r: u8, // set `g` to 255 #[arbitrary(value = 255)] pub g: 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)] pub b: u8, // Generate `a` with a custom closure (shortuct to avoid a custom funciton) #[arbitrary(with = |u: &mut Unstructured| u.int_in_range(0..=64))] pub a: u8, } fn arbitrary_b(u: &mut Unstructured) -> arbitrary::Result<u8> { u.int_in_range(64..=128) }
Arbitrary
By HandAlternatively, you can write an Arbitrary
implementation by hand:
// rgb.rs use arbitrary::{Arbitrary, Result, Unstructured}; #[derive(Copy, Clone, Debug)] pub struct Rgb { pub r: u8, pub g: u8, pub b: u8, } impl<'a> Arbitrary<'a> for Rgb { fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> { let r = u8::arbitrary(u)?; let g = u8::arbitrary(u)?; let b = u8::arbitrary(u)?; Ok(Rgb { r, g, b }) } }
Licensed under dual MIT or Apache-2.0 at your choice.
Unless you explicitly state otherwise, any contribution intentionally submitted for 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.