forge/

runner.rs

//! The Forge test runner.

use crate::{
    MultiContractRunner, TestFilter,
    coverage::HitMaps,
    fuzz::{BaseCounterExample, FuzzTestResult},
    multi_runner::{TestContract, TestRunnerConfig},
    progress::{TestsProgress, start_fuzz_progress},
    result::{InvariantFailure, SuiteResult, TestResult, TestSetup},
};
use alloy_dyn_abi::{DynSolValue, JsonAbiExt};
use alloy_json_abi::Function;
use alloy_primitives::{Address, Bytes, Selector, U256, address, map::HashMap};
use eyre::Result;
use foundry_common::{TestFunctionExt, TestFunctionKind, contracts::ContractsByAddress};
use foundry_compilers::utils::canonicalized;
use foundry_config::{Config, FuzzCorpusConfig, InvariantConfig};
use foundry_evm::{
    constants::CALLER,
    core::evm::FoundryEvmNetwork,
    decode::RevertDecoder,
    executors::{
        CallResult, EvmError, Executor, ITest, RawCallResult,
        fuzz::FuzzedExecutor,
        invariant::{
            CheckSequenceOptions, HandlerAssertionFailure, InvariantExecutor, InvariantFuzzError,
            check_sequence, replay_error, replay_handler_failure_sequence, replay_run,
        },
    },
    fuzz::{
        BasicTxDetails, CallDetails, CounterExample, FuzzFixtures, fixture_name,
        invariant::{InvariantContract, InvariantSettings, is_optimization_invariant},
        strategies::EvmFuzzState,
    },
    revm::primitives::hardfork::SpecId,
    traces::{TraceKind, TraceMode, load_contracts},
};
use itertools::Itertools;
use proptest::test_runner::{RngAlgorithm, TestError, TestRng, TestRunner};
use rayon::prelude::*;
use serde::{Deserialize, Serialize};
use std::{
    borrow::Cow,
    cmp::min,
    collections::BTreeMap,
    ops::Deref,
    path::{Path, PathBuf},
    sync::Arc,
    time::Instant,
};
use tokio::signal;
use tracing::Span;

/// When running tests, we deploy all external libraries present in the project. To avoid additional
/// libraries affecting nonces of senders used in tests, we are using separate address to
/// predeploy libraries.
///
/// `address(uint160(uint256(keccak256("foundry library deployer"))))`
pub const LIBRARY_DEPLOYER: Address = address!("0x1F95D37F27EA0dEA9C252FC09D5A6eaA97647353");

/// A type that executes all tests of a contract
pub struct ContractRunner<'a, FEN: FoundryEvmNetwork> {
    /// The name of the contract.
    name: &'a str,
    /// The data of the contract.
    contract: &'a TestContract,
    /// The EVM executor.
    executor: Executor<FEN>,
    /// Overall test run progress.
    progress: Option<&'a TestsProgress>,
    /// The handle to the tokio runtime.
    tokio_handle: &'a tokio::runtime::Handle,
    /// The span of the contract.
    span: tracing::Span,
    /// The contract-level configuration.
    tcfg: Cow<'a, TestRunnerConfig<FEN>>,
    /// The parent runner.
    mcr: &'a MultiContractRunner<FEN>,
}

impl<'a, FEN: FoundryEvmNetwork> Deref for ContractRunner<'a, FEN> {
    type Target = Cow<'a, TestRunnerConfig<FEN>>;

    #[inline(always)]
    fn deref(&self) -> &Self::Target {
        &self.tcfg
    }
}

impl<'a, FEN: FoundryEvmNetwork> ContractRunner<'a, FEN> {
    pub const fn new(
        name: &'a str,
        contract: &'a TestContract,
        executor: Executor<FEN>,
        progress: Option<&'a TestsProgress>,
        tokio_handle: &'a tokio::runtime::Handle,
        span: Span,
        mcr: &'a MultiContractRunner<FEN>,
    ) -> Self {
        Self {
            name,
            contract,
            executor,
            progress,
            tokio_handle,
            span,
            tcfg: Cow::Borrowed(&mcr.tcfg),
            mcr,
        }
    }

    /// Returns `true` if `func` should run in the current multi-network pass.
    ///
    /// In single-pass mode (no inline network overrides) every function passes.
    /// In multi-pass mode:
    /// - Default pass (`pass_network = None`): includes functions *without* an override annotation.
    /// - Override pass (`pass_network = Some(v)`): includes only functions annotated with `v`.
    fn function_matches_network_pass(&self, func: &Function) -> bool {
        let multi = &self.mcr.tcfg.multi_network;
        if multi.all_override_networks.is_empty() {
            return true;
        }
        let profile = &self.tcfg.config.profile;
        let func_network = self.mcr.inline_config.network_for(profile, self.name, &func.name);
        match &multi.pass_network {
            None => func_network.is_none_or(|n| !multi.all_override_networks.contains(&n)),
            Some(target) => func_network.as_ref() == Some(target),
        }
    }

    /// Deploys the test contract inside the runner from the sending account, and optionally runs
    /// the `setUp` function on the test contract.
    pub fn setup(&mut self, call_setup: bool) -> TestSetup {
        self._setup(call_setup).unwrap_or_else(|err| {
            if err.to_string().contains("skipped") {
                TestSetup::skipped(err.to_string())
            } else {
                TestSetup::failed(err.to_string())
            }
        })
    }

    fn _setup(&mut self, call_setup: bool) -> Result<TestSetup> {
        trace!(call_setup, "setting up");

        self.apply_contract_inline_config()?;

        // We max out their balance so that they can deploy and make calls.
        self.executor.set_balance(self.sender, U256::MAX)?;
        self.executor.set_balance(CALLER, U256::MAX)?;

        // We set the nonce of the deployer accounts to 1 to get the same addresses as DappTools.
        self.executor.set_nonce(self.sender, 1)?;

        // Deploy libraries.
        self.executor.set_balance(LIBRARY_DEPLOYER, U256::MAX)?;

        let mut result = TestSetup::default();
        for code in &self.mcr.libs_to_deploy {
            let deploy_result = self.executor.deploy(
                LIBRARY_DEPLOYER,
                code.clone(),
                U256::ZERO,
                Some(&self.mcr.revert_decoder),
            );

            // Record deployed library address.
            if let Ok(deployed) = &deploy_result {
                result.deployed_libs.push(deployed.address);
            }

            let (raw, reason) = RawCallResult::from_evm_result(deploy_result.map(Into::into))?;
            result.extend(raw, TraceKind::Deployment);
            if reason.is_some() {
                debug!(?reason, "deployment of library failed");
                result.reason = reason;
                return Ok(result);
            }
        }

        let address = self.sender.create(self.executor.get_nonce(self.sender)?);
        result.address = address;

        // Set the contracts initial balance before deployment, so it is available during
        // construction
        self.executor.set_balance(address, self.initial_balance())?;

        // Deploy the test contract
        let deploy_result = self.executor.deploy(
            self.sender,
            self.contract.bytecode.clone(),
            U256::ZERO,
            Some(&self.mcr.revert_decoder),
        );

        result.deployment_failure = deploy_result.is_err();

        if let Ok(dr) = &deploy_result {
            debug_assert_eq!(dr.address, address);
        }
        let (raw, reason) = RawCallResult::from_evm_result(deploy_result.map(Into::into))?;
        result.extend(raw, TraceKind::Deployment);
        if reason.is_some() {
            debug!(?reason, "deployment of test contract failed");
            result.reason = reason;
            return Ok(result);
        }

        // Reset `self.sender`s, `CALLER`s and `LIBRARY_DEPLOYER`'s balance to the initial balance.
        self.executor.set_balance(self.sender, self.initial_balance())?;
        self.executor.set_balance(CALLER, self.initial_balance())?;
        self.executor.set_balance(LIBRARY_DEPLOYER, self.initial_balance())?;

        self.executor.deploy_create2_deployer()?;

        // Optionally call the `setUp` function
        if call_setup {
            trace!("calling setUp");
            let res = self.executor.setup(None, address, Some(&self.mcr.revert_decoder));
            let (raw, reason) = RawCallResult::from_evm_result(res)?;
            result.extend(raw, TraceKind::Setup);
            result.reason = reason;
        }

        result.fuzz_fixtures = self.fuzz_fixtures(address);

        Ok(result)
    }

    fn initial_balance(&self) -> U256 {
        self.evm_opts.initial_balance
    }

    /// Configures this runner with the inline configuration for the contract.
    fn apply_contract_inline_config(&mut self) -> Result<()> {
        if self.inline_config.contains_contract(self.name) {
            let new_config = Arc::new(self.inline_config(None)?);
            self.tcfg.to_mut().reconfigure_with(new_config);
            let prev_tracer = self.executor.inspector_mut().tracer.take();
            self.tcfg.configure_executor(&mut self.executor);
            // Don't set tracer here.
            self.executor.inspector_mut().tracer = prev_tracer;
        }
        Ok(())
    }

    /// Returns the configuration for a contract or function.
    fn inline_config(&self, func: Option<&Function>) -> Result<Config> {
        let function = func.map(|f| f.name.as_str()).unwrap_or("");
        let config = self
            .config
            .merge_inline_provider(self.mcr.inline_config.provide(self.name, function))?;
        Ok(config)
    }

    /// Collect fixtures from test contract.
    ///
    /// Fixtures can be defined:
    /// - as storage arrays in test contract, prefixed with `fixture`
    /// - as functions prefixed with `fixture` and followed by parameter name to be fuzzed
    ///
    /// Storage array fixtures:
    /// `uint256[] public fixture_amount = [1, 2, 3];`
    /// define an array of uint256 values to be used for fuzzing `amount` named parameter in scope
    /// of the current test.
    ///
    /// Function fixtures:
    /// `function fixture_owner() public returns (address[] memory){}`
    /// returns an array of addresses to be used for fuzzing `owner` named parameter in scope of the
    /// current test.
    fn fuzz_fixtures(&mut self, address: Address) -> FuzzFixtures {
        let mut fixtures = HashMap::default();
        let fixture_functions = self.contract.abi.functions().filter(|func| func.is_fixture());
        for func in fixture_functions {
            if func.inputs.is_empty() {
                // Read fixtures declared as functions.
                if let Ok(CallResult { raw: _, decoded_result }) =
                    self.executor.call(CALLER, address, func, &[], U256::ZERO, None)
                {
                    fixtures.insert(fixture_name(func.name.clone()), decoded_result);
                }
            } else {
                // For reading fixtures from storage arrays we collect values by calling the
                // function with incremented indexes until there's an error.
                let mut vals = Vec::new();
                let mut index = 0;
                loop {
                    if let Ok(CallResult { raw: _, decoded_result }) = self.executor.call(
                        CALLER,
                        address,
                        func,
                        &[DynSolValue::Uint(U256::from(index), 256)],
                        U256::ZERO,
                        None,
                    ) {
                        vals.push(decoded_result);
                    } else {
                        // No result returned for this index, we reached the end of storage
                        // array or the function is not a valid fixture.
                        break;
                    }
                    index += 1;
                }
                fixtures.insert(fixture_name(func.name.clone()), DynSolValue::Array(vals));
            };
        }
        FuzzFixtures::new(fixtures)
    }

    /// Runs all tests for a contract whose names match the provided regular expression
    pub fn run_tests(mut self, filter: &dyn TestFilter) -> SuiteResult {
        let start = Instant::now();
        let mut warnings = Vec::new();

        // Check if `setUp` function with valid signature declared.
        let setup_fns: Vec<_> =
            self.contract.abi.functions().filter(|func| func.name.is_setup()).collect();
        let call_setup = setup_fns.len() == 1 && setup_fns[0].name == "setUp";
        // There is a single miss-cased `setUp` function, so we add a warning
        for &setup_fn in &setup_fns {
            if setup_fn.name != "setUp" {
                warnings.push(format!(
                    "Found invalid setup function \"{}\" did you mean \"setUp()\"?",
                    setup_fn.signature()
                ));
            }
        }

        // There are multiple setUp function, so we return a single test result for `setUp`
        if setup_fns.len() > 1 {
            return SuiteResult::new(
                start.elapsed(),
                [("setUp()".to_string(), TestResult::fail("multiple setUp functions".to_string()))]
                    .into(),
                warnings,
            );
        }

        // Check if `afterInvariant` function with valid signature declared.
        let after_invariant_fns: Vec<_> =
            self.contract.abi.functions().filter(|func| func.name.is_after_invariant()).collect();
        if after_invariant_fns.len() > 1 {
            // Return a single test result failure if multiple functions declared.
            return SuiteResult::new(
                start.elapsed(),
                [(
                    "afterInvariant()".to_string(),
                    TestResult::fail("multiple afterInvariant functions".to_string()),
                )]
                .into(),
                warnings,
            );
        }
        let call_after_invariant = after_invariant_fns.first().is_some_and(|after_invariant_fn| {
            let match_sig = after_invariant_fn.name == "afterInvariant";
            if !match_sig {
                warnings.push(format!(
                    "Found invalid afterInvariant function \"{}\" did you mean \"afterInvariant()\"?",
                    after_invariant_fn.signature()
                ));
            }
            match_sig
        });

        // Invariant testing requires tracing to figure out what contracts were created.
        // We also want to disable `debug` for setup since we won't be using those traces.
        let invariant_fns: Vec<_> =
            self.contract.abi.functions().filter(|func| func.is_invariant_test()).collect();

        // Validate signatures up front: invariant functions must take no parameters. Without
        // this, parameterized `invariant_*` functions would slip into `assert_all` secondaries
        // and fail with a confusing "selector not found" / decode error mid-campaign. Reject
        // here with a per-function result so the failure is obvious to the user.
        let invalid_invariants: Vec<_> = invariant_fns
            .iter()
            .filter(|f| !f.inputs.is_empty())
            .map(|f| {
                (
                    f.signature(),
                    TestResult::fail(format!(
                        "invariant `{}` must take no parameters",
                        f.signature()
                    )),
                )
            })
            .collect();
        if !invalid_invariants.is_empty() {
            return SuiteResult::new(
                start.elapsed(),
                invalid_invariants.into_iter().collect(),
                warnings,
            );
        }

        let has_invariants = !invariant_fns.is_empty();

        let prev_tracer = self.executor.inspector_mut().tracer.take();
        if prev_tracer.is_some() || has_invariants {
            self.executor.set_tracing(TraceMode::Call);
        }

        let setup_time = Instant::now();
        let setup = self.setup(call_setup);
        debug!("finished setting up in {:?}", setup_time.elapsed());

        self.executor.inspector_mut().tracer = prev_tracer;

        if setup.reason.is_some() {
            // The setup failed, so we return a single test result for `setUp`
            let fail_msg = if setup.deployment_failure {
                "constructor()".to_string()
            } else {
                "setUp()".to_string()
            };
            return SuiteResult::new(
                start.elapsed(),
                [(fail_msg, TestResult::setup_result(setup))].into(),
                warnings,
            );
        }

        // Filter out functions sequentially since it's very fast and there is no need to do it
        // in parallel.
        let find_timer = Instant::now();
        let functions = self
            .contract
            .abi
            .functions()
            .filter(|func| filter.matches_test_function(func))
            .filter(|func| self.function_matches_network_pass(func))
            .collect::<Vec<_>>();
        debug!(
            "Found {} test functions out of {} in {:?}",
            functions.len(),
            self.contract.abi.functions().count(),
            find_timer.elapsed(),
        );

        let identified_contracts = has_invariants.then(|| {
            load_contracts(setup.traces.iter().map(|(_, t)| &t.arena), &self.mcr.known_contracts)
        });

        let test_fail_functions =
            functions.iter().filter(|func| func.test_function_kind().is_any_test_fail());
        if test_fail_functions.clone().next().is_some() {
            let fail = || {
                TestResult::fail("`testFail*` has been removed. Consider changing to test_Revert[If|When]_Condition and expecting a revert".to_string())
            };
            let test_results = test_fail_functions.map(|func| (func.signature(), fail())).collect();
            return SuiteResult::new(start.elapsed(), test_results, warnings);
        }

        let early_exit = &self.tcfg.early_exit;

        if self.progress.is_some() {
            let interrupt = early_exit.clone();
            self.tokio_handle.spawn(async move {
                signal::ctrl_c().await.expect("Failed to listen for Ctrl+C");
                interrupt.record_ctrl_c();
            });
        }

        let test_results = functions
            .par_iter()
            .filter_map(|&func| {
                // Early exit if we're running with fail-fast and a test already failed.
                if early_exit.should_stop() {
                    return None;
                }

                let start = Instant::now();

                let _guard = self.tokio_handle.enter();

                let _guard;
                let current_span = tracing::Span::current();
                if current_span.is_none() || current_span.id() != self.span.id() {
                    _guard = self.span.enter();
                }

                let sig = func.signature();
                let kind = func.test_function_kind();

                let _guard = debug_span!(
                    "test",
                    %kind,
                    name = %if enabled!(tracing::Level::TRACE) { &sig } else { &func.name },
                )
                .entered();

                let mut res = FunctionRunner::new(&self, &setup).run(
                    func,
                    invariant_fns.clone(),
                    kind,
                    call_after_invariant,
                    identified_contracts.as_ref(),
                );
                res.duration = start.elapsed();

                // Record test failure for early exit (only triggers if fail-fast is enabled).
                if res.status.is_failure() {
                    early_exit.record_failure();
                }

                Some((sig, res))
            })
            .collect::<BTreeMap<_, _>>();

        let duration = start.elapsed();
        SuiteResult::new(duration, test_results, warnings)
    }
}

/// Executes a single test function, returning a [`TestResult`].
struct FunctionRunner<'a, FEN: FoundryEvmNetwork> {
    /// The function-level configuration.
    tcfg: Cow<'a, TestRunnerConfig<FEN>>,
    /// The EVM executor.
    executor: Cow<'a, Executor<FEN>>,
    /// The parent runner.
    cr: &'a ContractRunner<'a, FEN>,
    /// The address of the test contract.
    address: Address,
    /// The test setup result.
    setup: &'a TestSetup,
    /// The test result. Returned after running the test.
    result: TestResult,
}

impl<'a, FEN: FoundryEvmNetwork> Deref for FunctionRunner<'a, FEN> {
    type Target = Cow<'a, TestRunnerConfig<FEN>>;

    #[inline(always)]
    fn deref(&self) -> &Self::Target {
        &self.tcfg
    }
}

impl<'a, FEN: FoundryEvmNetwork> FunctionRunner<'a, FEN> {
    fn new(cr: &'a ContractRunner<'a, FEN>, setup: &'a TestSetup) -> Self {
        Self {
            tcfg: match &cr.tcfg {
                Cow::Borrowed(tcfg) => Cow::Borrowed(tcfg),
                Cow::Owned(tcfg) => Cow::Owned(tcfg.clone()),
            },
            executor: Cow::Borrowed(&cr.executor),
            cr,
            address: setup.address,
            setup,
            result: TestResult::new(setup),
        }
    }

    const fn revert_decoder(&self) -> &'a RevertDecoder {
        &self.cr.mcr.revert_decoder
    }

    /// Configures this runner with the inline configuration for the contract.
    fn apply_function_inline_config(&mut self, func: &Function) -> Result<()> {
        if self.inline_config.contains_function(self.cr.name, &func.name) {
            let new_config = Arc::new(self.cr.inline_config(Some(func))?);
            self.tcfg.to_mut().reconfigure_with(new_config);
            self.tcfg.configure_executor(self.executor.to_mut());
        }
        Ok(())
    }

    fn run(
        mut self,
        func: &Function,
        invariants: Vec<&Function>,
        kind: TestFunctionKind,
        call_after_invariant: bool,
        identified_contracts: Option<&ContractsByAddress>,
    ) -> TestResult {
        let fail_on_revert_for = |f: &Function| {
            if self.inline_config.contains_function(self.cr.name, &f.name)
                && let Ok(config) = self.cr.inline_config(Some(f))
            {
                return config.invariant.fail_on_revert;
            }
            self.config.invariant.fail_on_revert
        };
        let invariant_fns: Vec<_> =
            invariants.into_iter().map(|f| (f, fail_on_revert_for(f))).collect();

        if let Err(e) = self.apply_function_inline_config(func) {
            self.result.single_fail(Some(e.to_string()));
            return self.result;
        }

        match kind {
            TestFunctionKind::UnitTest { .. } => self.run_unit_test(func),
            TestFunctionKind::FuzzTest { .. } => self.run_fuzz_test(func),
            TestFunctionKind::TableTest => self.run_table_test(func),
            TestFunctionKind::InvariantTest => self.run_invariant_test(
                func,
                invariant_fns,
                call_after_invariant,
                identified_contracts.unwrap(),
            ),
            _ => unreachable!(),
        }
    }

    /// Runs a single unit test.
    ///
    /// Applies before test txes (if any), runs current test and returns the `TestResult`.
    ///
    /// Before test txes are applied in order and state modifications committed to the EVM database
    /// (therefore the unit test call will be made on modified state).
    /// State modifications of before test txes and unit test function call are discarded after
    /// test ends, similar to `eth_call`.
    fn run_unit_test(mut self, func: &Function) -> TestResult {
        // Prepare unit test execution.
        if self.prepare_test(func).is_err() {
            return self.result;
        }

        // Run current unit test.
        let (mut raw_call_result, reason) = match self.executor.call(
            self.sender,
            self.address,
            func,
            &[],
            U256::ZERO,
            Some(self.revert_decoder()),
        ) {
            Ok(res) => (res.raw, None),
            Err(EvmError::Execution(err)) => (err.raw, Some(err.reason)),
            Err(EvmError::Skip(reason)) => {
                self.result.single_skip(reason);
                return self.result;
            }
            Err(err) => {
                self.result.single_fail(Some(err.to_string()));
                return self.result;
            }
        };

        let success =
            self.executor.is_raw_call_mut_success(self.address, &mut raw_call_result, false);
        self.result.single_result(success, reason, raw_call_result);
        self.result
    }

    /// Runs a table test.
    /// The parameters dataset (table) is created from defined parameter fixtures, therefore each
    /// test table parameter should have the same number of fixtures defined.
    /// E.g. for table test
    /// - `table_test(uint256 amount, bool swap)` fixtures are defined as
    /// - `uint256[] public fixtureAmount = [2, 5]`
    /// - `bool[] public fixtureSwap = [true, false]` The `table_test` is then called with the pair
    ///   of args `(2, true)` and `(5, false)`.
    fn run_table_test(mut self, func: &Function) -> TestResult {
        // Prepare unit test execution.
        if self.prepare_test(func).is_err() {
            return self.result;
        }

        // Extract and validate fixtures for the first table test parameter.
        let Some(first_param) = func.inputs.first() else {
            self.result.single_fail(Some("Table test should have at least one parameter".into()));
            return self.result;
        };

        let Some(first_param_fixtures) =
            &self.setup.fuzz_fixtures.param_fixtures(first_param.name())
        else {
            self.result.single_fail(Some("Table test should have fixtures defined".into()));
            return self.result;
        };

        if first_param_fixtures.is_empty() {
            self.result.single_fail(Some("Table test should have at least one fixture".into()));
            return self.result;
        }

        let fixtures_len = first_param_fixtures.len();
        let mut table_fixtures = vec![&first_param_fixtures[..]];

        // Collect fixtures for remaining parameters.
        for param in &func.inputs[1..] {
            let param_name = param.name();
            let Some(fixtures) = &self.setup.fuzz_fixtures.param_fixtures(param.name()) else {
                self.result.single_fail(Some(format!("No fixture defined for param {param_name}")));
                return self.result;
            };

            if fixtures.len() != fixtures_len {
                self.result.single_fail(Some(format!(
                    "{} fixtures defined for {param_name} (expected {})",
                    fixtures.len(),
                    fixtures_len
                )));
                return self.result;
            }

            table_fixtures.push(&fixtures[..]);
        }

        let progress = start_fuzz_progress(
            self.cr.progress,
            self.cr.name,
            &func.name,
            None,
            fixtures_len as u32,
        );

        let mut result = FuzzTestResult::default();

        for i in 0..fixtures_len {
            if self.tcfg.early_exit.should_stop() {
                return self.result;
            }

            // Increment progress bar.
            if let Some(progress) = progress.as_ref() {
                progress.inc(1);
            }

            let args = table_fixtures.iter().map(|row| row[i].clone()).collect_vec();
            let (mut raw_call_result, reason) = match self.executor.call(
                self.sender,
                self.address,
                func,
                &args,
                U256::ZERO,
                Some(self.revert_decoder()),
            ) {
                Ok(res) => (res.raw, None),
                Err(EvmError::Execution(err)) => (err.raw, Some(err.reason)),
                Err(EvmError::Skip(reason)) => {
                    self.result.single_skip(reason);
                    return self.result;
                }
                Err(err) => {
                    self.result.single_fail(Some(err.to_string()));
                    return self.result;
                }
            };

            result.gas_by_case.push((raw_call_result.gas_used, raw_call_result.stipend));
            result.logs.extend(raw_call_result.logs.clone());
            result.labels.extend(raw_call_result.labels.clone());
            HitMaps::merge_opt(&mut result.line_coverage, raw_call_result.line_coverage.clone());

            let is_success =
                self.executor.is_raw_call_mut_success(self.address, &mut raw_call_result, false);
            // Record counterexample if test fails.
            if !is_success {
                result.counterexample =
                    Some(CounterExample::Single(BaseCounterExample::from_fuzz_call(
                        Bytes::from(func.abi_encode_input(&args).unwrap()),
                        args,
                        raw_call_result.traces.clone(),
                    )));
                result.reason = reason;
                result.traces = raw_call_result.traces;
                self.result.table_result(result);
                return self.result;
            }

            // If it's the last iteration and all other runs succeeded, then use last call result
            // for logs and traces.
            if i == fixtures_len - 1 {
                result.success = true;
                result.traces = raw_call_result.traces;
                self.result.table_result(result);
                return self.result;
            }
        }

        self.result
    }

    fn run_invariant_test(
        mut self,
        func: &Function,
        invariants: Vec<(&Function, bool)>,
        call_after_invariant: bool,
        identified_contracts: &ContractsByAddress,
    ) -> TestResult {
        // First, run the test normally to see if it needs to be skipped.
        if let Err(EvmError::Skip(reason)) = self.executor.call(
            self.sender,
            self.address,
            func,
            &[],
            U256::ZERO,
            Some(self.revert_decoder()),
        ) {
            self.result.invariant_skip(reason);
            return self.result;
        };

        let runner = self.invariant_runner();
        let invariant_config = self.config.invariant.clone();
        let invariant_config = &invariant_config;

        let mut executor = self.clone_executor();
        // Enable edge coverage if running with coverage guided fuzzing or with edge coverage
        // metrics (useful for benchmarking the fuzzer).
        executor
            .inspector_mut()
            .collect_edge_coverage(invariant_config.corpus.collect_evm_edge_coverage());
        executor.inspector_mut().collect_evm_cmp_log(invariant_config.corpus.collect_evm_cmp_log());
        executor
            .inspector_mut()
            .collect_sancov_edges(invariant_config.corpus.collect_sancov_edges());
        executor
            .inspector_mut()
            .collect_sancov_trace_cmp(invariant_config.corpus.collect_sancov_trace_cmp());
        let mut config = invariant_config.clone();
        let (failure_dir, failure_file) = test_paths(
            &mut config.corpus,
            invariant_config.failure_persist_dir.clone().unwrap(),
            self.cr.name,
            &func.name,
        );

        let mut evm = InvariantExecutor::new(
            executor,
            runner,
            config,
            identified_contracts,
            &self.cr.mcr.known_contracts,
        );
        // Filter out additional invariants to test if we already have a persisted failure.
        // Optimization mode only tracks the primary invariant's return value, so secondary
        // boolean invariants are excluded to avoid silently skipping them.
        let is_optimization = is_optimization_invariant(func);
        // When the primary is an optimization invariant and the user has assert_all on, warn
        // them once that secondary boolean invariants in the same contract are being skipped
        // — assert_all has no effect under optimization mode, so silently dropping them would
        // be a footgun.
        if is_optimization && invariant_config.assert_all {
            let dropped: Vec<&str> = invariants
                .iter()
                .filter(|(invariant_fn, _)| *invariant_fn != func)
                .map(|(invariant_fn, _)| invariant_fn.name.as_str())
                .collect();
            if !dropped.is_empty() {
                let _ = sh_warn!(
                    "{}: assert_all is on but {} is an optimization invariant; \
                     {} boolean invariant(s) skipped: {}. \
                     Move them to a separate contract to run them.",
                    self.cr.name,
                    func.name,
                    dropped.len(),
                    dropped.join(", "),
                );
            }
        }
        // Compute current invariant settings up front so secondary persisted-failure handling
        // can use the same compatibility check as the primary replay path below.
        let current_settings = match evm.compute_settings(self.address) {
            Ok(s) => s,
            Err(e) => {
                self.result.invariant_setup_fail(e);
                return self.result;
            }
        };
        // A secondary's persisted failure is only honored when its embedded settings still
        // match the current run; stale caches fall back to a fresh campaign.
        let secondary_has_compatible_persisted = |invariant_fn: &Function| {
            persisted_call_sequence(
                canonicalized(failure_dir.join(invariant_fn.name.clone())).as_path(),
                &current_settings,
            )
            .is_some()
        };
        // Warn when secondaries are dropped because they already have persisted failures from a
        // previous campaign. Symmetric with the primary's persisted-replay warning so users
        // aren't surprised when fewer invariants appear in the report than their contract
        // defines (Echidna/Medusa never skip properties between runs).
        if !is_optimization && invariant_config.assert_all {
            let persisted_skipped: Vec<&str> = invariants
                .iter()
                .filter(|(invariant_fn, _)| {
                    *invariant_fn != func && secondary_has_compatible_persisted(invariant_fn)
                })
                .map(|(invariant_fn, _)| invariant_fn.name.as_str())
                .collect();
            if !persisted_skipped.is_empty() {
                let _ = sh_warn!(
                    "{}: {} invariant(s) skipped due to persisted failures: {}. \
                     Run `forge clean` or delete files in {} to re-include.",
                    self.cr.name,
                    persisted_skipped.len(),
                    persisted_skipped.join(", "),
                    failure_dir.display(),
                );
            }
        }
        // Build the invariant list in source declaration order, retaining the anchor (`func`)
        // and — under `assert_all` — every other invariant that doesn't already have a
        // compatible persisted failure. Track the anchor's index so downstream consumers can
        // resolve the campaign-anchor without searching by name.
        let invariant_fns: Vec<(&Function, bool)> = invariants
            .into_iter()
            .filter(|(invariant_fn, _)| {
                *invariant_fn == func
                    || (!is_optimization
                        && invariant_config.assert_all
                        && !secondary_has_compatible_persisted(invariant_fn))
            })
            .collect();
        let anchor_idx = invariant_fns
            .iter()
            .position(|(invariant_fn, _)| *invariant_fn == func)
            .expect("anchor must be present in invariant_fns");
        let invariant_contract = InvariantContract::new(
            self.address,
            self.cr.name,
            invariant_fns,
            anchor_idx,
            call_after_invariant,
            &self.cr.contract.abi,
        );
        let show_solidity = invariant_config.show_solidity;

        let progress = start_fuzz_progress(
            self.cr.progress,
            self.cr.name,
            &func.name,
            invariant_config.timeout,
            invariant_config.runs,
        );

        let replay_ctx = ReplayContext {
            invariant_contract: &invariant_contract,
            invariant_config,
            revert_decoder: self.revert_decoder(),
            show_solidity,
        };

        // Try to replay recorded failure if any.
        if let Some(InvariantPersistedFailure { mut call_sequence, assertion_failure, .. }) =
            persisted_call_sequence(failure_file.as_path(), &current_settings)
        {
            let (txes, replay) = replay_persisted_call_sequence(
                &replay_ctx,
                self.clone_executor(),
                &mut call_sequence,
                assertion_failure,
            );
            if let Ok((success, replayed_entirely, replay_reason)) = replay
                && !success
            {
                let warn = format!(
                    "Replayed invariant failure from {:?} file. \nRun `forge clean` or remove file to ignore failure and to continue invariant test campaign.",
                    failure_file.as_path()
                );

                if let Some(ref progress) = progress {
                    progress.set_prefix(format!("{}\n{warn}\n", func.name));
                } else {
                    let _ = sh_warn!("{warn}");
                }

                // If sequence still fails then replay error to collect traces and exit without
                // executing new runs.
                match replay_error(
                    evm.config(),
                    self.clone_executor(),
                    &txes,
                    None,
                    assertion_failure,
                    None, // check mode
                    &invariant_contract,
                    invariant_contract.anchor(),
                    &self.cr.mcr.known_contracts,
                    identified_contracts.clone(),
                    &mut self.result.logs,
                    &mut self.result.traces,
                    &mut self.result.line_coverage,
                    &mut self.result.deprecated_cheatcodes,
                    progress.as_ref(),
                    &self.tcfg.early_exit,
                    None, // single-invariant replay path; no [i/N] counter
                ) {
                    Ok(replayed_call_sequence) if !replayed_call_sequence.is_empty() => {
                        call_sequence = replayed_call_sequence;
                        // Persist error in invariant failure dir.
                        record_invariant_failure(
                            failure_dir.as_path(),
                            failure_file.as_path(),
                            &call_sequence,
                            &current_settings,
                            assertion_failure,
                        );
                    }
                    Ok(_) => {}
                    Err(err) => {
                        error!(%err, "Failed to replay invariant error");
                    }
                }

                self.result.invariant_replay_fail(
                    replayed_entirely,
                    &invariant_contract.anchor().name,
                    replay_reason,
                    call_sequence,
                );
                return self.result;
            }
        }

        // Replay persisted handler bugs; feed still-reproducing ones into the campaign,
        // delete stale files in place.
        let persisted_handler_failures = replay_persisted_handler_failures(
            &failure_dir.join("handlers"),
            &current_settings,
            self.clone_executor(),
            &replay_ctx,
        );

        let invariant_result = match evm.invariant_fuzz(
            invariant_contract.clone(),
            &self.setup.fuzz_fixtures,
            self.build_fuzz_state(true),
            progress.as_ref(),
            &self.tcfg.early_exit,
            persisted_handler_failures,
        ) {
            Ok(x) => x,
            Err(e) => {
                self.result.invariant_setup_fail(e);
                return self.result;
            }
        };
        // Merge coverage collected during invariant run with test setup coverage.
        self.result.merge_coverages(invariant_result.line_coverage);

        let mut counterexample = None;
        // Success requires zero predicate breaks *and* zero handler-side assertion bugs.
        let success =
            invariant_result.errors.is_empty() && invariant_result.handler_errors.is_empty();
        let mut invariant_failures: Vec<InvariantFailure> = vec![];
        let mut any_failure_persisted = false;

        if success {
            if let Some(best_value) = invariant_result.optimization_best_value {
                // Optimization mode: replay and shrink to find shortest best sequence.
                match replay_error(
                    evm.config(),
                    self.clone_executor(),
                    &invariant_result.optimization_best_sequence,
                    None,
                    false,
                    Some(best_value),
                    &invariant_contract,
                    invariant_contract.anchor(),
                    &self.cr.mcr.known_contracts,
                    identified_contracts.clone(),
                    &mut self.result.logs,
                    &mut self.result.traces,
                    &mut self.result.line_coverage,
                    &mut self.result.deprecated_cheatcodes,
                    progress.as_ref(),
                    &self.tcfg.early_exit,
                    None, // optimization mode is single-invariant; no [i/N] counter
                ) {
                    Ok(best_sequence) if !best_sequence.is_empty() => {
                        counterexample = Some(CounterExample::Sequence(
                            invariant_result.optimization_best_sequence.len(),
                            best_sequence,
                        ));
                    }
                    Err(err) => {
                        error!(%err, "Failed to replay optimization best sequence");
                    }
                    _ => {}
                }
            } else {
                // Standard check mode: replay last run for traces.
                if let Err(err) = replay_run(
                    &invariant_contract,
                    invariant_contract.anchor(),
                    self.clone_executor(),
                    &self.cr.mcr.known_contracts,
                    identified_contracts.clone(),
                    &mut self.result.logs,
                    &mut self.result.traces,
                    &mut self.result.line_coverage,
                    &mut self.result.deprecated_cheatcodes,
                    &invariant_result.last_run_inputs,
                    show_solidity,
                ) {
                    error!(%err, "Failed to replay last invariant run");
                }
            }
        } else {
            // Total broken invariants in this campaign — used to decorate the shrink progress
            // bar with `[i/N]` so users see how many shrinkers are queued behind the current
            // one. `errors` keys cover both the anchor and any broken secondaries.
            let total_broken = invariant_result.errors.len();
            // Replay-and-shrink the anchor's failure first (gets [1/N] on the progress bar),
            // then push it into `invariant_failures` as the first entry. Non-replayable error
            // variants (e.g. `MaxAssumeRejects`) still get an entry — without a counterexample
            // — so the reason is rendered.
            if let Some(error) = invariant_result.errors.get(&invariant_contract.anchor().name) {
                let anchor_counterexample = match error {
                    InvariantFuzzError::BrokenInvariant(case_data)
                    | InvariantFuzzError::Revert(case_data) => {
                        let TestError::Fail(_, ref calls) = case_data.test_error else {
                            unreachable!("FailedInvariantCaseData::new always sets TestError::Fail")
                        };
                        match replay_error(
                            evm.config(),
                            self.clone_executor(),
                            calls,
                            Some(case_data.inner_sequence.clone()),
                            case_data.assertion_failure,
                            None, // check mode
                            &invariant_contract,
                            invariant_contract.anchor(),
                            &self.cr.mcr.known_contracts,
                            identified_contracts.clone(),
                            &mut self.result.logs,
                            &mut self.result.traces,
                            &mut self.result.line_coverage,
                            &mut self.result.deprecated_cheatcodes,
                            progress.as_ref(),
                            &self.tcfg.early_exit,
                            Some((1, total_broken)),
                        ) {
                            Ok(call_sequence) if !call_sequence.is_empty() => {
                                record_invariant_failure(
                                    failure_dir.as_path(),
                                    failure_file.as_path(),
                                    &call_sequence,
                                    &current_settings,
                                    case_data.assertion_failure,
                                );
                                any_failure_persisted = true;
                                Some(CounterExample::Sequence(calls.len(), call_sequence))
                            }
                            Ok(_) => None,
                            Err(err) => {
                                error!(%err, "Failed to replay invariant error");
                                None
                            }
                        }
                    }
                    InvariantFuzzError::MaxAssumeRejects(_) => None,
                    // Handler bugs live in `handler_errors`; defensive None here.
                    InvariantFuzzError::HandlerAssertion(_) => None,
                };
                invariant_failures.push(InvariantFailure::Predicate {
                    name: invariant_contract.anchor().name.clone(),
                    reason: error.revert_reason().unwrap_or_default(),
                    counterexample: anchor_counterexample,
                    persisted_path: failure_file,
                    is_anchor: true,
                });
            }

            // Shrink each broken non-primary invariant in turn so users get a ready-to-debug
            // counterexample for every failure in a single run. Loop is serial; on Ctrl+C we
            // still record every known secondary failure (without shrinking or persisting), so
            // the final report matches what the live progress bar showed.
            //
            // `next_position` tracks where this invariant sits in the broken queue (primary is
            // 1, secondaries follow). Only incremented when a secondary is actually shrunk so
            // the bar's `[i/N]` counter matches user-visible progress.
            let mut next_position = 2usize;
            // Iterate every invariant; skip the anchor (handled in the primary path above).
            for (idx, (invariant, _)) in invariant_contract.invariant_fns.iter().enumerate() {
                if idx == invariant_contract.anchor_idx {
                    continue;
                }

                // Skip invariants whose counterexample is already persisted from a prior run
                // (those were filtered out of the live campaign earlier; `errors` won't contain
                // them, but the dir check is a belt-and-braces safety net). Use the same
                // settings-aware compatibility check as the filter so a stale persisted cache
                // doesn't suppress a freshly-broken secondary.
                let persisted_failure = canonicalized(failure_dir.join(invariant.name.clone()));
                if !secondary_has_compatible_persisted(invariant)
                    && let Some(error) = invariant_result.errors.get(&invariant.name)
                    && let InvariantFuzzError::BrokenInvariant(case_data)
                    | InvariantFuzzError::Revert(case_data) = error
                    && let TestError::Fail(_, ref calls) = case_data.test_error
                {
                    let original_seq_len = calls.len();
                    // On Ctrl+C: skip the (potentially long) replay+shrink, but still persist
                    // the un-shrunk sequence so the next run targeting this invariant picks it
                    // up and shrinks from the saved counterexample. The current run's output
                    // still gets a terse `name: reason` line via the no-counterexample path.
                    let secondary_counterexample = if self.tcfg.early_exit.should_stop() {
                        let unshrunk_sequence = calls
                            .iter()
                            .map(|tx| {
                                BaseCounterExample::from_invariant_call(
                                    tx,
                                    identified_contracts,
                                    None,
                                    invariant_config.show_solidity,
                                )
                            })
                            .collect::<Vec<_>>();
                        record_invariant_failure(
                            failure_dir.as_path(),
                            persisted_failure.as_path(),
                            &unshrunk_sequence,
                            &current_settings,
                            case_data.assertion_failure,
                        );
                        any_failure_persisted = true;
                        None
                    } else {
                        let position = next_position;
                        next_position += 1;
                        match replay_error(
                            invariant_config.clone(),
                            self.clone_executor(),
                            calls,
                            Some(case_data.inner_sequence.clone()),
                            case_data.assertion_failure,
                            None, // check mode
                            &invariant_contract,
                            invariant,
                            &self.cr.mcr.known_contracts,
                            identified_contracts.clone(),
                            &mut self.result.logs,
                            &mut self.result.traces,
                            &mut self.result.line_coverage,
                            &mut self.result.deprecated_cheatcodes,
                            progress.as_ref(),
                            &self.tcfg.early_exit,
                            Some((position, total_broken)),
                        ) {
                            Ok(call_sequence) if !call_sequence.is_empty() => {
                                record_invariant_failure(
                                    failure_dir.as_path(),
                                    persisted_failure.as_path(),
                                    &call_sequence,
                                    &current_settings,
                                    case_data.assertion_failure,
                                );
                                any_failure_persisted = true;
                                Some(CounterExample::Sequence(original_seq_len, call_sequence))
                            }
                            Ok(_) => None,
                            Err(err) => {
                                error!(%err, "Failed to replay invariant error");
                                None
                            }
                        }
                    };
                    invariant_failures.push(InvariantFailure::Predicate {
                        name: invariant.name.clone(),
                        reason: error.revert_reason().unwrap_or_default(),
                        counterexample: secondary_counterexample,
                        persisted_path: persisted_failure.clone(),
                        is_anchor: false,
                    });
                }
            }
        }

        let invariant_failure_dir = any_failure_persisted.then(|| failure_dir.clone());
        // Only attach a suite-level roll-up when `assert_all` actually exercised >1 invariant.
        // Single-invariant runs (no assert_all, or filter-narrowed to one) get the legacy
        // single-block render with no roll-up line.
        let assert_all_invariant_count = (invariant_config.assert_all
            && invariant_contract.invariant_fns.len() > 1)
            .then_some(invariant_contract.invariant_fns.len());

        // Convert handler-side assertion bugs into render-ready entries. The name is a
        // best-effort `Contract::function` from `identified_contracts`, falling back to
        // `0xreverter::0xselector`. Map is keyed by `(reverter, selector)` site so multiple
        // code paths through the same function collapse to one entry, rendered in the
        // dedicated `Suite handlers:` section.
        let identified_contracts_ro = identified_contracts;
        let invariant_handler_failures = invariant_result
            .handler_errors
            .iter()
            .sorted_by(|(ka, _), (kb, _)| {
                // Stable order across runs: sort by `(reverter, selector)` site directly.
                ka.cmp(kb)
            })
            .filter_map(|(site, err)| err.as_handler_assertion().map(|f| (site, f)))
            .map(|(_site, failure)| {
                let reverter = failure.reverter;
                let selector = failure.selector;
                // Resolve `Contract::function` from identified contracts when possible.
                let resolved_name = identified_contracts_ro
                    .get(&reverter)
                    .and_then(|(contract_name, abi)| {
                        abi.functions()
                            .find(|f| f.selector() == selector)
                            .map(|f| format!("{contract_name}::{}", f.name))
                    })
                    .unwrap_or_else(|| format!("{reverter}::{selector}"));

                let counterexample_calls = failure
                    .call_sequence
                    .iter()
                    .map(|tx| {
                        BaseCounterExample::from_invariant_call(
                            tx,
                            identified_contracts_ro,
                            None,
                            invariant_config.show_solidity,
                        )
                    })
                    .collect::<Vec<_>>();

                // Persist for next-run replay (skip if nothing to record).
                if !counterexample_calls.is_empty() {
                    record_handler_failure(
                        failure_dir.as_path(),
                        reverter,
                        selector,
                        &counterexample_calls,
                        &current_settings,
                    );
                }

                let counterexample = if counterexample_calls.is_empty() {
                    None
                } else {
                    // Preserve pre-shrink length for `(original: N, shrunk: M)` rendering.
                    Some(CounterExample::Sequence(
                        failure.original_sequence_len,
                        counterexample_calls,
                    ))
                };

                InvariantFailure::Handler {
                    name: resolved_name,
                    reverter,
                    selector,
                    reason: failure.revert_reason.clone(),
                    counterexample,
                }
            })
            .collect::<Vec<_>>();

        self.result.invariant_result(
            invariant_result.gas_report_traces,
            success,
            invariant_failures,
            invariant_failure_dir,
            assert_all_invariant_count,
            invariant_handler_failures,
            counterexample,
            invariant_result.cases,
            invariant_result.reverts,
            invariant_result.metrics,
            invariant_result.failed_corpus_replays,
            invariant_result.optimization_best_value,
        );
        self.result
    }

    /// Runs a fuzzed test.
    ///
    /// Applies the before test txes (if any), fuzzes the current function and returns the
    /// `TestResult`.
    ///
    /// Before test txes are applied in order and state modifications committed to the EVM database
    /// (therefore the fuzz test will use the modified state).
    /// State modifications of before test txes and fuzz test are discarded after test ends,
    /// similar to `eth_call`.
    fn run_fuzz_test(mut self, func: &Function) -> TestResult {
        // Prepare fuzz test execution.
        if self.prepare_test(func).is_err() {
            return self.result;
        }

        let runner = self.fuzz_runner();
        let mut fuzz_config = self.config.fuzz.clone();
        let (failure_dir, failure_file) = test_paths(
            &mut fuzz_config.corpus,
            fuzz_config.failure_persist_dir.clone().unwrap(),
            self.cr.name,
            &func.name,
        );

        let progress = start_fuzz_progress(
            self.cr.progress,
            self.cr.name,
            &func.name,
            fuzz_config.timeout,
            if fuzz_config.run.is_some() { 1 } else { fuzz_config.runs },
        );

        let state = self.build_fuzz_state(false);
        let mut executor = self.executor.into_owned();
        // Enable edge coverage if running with coverage guided fuzzing or with edge coverage
        // metrics (useful for benchmarking the fuzzer).
        executor
            .inspector_mut()
            .collect_edge_coverage(fuzz_config.corpus.collect_evm_edge_coverage());
        executor.inspector_mut().collect_evm_cmp_log(fuzz_config.corpus.collect_evm_cmp_log());
        executor.inspector_mut().collect_sancov_edges(fuzz_config.corpus.collect_sancov_edges());
        executor
            .inspector_mut()
            .collect_sancov_trace_cmp(fuzz_config.corpus.collect_sancov_trace_cmp());
        // Load persisted counterexample, if any.
        let persisted_failure =
            foundry_common::fs::read_json_file::<BaseCounterExample>(failure_file.as_path()).ok();
        // Run fuzz test.
        let mut fuzzed_executor =
            FuzzedExecutor::new(executor, runner, self.tcfg.sender, fuzz_config, persisted_failure);
        let result = match fuzzed_executor.fuzz(
            func,
            &self.setup.fuzz_fixtures,
            state,
            self.address,
            &self.cr.mcr.revert_decoder,
            progress.as_ref(),
            &self.tcfg.early_exit,
            self.cr.tokio_handle,
        ) {
            Ok(x) => x,
            Err(e) => {
                self.result.fuzz_setup_fail(e);
                return self.result;
            }
        };

        // Record counterexample.
        if let Some(CounterExample::Single(counterexample)) = &result.counterexample {
            if let Err(err) = foundry_common::fs::create_dir_all(failure_dir) {
                error!(%err, "Failed to create fuzz failure dir");
            } else if let Err(err) =
                foundry_common::fs::write_json_file(failure_file.as_path(), counterexample)
            {
                error!(%err, "Failed to record call sequence");
            }
        }

        self.result.fuzz_result(result);
        self.result
    }

    /// Prepares single unit test and fuzz test execution:
    /// - set up the test result and executor
    /// - check if before test txes are configured and apply them in order
    ///
    /// Before test txes are arrays of arbitrary calldata obtained by calling the `beforeTest`
    /// function with test selector as a parameter.
    ///
    /// Unit tests within same contract (or even current test) are valid options for before test tx
    /// configuration. Test execution stops if any of before test txes fails.
    fn prepare_test(&mut self, func: &Function) -> Result<(), ()> {
        let address = self.setup.address;

        // Apply before test configured functions (if any).
        if self.cr.contract.abi.functions().any(|func| func.name.is_before_test_setup()) {
            for calldata in self.executor.call_sol_default(
                address,
                &ITest::beforeTestSetupCall { testSelector: func.selector() },
            ) {
                let spec_id: SpecId = self.executor.spec_id().into();
                debug!(?calldata, spec=%spec_id, "applying before_test_setup");
                // Apply before test configured calldata.
                match self.executor.to_mut().transact_raw(
                    self.tcfg.sender,
                    address,
                    calldata,
                    U256::ZERO,
                ) {
                    Ok(call_result) => {
                        let reverted = call_result.reverted;

                        // Merge tx result traces in unit test result.
                        self.result.extend(call_result);

                        // To continue unit test execution the call should not revert.
                        if reverted {
                            self.result.single_fail(None);
                            return Err(());
                        }
                    }
                    Err(_) => {
                        self.result.single_fail(None);
                        return Err(());
                    }
                }
            }
        }
        Ok(())
    }

    fn fuzz_runner(&self) -> TestRunner {
        let config = &self.config.fuzz;
        fuzzer_with_cases(config.seed, config.runs, config.max_test_rejects)
    }

    fn invariant_runner(&self) -> TestRunner {
        let config = &self.config.invariant;
        fuzzer_with_cases(self.config.fuzz.seed, config.runs, config.max_assume_rejects)
    }

    fn clone_executor(&self) -> Executor<FEN> {
        self.executor.clone().into_owned()
    }

    fn build_fuzz_state(&self, invariant: bool) -> EvmFuzzState {
        let config =
            if invariant { self.config.invariant.dictionary } else { self.config.fuzz.dictionary };
        if let Some(db) = self.executor.backend().active_fork_db() {
            EvmFuzzState::new(
                &self.setup.deployed_libs,
                db,
                config,
                Some(&self.cr.mcr.fuzz_literals),
            )
        } else {
            let db = self.executor.backend().mem_db();
            EvmFuzzState::new(
                &self.setup.deployed_libs,
                db,
                config,
                Some(&self.cr.mcr.fuzz_literals),
            )
        }
    }
}

fn fuzzer_with_cases(seed: Option<U256>, cases: u32, max_global_rejects: u32) -> TestRunner {
    let config = proptest::test_runner::Config {
        cases,
        max_global_rejects,
        // Disable proptest shrink: for fuzz tests we provide single counterexample,
        // for invariant tests we shrink outside proptest.
        max_shrink_iters: 0,
        ..Default::default()
    };

    if let Some(seed) = seed {
        trace!(target: "forge::test", %seed, "building deterministic fuzzer");
        let rng = TestRng::from_seed(RngAlgorithm::ChaCha, &seed.to_be_bytes::<32>());
        TestRunner::new_with_rng(config, rng)
    } else {
        trace!(target: "forge::test", "building stochastic fuzzer");
        TestRunner::new(config)
    }
}

/// Holds data about a persisted invariant failure.
#[derive(Serialize, Deserialize)]
struct InvariantPersistedFailure {
    /// Recorded counterexample.
    call_sequence: Vec<BaseCounterExample>,
    /// Invariant settings when the counterexample was generated.
    /// Used to determine if the counterexample is still valid.
    settings: InvariantSettings,
    /// Whether the persisted failure came from a handler assertion instead of the invariant body.
    #[serde(default)]
    assertion_failure: bool,
}

/// Mirrors `check_sequence`'s return: `(success, replayed_entirely, optional_reason)`.
type CheckSequenceResult = eyre::Result<(bool, bool, Option<String>)>;

/// Borrowed context shared by primary-invariant and handler-side replay helpers.
struct ReplayContext<'a> {
    invariant_contract: &'a InvariantContract<'a>,
    invariant_config: &'a InvariantConfig,
    revert_decoder: &'a RevertDecoder,
    show_solidity: bool,
}

/// Helper function to load failed call sequence from file.
/// Ignores failure if generated with different invariant settings than the current ones.
fn persisted_call_sequence(
    path: &Path,
    current_settings: &InvariantSettings,
) -> Option<InvariantPersistedFailure> {
    foundry_common::fs::read_json_file::<InvariantPersistedFailure>(path).ok().and_then(
        |persisted_failure| {
            if let Some(diff) = persisted_failure.settings.diff(current_settings) {
                let _ = sh_warn!(
                    "Failure from {:?} file was ignored because invariant test settings have changed: {}",
                    path,
                    diff
                );
                return None;
            }
            Some(persisted_failure)
        },
    )
}

/// Converts a persisted counterexample to `BasicTxDetails`, setting `show_solidity` in place.
fn base_counterexamples_to_txes(
    ctx: &ReplayContext<'_>,
    call_sequence: &mut [BaseCounterExample],
) -> Vec<BasicTxDetails> {
    call_sequence
        .iter_mut()
        .map(|seq| {
            seq.show_solidity = ctx.show_solidity;
            BasicTxDetails {
                warp: seq.warp,
                roll: seq.roll,
                sender: seq.sender.unwrap_or_default(),
                call_details: CallDetails {
                    target: seq.addr.unwrap_or_default(),
                    calldata: seq.calldata.clone(),
                    value: seq.value,
                },
            }
        })
        .collect()
}

/// Converts a persisted `BaseCounterExample` sequence into `BasicTxDetails` (applying
/// `ctx.show_solidity` in place) and replays it via `check_sequence`.
fn replay_persisted_call_sequence<FEN: FoundryEvmNetwork>(
    ctx: &ReplayContext<'_>,
    executor: Executor<FEN>,
    call_sequence: &mut [BaseCounterExample],
    expect_assertion_failure: bool,
) -> (Vec<BasicTxDetails>, CheckSequenceResult) {
    let txes = base_counterexamples_to_txes(ctx, call_sequence);
    let result = check_sequence(
        executor,
        &txes,
        (0..min(txes.len(), ctx.invariant_config.depth as usize)).collect(),
        ctx.invariant_contract.address,
        ctx.invariant_contract.anchor().selector().to_vec().into(),
        CheckSequenceOptions {
            accumulate_warp_roll: ctx.invariant_config.has_delay(),
            fail_on_revert: ctx.invariant_config.fail_on_revert,
            expect_assertion_failure,
            call_after_invariant: ctx.invariant_contract.call_after_invariant,
            rd: Some(ctx.revert_decoder),
        },
    );
    (txes, result)
}

/// Helper function to set test corpus dir and to compose persisted failure paths.
fn test_paths(
    corpus_config: &mut FuzzCorpusConfig,
    persist_dir: PathBuf,
    contract_name: &str,
    test_name: &str,
) -> (PathBuf, PathBuf) {
    let contract = contract_name.split(':').next_back().unwrap();
    // Update config with corpus dir for current test.
    corpus_config.with_test(contract, test_name);

    let failures_dir = canonicalized(persist_dir.join("failures").join(contract));
    let failure_file = canonicalized(failures_dir.join(test_name));
    (failures_dir, failure_file)
}

/// Helper function to persist invariant failure.
fn record_invariant_failure(
    failure_dir: &Path,
    failure_file: &Path,
    call_sequence: &[BaseCounterExample],
    settings: &InvariantSettings,
    assertion_failure: bool,
) {
    if let Err(err) = foundry_common::fs::create_dir_all(failure_dir) {
        error!(%err, "Failed to create invariant failure dir");
        return;
    }

    if let Err(err) = foundry_common::fs::write_json_file(
        failure_file,
        &InvariantPersistedFailure {
            call_sequence: call_sequence.to_owned(),
            settings: settings.clone(),
            assertion_failure,
        },
    ) {
        error!(%err, "Failed to record call sequence");
    }
}

/// Persists a handler-side assertion bug under `<failure_dir>/handlers/<site>.json`,
/// where `<site>` is `keccak256(reverter || selector)`.
fn record_handler_failure(
    failure_dir: &Path,
    reverter: Address,
    selector: Selector,
    call_sequence: &[BaseCounterExample],
    settings: &InvariantSettings,
) {
    let handlers_dir = failure_dir.join("handlers");
    if let Err(err) = foundry_common::fs::create_dir_all(&handlers_dir) {
        error!(%err, "Failed to create handler failure dir");
        return;
    }
    let mut buf = [0u8; 24];
    buf[..20].copy_from_slice(reverter.as_slice());
    buf[20..].copy_from_slice(selector.as_slice());
    let site_hash = alloy_primitives::keccak256(buf);
    let file = handlers_dir.join(format!("{site_hash:x}.json"));
    record_invariant_failure(&handlers_dir, &file, call_sequence, settings, true);
}

/// Replays persisted handler-side assertion bugs. A file is kept only if the anchor still
/// asserts at the same `(reverter, selector)` site; stale files (anchor no longer asserts,
/// asserts at a different site, or earlier call asserts) are deleted in place.
fn replay_persisted_handler_failures<FEN: FoundryEvmNetwork>(
    handlers_dir: &Path,
    current_settings: &InvariantSettings,
    executor: Executor<FEN>,
    ctx: &ReplayContext<'_>,
) -> std::collections::HashMap<(Address, Selector), InvariantFuzzError> {
    let mut replayed: std::collections::HashMap<(Address, Selector), InvariantFuzzError> =
        std::collections::HashMap::new();
    let entries = match std::fs::read_dir(handlers_dir) {
        Ok(e) => e,
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return replayed,
        Err(err) => {
            error!(%err, "Failed to read handler failure dir");
            return replayed;
        }
    };
    for entry in entries.flatten() {
        let path = entry.path();
        if path.extension().and_then(|s| s.to_str()) != Some("json") {
            continue;
        }
        let Some(persisted) = persisted_call_sequence(&path, current_settings) else {
            continue;
        };
        let mut call_sequence = persisted.call_sequence;
        if call_sequence.is_empty() {
            let _ = std::fs::remove_file(&path);
            continue;
        }
        let txes = base_counterexamples_to_txes(ctx, &mut call_sequence);
        // Expected site = (target, selector) of the persisted reproducer's last call.
        let Some(last) = txes.last() else {
            let _ = std::fs::remove_file(&path);
            continue;
        };
        let expected_target = last.call_details.target;
        let expected_selector_bytes: [u8; 4] =
            last.call_details.calldata.get(..4).and_then(|s| s.try_into().ok()).unwrap_or_default();
        let expected_site = (expected_target, Selector::from(expected_selector_bytes));
        let sequence: Vec<usize> =
            (0..min(txes.len(), ctx.invariant_config.depth as usize)).collect();
        let outcome = replay_handler_failure_sequence(
            executor.clone(),
            &txes,
            sequence,
            ctx.invariant_config.has_delay(),
            Some(ctx.revert_decoder),
        );
        match outcome {
            Ok(outcome) if outcome.anchor_asserted => {
                let _ = sh_warn!(
                    "Replayed handler-side assertion bug from {path:?}. \nRun `forge clean` or remove file to ignore."
                );
                let failure = HandlerAssertionFailure::from_replayed_sequence(
                    txes,
                    outcome.anchor_fingerprint,
                    outcome.revert_reason.unwrap_or_default(),
                );
                // On collision keep the shorter reproducer. Inlined: `replayed` uses the legacy
                // `(reverter, selector)` key, not the unified `FailureKey`.
                let already_shorter = replayed
                    .get(&expected_site)
                    .and_then(InvariantFuzzError::as_handler_assertion)
                    .is_some_and(|existing| {
                        existing.call_sequence.len() <= failure.call_sequence.len()
                    });
                if !already_shorter {
                    replayed.insert(expected_site, InvariantFuzzError::HandlerAssertion(failure));
                }
            }
            // Stale: anchor doesn't assert or earlier call asserts.
            Ok(_) => {
                let _ = std::fs::remove_file(&path);
            }
            Err(err) => {
                error!(%err, "Failed to replay handler-side assertion bug");
            }
        }
    }
    replayed
}