foundry_evm_fuzz/
lib.rs

Help
1//! # foundry-evm-fuzz
2//!
3//! EVM fuzzing implementation using [`proptest`].
4
5#![cfg_attr(not(test), warn(unused_crate_dependencies))]
6#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
7
8#[macro_use]
9extern crate tracing;
10
11use alloy_dyn_abi::{DynSolValue, JsonAbiExt};
12use alloy_primitives::{
13    map::{AddressHashMap, HashMap},
14    Address, Bytes, Log,
15};
16use foundry_common::{calc, contracts::ContractsByAddress, evm::Breakpoints};
17use foundry_evm_coverage::HitMaps;
18use foundry_evm_traces::{CallTraceArena, SparsedTraceArena};
19use itertools::Itertools;
20use serde::{Deserialize, Serialize};
21use std::{fmt, sync::Arc};
22
23pub use proptest::test_runner::{Config as FuzzConfig, Reason};
24
25mod error;
26pub use error::FuzzError;
27
28pub mod invariant;
29pub mod strategies;
30
31mod inspector;
32pub use inspector::Fuzzer;
33
34#[derive(Clone, Debug, Serialize, Deserialize)]
35#[expect(clippy::large_enum_variant)]
36pub enum CounterExample {
37    /// Call used as a counter example for fuzz tests.
38    Single(BaseCounterExample),
39    /// Original sequence size and sequence of calls used as a counter example for invariant tests.
40    Sequence(usize, Vec<BaseCounterExample>),
41}
42
43#[derive(Clone, Debug, Serialize, Deserialize)]
44pub struct BaseCounterExample {
45    /// Address which makes the call.
46    pub sender: Option<Address>,
47    /// Address to which to call to.
48    pub addr: Option<Address>,
49    /// The data to provide.
50    pub calldata: Bytes,
51    /// Contract name if it exists.
52    pub contract_name: Option<String>,
53    /// Function name if it exists.
54    pub func_name: Option<String>,
55    /// Function signature if it exists.
56    pub signature: Option<String>,
57    /// Pretty formatted args used to call the function.
58    pub args: Option<String>,
59    /// Unformatted args used to call the function.
60    pub raw_args: Option<String>,
61    /// Counter example traces.
62    #[serde(skip)]
63    pub traces: Option<SparsedTraceArena>,
64    /// Whether to display sequence as solidity.
65    #[serde(skip)]
66    pub show_solidity: bool,
67}
68
69impl BaseCounterExample {
70    /// Creates counter example representing a step from invariant call sequence.
71    pub fn from_invariant_call(
72        sender: Address,
73        addr: Address,
74        bytes: &Bytes,
75        contracts: &ContractsByAddress,
76        traces: Option<SparsedTraceArena>,
77        show_solidity: bool,
78    ) -> Self {
79        if let Some((name, abi)) = &contracts.get(&addr) {
80            if let Some(func) = abi.functions().find(|f| f.selector() == bytes[..4]) {
81                // skip the function selector when decoding
82                if let Ok(args) = func.abi_decode_input(&bytes[4..], false) {
83                    return Self {
84                        sender: Some(sender),
85                        addr: Some(addr),
86                        calldata: bytes.clone(),
87                        contract_name: Some(name.clone()),
88                        func_name: Some(func.name.clone()),
89                        signature: Some(func.signature()),
90                        args: Some(
91                            foundry_common::fmt::format_tokens(&args).format(", ").to_string(),
92                        ),
93                        raw_args: Some(
94                            foundry_common::fmt::format_tokens_raw(&args).format(", ").to_string(),
95                        ),
96                        traces,
97                        show_solidity,
98                    };
99                }
100            }
101        }
102
103        Self {
104            sender: Some(sender),
105            addr: Some(addr),
106            calldata: bytes.clone(),
107            contract_name: None,
108            func_name: None,
109            signature: None,
110            args: None,
111            raw_args: None,
112            traces,
113            show_solidity: false,
114        }
115    }
116
117    /// Creates counter example for a fuzz test failure.
118    pub fn from_fuzz_call(
119        bytes: Bytes,
120        args: Vec<DynSolValue>,
121        traces: Option<SparsedTraceArena>,
122    ) -> Self {
123        Self {
124            sender: None,
125            addr: None,
126            calldata: bytes,
127            contract_name: None,
128            func_name: None,
129            signature: None,
130            args: Some(foundry_common::fmt::format_tokens(&args).format(", ").to_string()),
131            raw_args: Some(foundry_common::fmt::format_tokens_raw(&args).format(", ").to_string()),
132            traces,
133            show_solidity: false,
134        }
135    }
136}
137
138impl fmt::Display for BaseCounterExample {
139    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
140        // Display counterexample as solidity.
141        if self.show_solidity {
142            if let (Some(sender), Some(contract), Some(address), Some(func_name), Some(args)) =
143                (&self.sender, &self.contract_name, &self.addr, &self.func_name, &self.raw_args)
144            {
145                writeln!(f, "\t\tvm.prank({sender});")?;
146                write!(
147                    f,
148                    "\t\t{}({}).{}({});",
149                    contract.split_once(':').map_or(contract.as_str(), |(_, contract)| contract),
150                    address,
151                    func_name,
152                    args
153                )?;
154
155                return Ok(())
156            }
157        }
158
159        // Regular counterexample display.
160        if let Some(sender) = self.sender {
161            write!(f, "\t\tsender={sender} addr=")?
162        }
163
164        if let Some(name) = &self.contract_name {
165            write!(f, "[{name}]")?
166        }
167
168        if let Some(addr) = &self.addr {
169            write!(f, "{addr} ")?
170        }
171
172        if let Some(sig) = &self.signature {
173            write!(f, "calldata={sig}")?
174        } else {
175            write!(f, "calldata={}", &self.calldata)?
176        }
177
178        if let Some(args) = &self.args {
179            write!(f, " args=[{args}]")
180        } else {
181            write!(f, " args=[]")
182        }
183    }
184}
185
186/// The outcome of a fuzz test
187#[derive(Debug)]
188pub struct FuzzTestResult {
189    /// we keep this for the debugger
190    pub first_case: FuzzCase,
191    /// Gas usage (gas_used, call_stipend) per cases
192    pub gas_by_case: Vec<(u64, u64)>,
193    /// Whether the test case was successful. This means that the transaction executed
194    /// properly, or that there was a revert and that the test was expected to fail
195    /// (prefixed with `testFail`)
196    pub success: bool,
197    /// Whether the test case was skipped. `reason` will contain the skip reason, if any.
198    pub skipped: bool,
199
200    /// If there was a revert, this field will be populated. Note that the test can
201    /// still be successful (i.e self.success == true) when it's expected to fail.
202    pub reason: Option<String>,
203
204    /// Minimal reproduction test case for failing fuzz tests
205    pub counterexample: Option<CounterExample>,
206
207    /// Any captured & parsed as strings logs along the test's execution which should
208    /// be printed to the user.
209    pub logs: Vec<Log>,
210
211    /// Labeled addresses
212    pub labeled_addresses: AddressHashMap<String>,
213
214    /// Exemplary traces for a fuzz run of the test function
215    ///
216    /// **Note** We only store a single trace of a successful fuzz call, otherwise we would get
217    /// `num(fuzz_cases)` traces, one for each run, which is neither helpful nor performant.
218    pub traces: Option<SparsedTraceArena>,
219
220    /// Additional traces used for gas report construction.
221    /// Those traces should not be displayed.
222    pub gas_report_traces: Vec<CallTraceArena>,
223
224    /// Raw coverage info
225    pub coverage: Option<HitMaps>,
226
227    /// Breakpoints for debugger. Correspond to the same fuzz case as `traces`.
228    pub breakpoints: Option<Breakpoints>,
229
230    // Deprecated cheatcodes mapped to their replacements.
231    pub deprecated_cheatcodes: HashMap<&'static str, Option<&'static str>>,
232}
233
234impl FuzzTestResult {
235    /// Returns the median gas of all test cases
236    pub fn median_gas(&self, with_stipend: bool) -> u64 {
237        let mut values = self.gas_values(with_stipend);
238        values.sort_unstable();
239        calc::median_sorted(&values)
240    }
241
242    /// Returns the average gas use of all test cases
243    pub fn mean_gas(&self, with_stipend: bool) -> u64 {
244        let mut values = self.gas_values(with_stipend);
245        values.sort_unstable();
246        calc::mean(&values)
247    }
248
249    fn gas_values(&self, with_stipend: bool) -> Vec<u64> {
250        self.gas_by_case
251            .iter()
252            .map(|gas| if with_stipend { gas.0 } else { gas.0.saturating_sub(gas.1) })
253            .collect()
254    }
255}
256
257/// Data of a single fuzz test case
258#[derive(Clone, Debug, Default, Serialize, Deserialize)]
259pub struct FuzzCase {
260    /// The calldata used for this fuzz test
261    pub calldata: Bytes,
262    /// Consumed gas
263    pub gas: u64,
264    /// The initial gas stipend for the transaction
265    pub stipend: u64,
266}
267
268/// Container type for all successful test cases
269#[derive(Clone, Debug, Serialize, Deserialize)]
270#[serde(transparent)]
271pub struct FuzzedCases {
272    cases: Vec<FuzzCase>,
273}
274
275impl FuzzedCases {
276    #[inline]
277    pub fn new(mut cases: Vec<FuzzCase>) -> Self {
278        cases.sort_by_key(|c| c.gas);
279        Self { cases }
280    }
281
282    #[inline]
283    pub fn cases(&self) -> &[FuzzCase] {
284        &self.cases
285    }
286
287    #[inline]
288    pub fn into_cases(self) -> Vec<FuzzCase> {
289        self.cases
290    }
291
292    /// Get the last [FuzzCase]
293    #[inline]
294    pub fn last(&self) -> Option<&FuzzCase> {
295        self.cases.last()
296    }
297
298    /// Returns the median gas of all test cases
299    #[inline]
300    pub fn median_gas(&self, with_stipend: bool) -> u64 {
301        let mut values = self.gas_values(with_stipend);
302        values.sort_unstable();
303        calc::median_sorted(&values)
304    }
305
306    /// Returns the average gas use of all test cases
307    #[inline]
308    pub fn mean_gas(&self, with_stipend: bool) -> u64 {
309        let mut values = self.gas_values(with_stipend);
310        values.sort_unstable();
311        calc::mean(&values)
312    }
313
314    #[inline]
315    fn gas_values(&self, with_stipend: bool) -> Vec<u64> {
316        self.cases
317            .iter()
318            .map(|c| if with_stipend { c.gas } else { c.gas.saturating_sub(c.stipend) })
319            .collect()
320    }
321
322    /// Returns the case with the highest gas usage
323    #[inline]
324    pub fn highest(&self) -> Option<&FuzzCase> {
325        self.cases.last()
326    }
327
328    /// Returns the case with the lowest gas usage
329    #[inline]
330    pub fn lowest(&self) -> Option<&FuzzCase> {
331        self.cases.first()
332    }
333
334    /// Returns the highest amount of gas spent on a fuzz case
335    #[inline]
336    pub fn highest_gas(&self, with_stipend: bool) -> u64 {
337        self.highest()
338            .map(|c| if with_stipend { c.gas } else { c.gas - c.stipend })
339            .unwrap_or_default()
340    }
341
342    /// Returns the lowest amount of gas spent on a fuzz case
343    #[inline]
344    pub fn lowest_gas(&self) -> u64 {
345        self.lowest().map(|c| c.gas).unwrap_or_default()
346    }
347}
348
349/// Fixtures to be used for fuzz tests.
350///
351/// The key represents name of the fuzzed parameter, value holds possible fuzzed values.
352/// For example, for a fixture function declared as
353/// `function fixture_sender() external returns (address[] memory senders)`
354/// the fuzz fixtures will contain `sender` key with `senders` array as value
355#[derive(Clone, Default, Debug)]
356pub struct FuzzFixtures {
357    inner: Arc<HashMap<String, DynSolValue>>,
358}
359
360impl FuzzFixtures {
361    pub fn new(fixtures: HashMap<String, DynSolValue>) -> Self {
362        Self { inner: Arc::new(fixtures) }
363    }
364
365    /// Returns configured fixtures for `param_name` fuzzed parameter.
366    pub fn param_fixtures(&self, param_name: &str) -> Option<&[DynSolValue]> {
367        if let Some(param_fixtures) = self.inner.get(&normalize_fixture(param_name)) {
368            param_fixtures.as_fixed_array().or_else(|| param_fixtures.as_array())
369        } else {
370            None
371        }
372    }
373}
374
375/// Extracts fixture name from a function name.
376/// For example: fixtures defined in `fixture_Owner` function will be applied for `owner` parameter.
377pub fn fixture_name(function_name: String) -> String {
378    normalize_fixture(function_name.strip_prefix("fixture").unwrap())
379}
380
381/// Normalize fixture parameter name, for example `_Owner` to `owner`.
382fn normalize_fixture(param_name: &str) -> String {
383    param_name.trim_matches('_').to_ascii_lowercase()
384}
foundry_evm_fuzz/lib.rs

foundry_evm_fuzz/
lib.rs
