Skip to main content

forge/
multi_runner.rs

1//! Forge test runner for multiple contracts.
2
3use crate::{
4    ContractRunner, TestFilter,
5    progress::TestsProgress,
6    result::{SuiteResult, SymbolicCounterexampleArtifact, SymbolicCounterexampleArtifactKind},
7    runner::{
8        ContractRunnerContext, InvariantCampaignScope, count_runnable_invariant_campaign_anchors,
9        function_matches_network_pass, inline_config_for,
10    },
11    symbolic_regression::SYMBOLIC_REGRESSION_MARKER,
12};
13use alloy_json_abi::{Function, JsonAbi};
14use alloy_primitives::{Address, Bytes, ChainId, U256};
15use eyre::Result;
16use foundry_cli::opts::configure_pcx_from_compile_output;
17use foundry_common::{
18    ContractsByArtifact, ContractsByArtifactBuilder, EmptyTestFilter, LIBRARY_DEPLOYER,
19    TestFunctionKind, external_compiler::external_artifact_is_test_eligible, get_contract_name,
20    namespaced_storage,
21};
22use foundry_compilers::{
23    Artifact, ArtifactId, Compiler, ProjectCompileOutput,
24    artifacts::{Contract, Libraries},
25};
26use foundry_config::{Config, FoundryHardfork, InlineConfig};
27use foundry_evm::{
28    backend::Backend,
29    core::evm::{EvmEnvFor, EvmFactoryFor, FoundryEvmNetwork, SpecFor, TransactionRequestFor},
30    decode::RevertDecoder,
31    executors::{EarlyExit, Executor, ExecutorBuilder, ReplayObservation, ShowmapDomain},
32    fuzz::{
33        BaseCounterExample, BasicTxDetails,
34        strategies::{EnumBounds, LiteralsDictionary},
35    },
36    inspectors::{CheatsConfig, EdgeIndexMap},
37    opts::{EvmOpts, ExecutionSpecContext, resolve_execution_spec},
38    traces::{InternalTraceMode, TraceRequirements},
39};
40use foundry_evm_networks::NetworkVariant;
41
42use foundry_linking::{DetailedLinkOutput, LinkOutput, Linker, LinkerError, Resolver};
43use rayon::prelude::*;
44use std::{
45    borrow::{Borrow, Cow},
46    collections::{BTreeMap, BTreeSet, HashMap},
47    ops::{Deref, DerefMut},
48    path::PathBuf,
49    sync::{Arc, Mutex, mpsc},
50    time::Instant,
51};
52
53#[derive(Debug, Clone)]
54pub struct TestContract {
55    pub abi: JsonAbi,
56    pub bytecode: Bytes,
57    pub library_addresses: BTreeSet<Address>,
58}
59
60pub type DeployableContracts = BTreeMap<ArtifactId, TestContract>;
61
62/// A multi contract runner receives a set of contracts deployed in an EVM instance and proceeds
63/// to run all test functions in these contracts.
64#[derive(Clone, Debug)]
65pub struct MultiContractRunner<FEN: FoundryEvmNetwork> {
66    /// Mapping of contract name to JsonAbi, creation bytecode and library bytecode which
67    /// needs to be deployed & linked against
68    pub contracts: DeployableContracts,
69    /// Known contracts linked with computed library addresses.
70    pub known_contracts: ContractsByArtifact,
71    /// Revert decoder. Contains all known errors and their selectors.
72    pub revert_decoder: RevertDecoder,
73    /// Libraries to deploy.
74    pub libs_to_deploy: Vec<Bytes>,
75    /// Addresses of libraries required by linked test artifacts.
76    pub library_addresses: Vec<Address>,
77    /// How libraries should be deployed.
78    pub library_deployment: LibraryDeployment,
79    /// Library addresses used to link contracts.
80    pub libraries: Libraries,
81    /// Solar compiler instance, to grant syntactic and semantic analysis capabilities
82    pub analysis: Arc<solar::sema::Compiler>,
83    /// Literals dictionary for fuzzing.
84    pub fuzz_literals: LiteralsDictionary,
85    /// Literals dictionary for invariant fuzzing.
86    pub invariant_literals: LiteralsDictionary,
87    /// Variant counts for project enums, used to constrain fuzzed enum inputs.
88    pub enum_bounds: EnumBounds,
89
90    /// Pristine backend cloned for every test execution.
91    pub backend: Backend<FEN>,
92
93    /// The base configuration for the test runner.
94    pub tcfg: TestRunnerConfig<FEN>,
95}
96
97/// Forge-local library deployment strategy.
98#[derive(Clone, Copy, Debug)]
99pub enum LibraryDeployment {
100    Nonce,
101    Create2 { deployer: Address, salt: alloy_primitives::B256 },
102}
103
104impl<FEN: FoundryEvmNetwork> Deref for MultiContractRunner<FEN> {
105    type Target = TestRunnerConfig<FEN>;
106
107    fn deref(&self) -> &Self::Target {
108        &self.tcfg
109    }
110}
111
112impl<FEN: FoundryEvmNetwork> DerefMut for MultiContractRunner<FEN> {
113    fn deref_mut(&mut self) -> &mut Self::Target {
114        &mut self.tcfg
115    }
116}
117
118impl<FEN: FoundryEvmNetwork> MultiContractRunner<FEN> {
119    pub(crate) fn test_function_matcher(&self) -> TestFunctionMatcher<'_> {
120        TestFunctionMatcher::new(
121            &self.config,
122            &self.inline_config,
123            self.tcfg.symbolic_artifact_replay.as_ref(),
124        )
125    }
126
127    /// Returns an iterator over all contracts that match the filter.
128    pub fn matching_contracts<'a: 'b, 'b>(
129        &'a self,
130        filter: &'b dyn TestFilter,
131    ) -> impl Iterator<Item = (&'a ArtifactId, &'a TestContract)> + 'b {
132        let matcher = self.test_function_matcher();
133        self.contracts.iter().filter(move |&(id, c)| matcher.matches_contract(filter, id, &c.abi))
134    }
135
136    /// Returns an iterator over all test functions that match the filter.
137    pub fn matching_test_functions<'a: 'b, 'b>(
138        &'a self,
139        filter: &'b dyn TestFilter,
140    ) -> impl Iterator<Item = &'a Function> + 'b {
141        let matcher = self.test_function_matcher();
142        self.matching_contracts(filter)
143            .flat_map(move |(id, c)| matcher.matching_test_functions(filter, id, &c.abi))
144    }
145
146    /// Returns an iterator over all test functions in contracts that match the filter.
147    pub fn all_test_functions<'a: 'b, 'b>(
148        &'a self,
149        filter: &'b dyn TestFilter,
150    ) -> impl Iterator<Item = &'a Function> + 'b {
151        let matcher = self.test_function_matcher();
152        self.contracts
153            .iter()
154            .filter(|(id, _)| filter.matches_path(&id.source) && filter.matches_contract(&id.name))
155            .flat_map(move |(id, c)| {
156                matcher.test_functions(id.identifier(), &c.abi, |_, _, kind| kind.is_any_test())
157            })
158    }
159
160    /// Returns all matching tests grouped by contract grouped by file (file -> (contract -> tests))
161    pub fn list(&self, filter: &dyn TestFilter) -> BTreeMap<String, BTreeMap<String, Vec<String>>> {
162        self.list_with(filter, |func| func.name.clone())
163    }
164
165    pub(crate) fn list_signatures(
166        &self,
167        filter: &dyn TestFilter,
168    ) -> BTreeMap<String, BTreeMap<String, Vec<String>>> {
169        self.list_with(filter, |func| func.signature())
170    }
171
172    fn list_with(
173        &self,
174        filter: &dyn TestFilter,
175        format_test: impl Fn(&Function) -> String,
176    ) -> BTreeMap<String, BTreeMap<String, Vec<String>>> {
177        let matcher = self.test_function_matcher();
178        let fuzz_only = self.tcfg.fuzz_only;
179        let mut out = BTreeMap::<_, BTreeMap<_, _>>::new();
180        for (id, c) in self.matching_contracts(filter) {
181            let tests = matcher
182                .test_functions(id.identifier(), &c.abi, |contract_id, func, kind| {
183                    (!fuzz_only
184                        || matches!(
185                            kind,
186                            TestFunctionKind::FuzzTest { .. } | TestFunctionKind::InvariantTest
187                        ))
188                        && filter.matches_test_function_kind_in_contract(contract_id, func, kind)
189                })
190                .map(&format_test)
191                .collect::<Vec<_>>();
192            if !tests.is_empty() {
193                out.entry(id.source.display().to_string())
194                    .or_default()
195                    .insert(id.name.clone(), tests);
196            }
197        }
198        out
199    }
200
201    /// Executes _all_ tests that match the given `filter`.
202    ///
203    /// The same as [`test`](Self::test), but returns the results instead of streaming them.
204    ///
205    /// Note that this method returns only when all tests have been executed.
206    pub fn test_collect(
207        &mut self,
208        filter: &dyn TestFilter,
209    ) -> Result<BTreeMap<String, SuiteResult>> {
210        let (tx, rx) = mpsc::channel();
211        self.test(filter, tx, false)?;
212        Ok(rx.into_iter().collect())
213    }
214
215    /// Executes _all_ tests that match the given `filter`.
216    ///
217    /// This will create the runtime based on the configured `evm` ops and create the `Backend`
218    /// before executing all contracts and their tests in _parallel_.
219    ///
220    /// Each Executor gets its own instance of the `Backend`.
221    pub fn test(
222        &mut self,
223        filter: &dyn TestFilter,
224        tx: mpsc::Sender<(String, SuiteResult)>,
225        show_progress: bool,
226    ) -> Result<()> {
227        let tokio_handle = tokio::runtime::Handle::current();
228        trace!("running all tests");
229
230        // The DB backend that serves all the data.
231        let db = self.backend.clone();
232
233        let find_timer = Instant::now();
234        let contracts = self.matching_contracts(filter).collect::<Vec<_>>();
235        debug!(
236            "Found {} test contracts out of {} in {:?}",
237            contracts.len(),
238            self.contracts.len(),
239            find_timer.elapsed(),
240        );
241        let num_invariant_campaign_anchors = contracts
242            .iter()
243            .map(|(id, contract)| {
244                count_runnable_invariant_campaign_anchors(
245                    &contract.abi,
246                    filter,
247                    InvariantCampaignScope {
248                        config: &self.tcfg.config,
249                        inline_config: &self.tcfg.inline_config,
250                        contract_name: &id.identifier(),
251                        all_override_networks: &self.tcfg.multi_network.all_override_networks,
252                        pass_network: self.tcfg.multi_network.pass_network.as_ref(),
253                    },
254                )
255            })
256            .sum();
257
258        let progress = show_progress
259            .then(|| TestsProgress::new(contracts.len(), rayon::current_num_threads()));
260        let run_suite = |&(id, contract): &(&ArtifactId, &TestContract)| {
261            let _guard = tokio_handle.enter();
262            let identifier = id.identifier();
263            if let Some(progress) = &progress {
264                progress.inner.lock().start_suite_progress(&identifier);
265            }
266            let result = self.run_test_suite(
267                id,
268                contract,
269                &db,
270                filter,
271                ContractRunnerContext {
272                    progress: progress.as_ref(),
273                    tokio_handle: tokio_handle.clone(),
274                    num_invariant_campaign_anchors,
275                },
276            );
277            if let Some(progress) = &progress {
278                progress.inner.lock().end_suite_progress(&identifier, result.summary());
279            }
280            (identifier, result)
281        };
282
283        if let Some(progress) = &progress {
284            // Collect test suite results to stream at the end of test run, once the progress bars
285            // have been cleared.
286            let results = contracts.par_iter().map(run_suite).collect::<Vec<_>>();
287            progress.inner.lock().clear();
288            for result in results {
289                let _ = tx.send(result);
290            }
291        } else {
292            contracts.par_iter().for_each(|contract| {
293                let _ = tx.send(run_suite(contract));
294            });
295        }
296
297        Ok(())
298    }
299
300    fn run_test_suite(
301        &self,
302        artifact_id: &ArtifactId,
303        contract: &TestContract,
304        db: &Backend<FEN>,
305        filter: &dyn TestFilter,
306        context: ContractRunnerContext<'_>,
307    ) -> SuiteResult {
308        let identifier = artifact_id.identifier();
309        let span_name = if enabled!(tracing::Level::TRACE) {
310            identifier.as_str()
311        } else {
312            get_contract_name(&identifier)
313        };
314        let span = debug_span!("suite", name = %span_name);
315        let _guard = span.clone().entered();
316
317        debug!("start executing all tests in contract");
318
319        // Resolve the contract's inline config once, for both its backend and its runner.
320        let tcfg = self.contract_tcfg(&identifier);
321        let db = if tcfg.spec_id != self.tcfg.spec_id && !db.is_forked_mode() {
322            db.clone_empty_with_env(tcfg.evm_env)
323        } else {
324            db.clone()
325        };
326        // Built from the shared config: the runner applies the contract's config before
327        // `setUp` and keeps the shared trace and live-log settings.
328        let executor = self.tcfg.executor(
329            self.known_contracts.clone(),
330            self.analysis.clone(),
331            artifact_id,
332            db,
333        );
334        let runner =
335            ContractRunner::new(&identifier, contract, executor, tcfg, span, self, context);
336        let r = runner.run_tests(filter);
337
338        debug!(duration=?r.duration, "executed all tests in contract");
339
340        r
341    }
342
343    /// Returns the test configuration for `identifier`'s suite, with its contract-level inline
344    /// config applied. Borrows the shared configuration when the contract has none, or when it
345    /// fails to resolve, so that the runner reports the error during setup.
346    ///
347    /// Only contract-level config selects the backend's hardfork: a function-level hardfork pin
348    /// runs over network state seeded at its contract's hardfork, since `setUp` runs once per
349    /// contract.
350    fn contract_tcfg(&self, identifier: &str) -> Cow<'_, TestRunnerConfig<FEN>> {
351        if !self.tcfg.inline_config.contains_contract(identifier) {
352            return Cow::Borrowed(&self.tcfg);
353        }
354        let Ok(mut config) =
355            inline_config_for(&self.tcfg.config, &self.tcfg.inline_config, identifier, None)
356        else {
357            return Cow::Borrowed(&self.tcfg);
358        };
359        config.networks = config.networks.with_execution_profile(self.tcfg.evm_opts.networks);
360        let mut tcfg = self.tcfg.clone();
361        tcfg.reconfigure_with(Arc::new(config));
362        Cow::Owned(tcfg)
363    }
364}
365
366/// Tracks network assignment across a multi-network test run.
367///
368/// When inline config specifies different networks for different tests, the runner performs one
369/// pass per distinct network. This struct encodes which pass we're in so each `ContractRunner`
370/// can skip tests that belong to a different pass.
371///
372/// Default (empty `all_override_networks`, `None` pass) = single-pass mode, every test runs.
373#[derive(Clone, Debug, Default)]
374pub struct MultiNetworkConfig {
375    /// All networks explicitly referenced in inline config annotations across the whole suite.
376    /// Empty means single-pass mode (no per-test network overrides present).
377    pub all_override_networks: Vec<NetworkVariant>,
378    /// The network this pass is responsible for.
379    /// `None` = default pass: runs tests *without* an explicit network annotation (or annotated
380    /// with a network not in `all_override_networks`).
381    /// `Some(v)` = override pass: runs only tests annotated with exactly `v`.
382    pub pass_network: Option<NetworkVariant>,
383}
384
385/// CLI-only options that switch fuzz/invariant tests into corpus replay
386/// mode that emits AFL-`afl-showmap`-style coverage files.
387#[derive(Clone, Debug)]
388pub struct ShowmapConfig {
389    /// Output root directory for showmap files.
390    pub out_dir: PathBuf,
391    /// Approach name; used as a subdirectory under `out_dir`.
392    pub approach: String,
393    /// Trial identifier embedded in each emitted filename to keep reruns separate.
394    pub trial: String,
395    /// One file per corpus entry instead of one aggregated file per test.
396    pub per_input: bool,
397    /// Which bitmap(s) to dump.
398    pub domain: ShowmapDomain,
399    /// Optional override for the corpus directory to replay from.
400    /// When unset, the per-test corpus dir derived from config is used.
401    pub corpus_dir: Option<PathBuf>,
402    /// Whether replay should emit showmap files.
403    pub emit_files: bool,
404}
405
406pub type FuzzMinimizeEdgeIndices = Arc<Mutex<BTreeMap<String, Arc<Mutex<EdgeIndexMap>>>>>;
407
408/// Replay behavior required by a fuzz minimization command.
409#[derive(Clone, Copy, Debug, PartialEq, Eq)]
410pub enum FuzzMinimizeMode {
411    /// Replay complete entries so corpus minimization observes all coverage and failures.
412    Cmin,
413    /// Stop at the campaign boundary so transaction minimization ignores unreachable suffixes.
414    Tmin,
415}
416
417/// CLI-only options that switch fuzz/invariant tests into single-entry replay
418/// mode for corpus minimization.
419#[derive(Clone, Debug)]
420pub struct FuzzMinimizeConfig {
421    /// Entry to replay.
422    pub input: Arc<[BasicTxDetails]>,
423    /// Whether replay serves corpus or transaction minimization.
424    pub mode: FuzzMinimizeMode,
425    /// Shared edge-index assignments for all candidate replays in this minimization invocation,
426    /// namespaced by matched target.
427    pub evm_edge_indices: FuzzMinimizeEdgeIndices,
428    /// Shared replay observations collected from matched fuzz/invariant tests.
429    pub observations: Arc<Mutex<Vec<FuzzMinimizeObservation>>>,
430}
431
432/// Replay observation for one matched minimization target.
433#[derive(Clone, Debug)]
434pub struct FuzzMinimizeObservation {
435    /// Stable target identity for this minimization run.
436    pub target: String,
437    /// Replay result for this target.
438    pub observation: ReplayObservation,
439}
440
441#[derive(Clone, Debug)]
442pub struct SymbolicArtifactReplayConfig {
443    /// Artifact payload to replay.
444    pub artifact: SymbolicCounterexampleArtifact,
445    /// Path the artifact was loaded from, used in diagnostics.
446    pub path: PathBuf,
447}
448
449/// A validated stateless fuzz failure and its unique replay target.
450#[derive(Clone, Debug)]
451pub struct FuzzFailureReplayConfig {
452    /// Artifact payload to replay.
453    pub failure: Arc<BaseCounterExample>,
454    /// Fully qualified contract identifier selected for replay.
455    pub contract: String,
456    /// Function signature selected for replay.
457    pub test: String,
458}
459
460/// Configuration for the test runner.
461///
462/// This is modified after instantiation through inline config.
463#[derive(Clone, Debug)]
464pub struct TestRunnerConfig<FEN: FoundryEvmNetwork> {
465    /// Project config.
466    pub config: Arc<Config>,
467    /// Inline configuration.
468    pub inline_config: Arc<InlineConfig>,
469
470    /// EVM configuration.
471    pub evm_opts: EvmOpts,
472    /// Executor construction selected by concrete network dispatch.
473    pub executor_builder: ExecutorBuilder<FEN>,
474    /// EVM environment.
475    pub evm_env: EvmEnvFor<FEN>,
476    /// Transaction defaults.
477    pub tx: TransactionRequestFor<FEN>,
478    /// EVM version.
479    pub spec_id: SpecFor<FEN>,
480    /// Exact network hardfork selected for the execution environment.
481    pub hardfork: Option<FoundryHardfork>,
482    /// Source chain ID used to resolve fork hardfork schedules.
483    pub fork_chain_id: Option<ChainId>,
484    /// Exact hardfork reported by the fork endpoint.
485    pub fork_hardfork: Option<FoundryHardfork>,
486    /// The address which will be used to deploy the initial contracts and send all transactions.
487    pub sender: Address,
488
489    /// Whether to collect line coverage info
490    pub line_coverage: bool,
491    /// Whether to collect debug info
492    pub debug: bool,
493    /// Whether to enable steps tracking in the tracer.
494    pub decode_internal: InternalTraceMode,
495    /// Whether to record every opcode step without debugger snapshots.
496    pub record_all_steps: bool,
497    /// Whether to enable call isolation.
498    pub isolation: bool,
499    /// Whether to exit early on test failure or if test run interrupted.
500    pub early_exit: EarlyExit,
501
502    /// Multi-network pass configuration. Default = single-pass mode.
503    pub multi_network: MultiNetworkConfig,
504
505    /// When set, fuzz/invariant tests run in corpus replay mode and emit
506    /// AFL-`afl-showmap`-style files instead of running a campaign.
507    pub showmap: Option<ShowmapConfig>,
508    /// When set, fuzz/invariant tests replay one candidate input and record minimization facts.
509    pub fuzz_minimize: Option<FuzzMinimizeConfig>,
510    /// Run only fuzz and invariant tests.
511    pub fuzz_only: bool,
512    /// Replay persisted fuzz failures without running a new fuzz campaign.
513    pub fuzz_failure_replay: bool,
514    /// Validated explicit stateless fuzz failure to replay.
515    pub fuzz_input: Option<FuzzFailureReplayConfig>,
516
517    /// When set, run only the matching test and replay this artifact's concrete payload.
518    pub symbolic_artifact_replay: Option<SymbolicArtifactReplayConfig>,
519}
520
521impl<FEN: FoundryEvmNetwork> TestRunnerConfig<FEN> {
522    /// Reconfigures all fields using the given `config`.
523    /// This is for example used to override the configuration with inline config.
524    pub fn reconfigure_with(&mut self, config: Arc<Config>) {
525        debug_assert!(!Arc::ptr_eq(&self.config, &config));
526
527        self.sender = config.sender;
528        self.evm_opts.networks = config.networks;
529        self.hardfork = resolve_execution_spec::<EvmFactoryFor<FEN>>(
530            config.evm_version,
531            config.hardfork,
532            &mut self.evm_env,
533            ExecutionSpecContext::local_or_fork(self.fork_chain_id, self.fork_hardfork),
534            None,
535        );
536        self.spec_id = self.evm_env.spec;
537        self.isolation = config.isolate;
538        // `line_coverage`, `debug`, `decode_internal` and `record_all_steps` are Forge-specific
539        // and not present in the config.
540        // TODO: `self.evm_opts` and `self.evm_env` are only partially reconfigured.
541        self.evm_opts.always_use_create_2_factory = config.always_use_create_2_factory;
542        self.evm_opts.no_fork_bal = config.no_fork_bal;
543        self.evm_opts.fork_prefetch = config.fork_prefetch;
544        self.evm_opts.fork_state_by_number = config.fork_state_by_number;
545        self.config = config;
546    }
547
548    /// Configures the given executor with this configuration.
549    pub fn configure_executor(&self, executor: &mut Executor<FEN>) {
550        debug_assert!(
551            executor.backend().networks().has_same_execution_profile(&self.evm_opts.networks)
552        );
553        let inspector = executor.inspector_mut();
554        if let Some(cheatcodes) = inspector.cheatcodes.as_mut() {
555            let mut config = cheatcodes.core.config.clone_with(&self.config, self.evm_opts.clone());
556            config.isolate = self.isolation;
557            cheatcodes.core.config = Arc::new(config);
558        }
559        inspector.tracing_requirements(self.trace_requirements());
560        inspector.collect_line_coverage(self.line_coverage);
561        inspector.enable_isolation(self.isolation);
562        inspector.enable_edgecov_opcode(self.edgecov_opcode());
563        inspector.fork_prefetch(self.evm_opts.fork_prefetch);
564        executor.set_spec_id(self.spec_id);
565        executor.set_legacy_assertions(self.config.legacy_assertions);
566    }
567
568    /// Creates a new executor with this configuration.
569    pub fn executor(
570        &self,
571        known_contracts: ContractsByArtifact,
572        analysis: Arc<solar::sema::Compiler>,
573        artifact_id: &ArtifactId,
574        db: Backend<FEN>,
575    ) -> Executor<FEN> {
576        let mut cheats_config = CheatsConfig::new(
577            &self.config,
578            self.evm_opts.clone(),
579            Some(known_contracts),
580            Some(artifact_id.clone()),
581            false,
582        );
583        cheats_config.isolate = self.isolation;
584        let cheats_config = Arc::new(cheats_config);
585        let mut executor = self
586            .executor_builder
587            .clone()
588            .inspectors(|stack| {
589                stack
590                    .logs(self.config.live_logs)
591                    .cheatcodes(cheats_config)
592                    .trace_requirements(self.trace_requirements())
593                    .line_coverage(self.line_coverage)
594                    .enable_isolation(self.isolation)
595                    .fork_prefetch(self.evm_opts.fork_prefetch)
596                    .create2_deployer(self.evm_opts.create2_deployer)
597                    .set_analysis(analysis)
598            })
599            .spec_id(self.spec_id)
600            .gas_limit(self.evm_opts.gas_limit())
601            .legacy_assertions(self.config.legacy_assertions)
602            .build(self.evm_env, self.tx.clone(), db, self.evm_opts.networks);
603        executor.inspector_mut().enable_edgecov_opcode(self.edgecov_opcode());
604        executor
605    }
606
607    /// Whether test executors run the compiler-instrumented `EDGECOV` and `CMPLOG` opcodes, so
608    /// that instrumented artifacts also deploy and run outside coverage-guided campaigns.
609    fn edgecov_opcode(&self) -> bool {
610        self.config.fuzz.corpus.collect_instrumented_edges()
611            || self.config.invariant.corpus.collect_instrumented_edges()
612    }
613
614    fn trace_requirements(&self) -> TraceRequirements {
615        TraceRequirements::none()
616            .with_debug_recording(self.debug)
617            .with_decode_internal(self.decode_internal)
618            .with_all_steps(self.record_all_steps)
619            .with_verbosity(self.config.tracing.verbosity.max(self.evm_opts.verbosity))
620    }
621}
622
623/// Builder used for instantiating the multi-contract runner
624#[derive(Clone)]
625#[must_use = "builders do nothing unless you call `build` on them"]
626pub struct MultiContractRunnerBuilder {
627    /// The address which will be used to deploy the initial contracts and send all
628    /// transactions
629    pub sender: Option<Address>,
630    /// The initial balance for each one of the deployed smart contracts
631    pub initial_balance: U256,
632    /// Project config.
633    pub config: Arc<Config>,
634    /// Parsed inline configuration.
635    pub inline_config: Arc<InlineConfig>,
636    /// Whether or not to collect line coverage info
637    pub line_coverage: bool,
638    /// Whether or not to collect debug info
639    pub debug: bool,
640    /// Whether to enable steps tracking in the tracer.
641    pub decode_internal: InternalTraceMode,
642    /// Whether to record every opcode step without debugger snapshots.
643    pub record_all_steps: bool,
644    /// Whether to enable call isolation
645    pub isolation: bool,
646    /// Whether to exit early on test failure.
647    pub fail_fast: bool,
648    /// Multi-network pass configuration.
649    pub multi_network: MultiNetworkConfig,
650    /// Showmap replay mode (CLI-only, off by default).
651    pub showmap: Option<ShowmapConfig>,
652    /// Run only fuzz and invariant tests.
653    pub fuzz_only: bool,
654    /// Replay persisted fuzz failures without running a new fuzz campaign.
655    pub fuzz_failure_replay: bool,
656    /// Validated explicit stateless fuzz failure to replay.
657    pub fuzz_input: Option<FuzzFailureReplayConfig>,
658    /// Symbolic artifact replay mode (CLI-only, off by default).
659    pub symbolic_artifact_replay: Option<SymbolicArtifactReplayConfig>,
660    /// Whether the configured CREATE2 deployer is available in the execution environment.
661    pub create2_deployer_available: Option<bool>,
662}
663
664impl MultiContractRunnerBuilder {
665    fn create2_deployer_available<FEN: FoundryEvmNetwork>(
666        &self,
667        evm_opts: &EvmOpts,
668        backend: &Backend<FEN>,
669    ) -> bool {
670        self.create2_deployer_available.unwrap_or_else(|| {
671            !backend.is_forked_mode()
672                && evm_opts.fork_url.is_none()
673                && evm_opts.create2_deployer == foundry_evm::constants::DEFAULT_CREATE2_DEPLOYER
674        })
675    }
676
677    pub fn new(config: Arc<Config>, inline_config: Arc<InlineConfig>) -> Self {
678        Self {
679            config,
680            inline_config,
681            sender: None,
682            initial_balance: U256::ZERO,
683            line_coverage: false,
684            debug: false,
685            isolation: false,
686            decode_internal: Default::default(),
687            record_all_steps: false,
688            fail_fast: false,
689            multi_network: Default::default(),
690            showmap: None,
691            fuzz_only: false,
692            fuzz_failure_replay: false,
693            fuzz_input: None,
694            symbolic_artifact_replay: None,
695            create2_deployer_available: None,
696        }
697    }
698
699    pub const fn with_create2_deployer_available(mut self, available: bool) -> Self {
700        self.create2_deployer_available = Some(available);
701        self
702    }
703
704    pub fn with_showmap(mut self, showmap: Option<ShowmapConfig>) -> Self {
705        self.showmap = showmap;
706        self
707    }
708
709    pub const fn with_fuzz_only(mut self, fuzz_only: bool) -> Self {
710        self.fuzz_only = fuzz_only;
711        self
712    }
713
714    pub const fn with_fuzz_failure_replay(mut self, fuzz_failure_replay: bool) -> Self {
715        self.fuzz_failure_replay = fuzz_failure_replay;
716        self
717    }
718
719    pub fn with_fuzz_input(mut self, fuzz_input: Option<FuzzFailureReplayConfig>) -> Self {
720        self.fuzz_input = fuzz_input;
721        self
722    }
723
724    pub fn with_symbolic_artifact_replay(
725        mut self,
726        replay: Option<SymbolicArtifactReplayConfig>,
727    ) -> Self {
728        self.symbolic_artifact_replay = replay;
729        self
730    }
731
732    pub const fn sender(mut self, sender: Address) -> Self {
733        self.sender = Some(sender);
734        self
735    }
736
737    pub const fn initial_balance(mut self, initial_balance: U256) -> Self {
738        self.initial_balance = initial_balance;
739        self
740    }
741
742    pub const fn set_coverage(mut self, enable: bool) -> Self {
743        self.line_coverage = enable;
744        self
745    }
746
747    pub const fn set_debug(mut self, enable: bool) -> Self {
748        self.debug = enable;
749        self
750    }
751
752    pub const fn set_decode_internal(mut self, mode: InternalTraceMode) -> Self {
753        self.decode_internal = mode;
754        self
755    }
756
757    pub const fn set_record_all_steps(mut self, enable: bool) -> Self {
758        self.record_all_steps = enable;
759        self
760    }
761
762    pub fn with_multi_network(mut self, multi_network: MultiNetworkConfig) -> Self {
763        self.multi_network = multi_network;
764        self
765    }
766
767    pub const fn fail_fast(mut self, fail_fast: bool) -> Self {
768        self.fail_fast = fail_fast;
769        self
770    }
771
772    pub const fn enable_isolation(mut self, enable: bool) -> Self {
773        self.isolation = enable;
774        self
775    }
776
777    /// Given an EVM, proceeds to return a runner which is able to execute all tests
778    /// against that evm
779    pub fn build<FEN: FoundryEvmNetwork, C: Compiler<CompilerContract = Contract>>(
780        self,
781        output: &ProjectCompileOutput,
782        mut evm_env: EvmEnvFor<FEN>,
783        tx: TransactionRequestFor<FEN>,
784        evm_opts: EvmOpts,
785        backend: Backend<FEN>,
786        executor_builder: ExecutorBuilder<FEN>,
787    ) -> Result<MultiContractRunner<FEN>> {
788        let root = &self.config.root;
789        let coverage_artifacts = self
790            .line_coverage
791            .then(|| self.config.coverage_cache_path())
792            .flatten()
793            .map(|path| path.join("artifacts"));
794        let artifact_id = |mut id: ArtifactId| {
795            // Artifact-path cheatcodes retain the logical output paths even when coverage
796            // compilation stores its unoptimized artifacts in a separate cache.
797            if let Some(coverage_artifacts) = &coverage_artifacts
798                && let Ok(path) = id.path.strip_prefix(coverage_artifacts)
799            {
800                id.path = self.config.out.join(path);
801            }
802            id.with_stripped_file_prefixes(root).with_slashed_paths()
803        };
804        let contracts = output.artifact_ids().map(|(id, v)| (artifact_id(id), v)).collect();
805        let linker = Linker::new(root, contracts);
806
807        // Build revert decoder from ABIs of all artifacts.
808        let abis = linker
809            .contracts
810            .values()
811            .filter_map(|contract| contract.abi.as_ref().map(|abi| abi.borrow()));
812        let revert_decoder = RevertDecoder::new().with_abis(abis);
813
814        let configured_libraries = self.config.libraries_with_remappings()?;
815        let create2 = if self.create2_deployer_available(&evm_opts, &backend) {
816            match linker.link_with_create2_detailed(
817                configured_libraries.clone(),
818                evm_opts.create2_deployer,
819                self.config.create2_library_salt,
820                linker.contracts.keys(),
821            ) {
822                Ok(output) => Some(output),
823                Err(LinkerError::CyclicDependency) => None,
824                Err(err) => return Err(err.into()),
825            }
826        } else {
827            None
828        };
829        let (
830            DetailedLinkOutput {
831                output: LinkOutput { libraries, library_addresses, libs_to_deploy },
832                artifact_libraries,
833                ..
834            },
835            library_deployment,
836        ) = match create2 {
837            Some(output) => {
838                let deployment = if output.output.libs_to_deploy.is_empty() {
839                    LibraryDeployment::Nonce
840                } else {
841                    LibraryDeployment::Create2 {
842                        deployer: evm_opts.create2_deployer,
843                        salt: self.config.create2_library_salt,
844                    }
845                };
846                (output, deployment)
847            }
848            None => (
849                linker.link_with_nonce_or_address_detailed(
850                    configured_libraries,
851                    LIBRARY_DEPLOYER,
852                    0,
853                    linker.contracts.keys(),
854                )?,
855                LibraryDeployment::Nonce,
856            ),
857        };
858
859        let linked_contracts = linker
860            .get_linked_artifacts_cow_with_artifact_libraries(&libraries, &artifact_libraries)?;
861        let inline_config = self.inline_config;
862
863        // Collect every deployable test contract: a test contract with a default constructor.
864        let mut deployable_contracts = DeployableContracts::default();
865        let test_matcher = TestFunctionMatcher::new(
866            &self.config,
867            &inline_config,
868            self.symbolic_artifact_replay.as_ref(),
869        );
870        let empty_filter = EmptyTestFilter::default();
871        let resolver = Resolver::new(&linker);
872        for (id, contract) in linked_contracts.iter() {
873            let Some(abi) = contract.abi.as_ref() else { continue };
874            if abi.constructor.as_ref().is_some_and(|c| !c.inputs.is_empty())
875                || !test_matcher.matches_contract(&empty_filter, id, abi)
876            {
877                continue;
878            }
879            linker.ensure_linked(contract, id)?;
880            let Some(bytecode) =
881                contract.get_bytecode_bytes().map(|b| b.into_owned()).filter(|b| !b.is_empty())
882            else {
883                continue;
884            };
885            let artifact_libraries = artifact_libraries.get(id).unwrap_or(&libraries);
886            let library_addresses = resolver.linked_library_addresses(id, artifact_libraries)?;
887            deployable_contracts.insert(
888                id.clone(),
889                TestContract { abi: abi.clone().into_owned(), bytecode, library_addresses },
890            );
891        }
892
893        // Initialize and configure the solar compiler.
894        let mut analysis = solar::sema::Compiler::new(
895            solar::interface::Session::builder().with_stderr_emitter().build(),
896        );
897        let dcx = analysis.dcx_mut();
898        dcx.set_emitter(Box::new(
899            solar::interface::diagnostics::HumanEmitter::stderr(Default::default())
900                .source_map(Some(dcx.source_map().unwrap())),
901        ));
902        dcx.set_flags_mut(|f| f.track_diagnostics = false);
903
904        // Populate solar's global context by parsing and lowering every source, not only the
905        // sources that this build recompiled. Struct definitions, fuzz dictionary literals, enum
906        // bounds and ERC-7201 namespaces must not depend on the build history.
907        analysis.enter_mut(|compiler| -> Result<()> {
908            let mut pcx = compiler.parse();
909            configure_pcx_from_compile_output(&mut pcx, &self.config, output)?;
910            pcx.parse();
911            let _ = compiler.lower_asts();
912            Ok(())
913        })?;
914
915        // Create known contracts from linked contracts and storage layout information (if any),
916        // including ERC-7201 namespaces. A filtered build can keep cached artifacts of other
917        // compiler profiles without layouts, so they take the layout of the same contract from
918        // another profile, which only differs in AST ids.
919        let contract_key = |id: &ArtifactId| {
920            (id.source.clone(), id.version.clone(), id.name.split('.').next().unwrap().to_owned())
921        };
922        let layouts = output
923            .artifact_ids()
924            .filter_map(|(id, artifact)| {
925                Some((contract_key(&id), artifact.storage_layout.as_ref()?))
926            })
927            .collect::<HashMap<_, _>>();
928        let storage_layouts = output.artifact_ids().filter_map(|(id, artifact)| {
929            let layout = artifact
930                .storage_layout
931                .as_ref()
932                .or_else(|| layouts.get(&contract_key(&id)).copied())?;
933            Some((artifact_id(id), layout.clone()))
934        });
935        let storage_layouts =
936            namespaced_storage::extend_storage_layouts(&mut analysis, root, storage_layouts);
937        let known_contracts = ContractsByArtifactBuilder::new(linked_contracts)
938            .with_storage_layouts(storage_layouts)
939            .build();
940        let analysis = Arc::new(analysis);
941
942        // Enum variant counts used to constrain fuzzed enum inputs to valid values.
943        let enum_bounds = EnumBounds::collect(&analysis);
944        let literals = |max_literals| {
945            LiteralsDictionary::new(
946                Some(analysis.clone()),
947                Some(self.config.project_paths()),
948                max_literals,
949            )
950        };
951        let fuzz_max_literals = self.config.fuzz.dictionary.max_fuzz_dictionary_literals;
952        let invariant_max_literals = self.config.invariant.dictionary.max_fuzz_dictionary_literals;
953        let fuzz_literals = literals(fuzz_max_literals);
954        let invariant_literals = if invariant_max_literals == fuzz_max_literals {
955            fuzz_literals.clone()
956        } else {
957            literals(invariant_max_literals)
958        };
959
960        let fork_context = backend.fork().map(|fork| fork.context());
961        let fork_chain_id = fork_context.map(|context| context.source_chain_id);
962        let fork_hardfork = fork_context.and_then(|context| context.hardfork);
963        let hardfork = resolve_execution_spec::<EvmFactoryFor<FEN>>(
964            self.config.evm_version,
965            self.config.hardfork,
966            &mut evm_env,
967            ExecutionSpecContext::local_or_fork(fork_chain_id, fork_hardfork),
968            None,
969        );
970        let spec_id = evm_env.spec;
971
972        Ok(MultiContractRunner {
973            contracts: deployable_contracts,
974            revert_decoder,
975            known_contracts,
976            libs_to_deploy,
977            library_addresses,
978            library_deployment,
979            libraries,
980            analysis,
981            fuzz_literals,
982            invariant_literals,
983            enum_bounds,
984
985            tcfg: TestRunnerConfig {
986                evm_opts,
987                executor_builder,
988                evm_env,
989                tx,
990                spec_id,
991                hardfork,
992                fork_chain_id,
993                fork_hardfork,
994                sender: self.sender.unwrap_or(self.config.sender),
995                line_coverage: self.line_coverage,
996                debug: self.debug,
997                decode_internal: self.decode_internal,
998                record_all_steps: self.record_all_steps,
999                inline_config,
1000                isolation: self.isolation,
1001                early_exit: EarlyExit::new(self.fail_fast),
1002                multi_network: self.multi_network,
1003                showmap: self.showmap,
1004                fuzz_minimize: None,
1005                fuzz_only: self.fuzz_only,
1006                fuzz_failure_replay: self.fuzz_failure_replay,
1007                fuzz_input: self.fuzz_input,
1008                symbolic_artifact_replay: self.symbolic_artifact_replay,
1009                config: self.config,
1010            },
1011
1012            backend,
1013        })
1014    }
1015}
1016
1017#[derive(Clone, Copy)]
1018pub(crate) struct TestFunctionMatcher<'a> {
1019    config: &'a Config,
1020    inline_config: &'a InlineConfig,
1021    symbolic_artifact_replay: Option<&'a SymbolicArtifactReplayConfig>,
1022}
1023
1024impl<'a> TestFunctionMatcher<'a> {
1025    pub(crate) const fn new(
1026        config: &'a Config,
1027        inline_config: &'a InlineConfig,
1028        symbolic_artifact_replay: Option<&'a SymbolicArtifactReplayConfig>,
1029    ) -> Self {
1030        Self { config, inline_config, symbolic_artifact_replay }
1031    }
1032
1033    fn symbolic_tests_enabled(&self, contract_id: &str) -> bool {
1034        self.symbolic_artifact_replay.is_some_and(|artifact| {
1035            artifact.artifact.kind == SymbolicCounterexampleArtifactKind::SingleCall
1036        }) || self.inline_config.contract_symbolic_enabled(
1037            &self.config.profile,
1038            contract_id,
1039            self.config.symbolic.enabled,
1040        )
1041    }
1042
1043    pub(crate) fn test_function_kind(
1044        &self,
1045        contract_id: &str,
1046        func: &Function,
1047        generated_symbolic_regression: bool,
1048    ) -> TestFunctionKind {
1049        if generated_symbolic_regression && !func.name.starts_with("test_regression_") {
1050            return TestFunctionKind::Unknown;
1051        }
1052
1053        TestFunctionKind::classify(
1054            func.name.as_str(),
1055            !func.inputs.is_empty(),
1056            self.symbolic_tests_enabled(contract_id),
1057        )
1058    }
1059
1060    /// Returns the functions of `abi` accepted by `keep`, which is given the contract identifier,
1061    /// the function and its classification.
1062    pub(crate) fn test_functions(
1063        self,
1064        contract_id: String,
1065        abi: &JsonAbi,
1066        mut keep: impl FnMut(&str, &Function, TestFunctionKind) -> bool,
1067    ) -> impl Iterator<Item = &Function> {
1068        let generated_symbolic_regression = is_generated_symbolic_regression_contract(abi);
1069        abi.functions().filter(move |func| {
1070            let kind = self.test_function_kind(&contract_id, func, generated_symbolic_regression);
1071            keep(&contract_id, func, kind)
1072        })
1073    }
1074
1075    /// Returns the test functions of `abi` that match `filter`.
1076    fn matching_test_functions<'b>(
1077        self,
1078        filter: &dyn TestFilter,
1079        id: &ArtifactId,
1080        abi: &'b JsonAbi,
1081    ) -> impl Iterator<Item = &'b Function> {
1082        self.test_functions(id.identifier(), abi, move |contract_id, func, kind| {
1083            filter.matches_test_function_kind_in_contract(contract_id, func, kind)
1084        })
1085    }
1086
1087    /// Counts the fuzz test functions and runnable invariant campaign anchors of `abi` that
1088    /// match `filter` in the current network pass.
1089    pub(crate) fn count_fuzz_engine_targets(
1090        &self,
1091        filter: &dyn TestFilter,
1092        id: &ArtifactId,
1093        abi: &JsonAbi,
1094        multi_network: &MultiNetworkConfig,
1095    ) -> (usize, usize) {
1096        let contract_name = id.identifier();
1097        let matches_network_pass = |func: &Function| {
1098            function_matches_network_pass(
1099                &multi_network.all_override_networks,
1100                multi_network.pass_network.as_ref(),
1101                self.inline_config.network_for(&self.config.profile, &contract_name, &func.name),
1102            )
1103        };
1104        let fuzz = self
1105            .test_functions(contract_name.clone(), abi, |contract_id, func, kind| {
1106                kind.is_fuzz_test()
1107                    && filter.matches_test_function_kind_in_contract(contract_id, func, kind)
1108                    && matches_network_pass(func)
1109            })
1110            .count();
1111        let invariant = count_runnable_invariant_campaign_anchors(
1112            abi,
1113            filter,
1114            InvariantCampaignScope {
1115                config: self.config,
1116                inline_config: self.inline_config,
1117                contract_name: &contract_name,
1118                all_override_networks: &multi_network.all_override_networks,
1119                pass_network: multi_network.pass_network.as_ref(),
1120            },
1121        );
1122        (fuzz, invariant)
1123    }
1124
1125    pub(crate) fn matches_contract(
1126        &self,
1127        filter: &dyn TestFilter,
1128        id: &ArtifactId,
1129        abi: &JsonAbi,
1130    ) -> bool {
1131        external_artifact_is_test_eligible(&id.build_id)
1132            && filter.matches_path(&id.source)
1133            && filter.matches_contract(&id.name)
1134            && self.matching_test_functions(filter, id, abi).next().is_some()
1135    }
1136}
1137
1138pub(crate) fn is_generated_symbolic_regression_contract(abi: &JsonAbi) -> bool {
1139    abi.functions().any(|func| func.name == SYMBOLIC_REGRESSION_MARKER && func.inputs.is_empty())
1140}
1141
1142#[cfg(test)]
1143mod tests {
1144    use super::*;
1145    use foundry_evm::core::evm::EthEvmNetwork;
1146
1147    fn abi_with_functions(functions: &[&str]) -> JsonAbi {
1148        let mut abi = JsonAbi::new();
1149        for function in functions {
1150            let function = Function::parse(function).unwrap();
1151            abi.functions.entry(function.name.clone()).or_default().push(function);
1152        }
1153        abi
1154    }
1155
1156    #[test]
1157    fn generated_symbolic_regression_detection_uses_marker() {
1158        let user_suffix_abi = abi_with_functions(&["test_fails()"]);
1159        assert!(!is_generated_symbolic_regression_contract(&user_suffix_abi));
1160
1161        let generated_abi =
1162            abi_with_functions(&[&format!("{SYMBOLIC_REGRESSION_MARKER}()"), "test_fails()"]);
1163        assert!(is_generated_symbolic_regression_contract(&generated_abi));
1164    }
1165
1166    #[test]
1167    fn create2_deployer_availability_default_is_conservative() {
1168        let config = Arc::new(Config::default());
1169        let builder = MultiContractRunnerBuilder::new(config, Arc::new(InlineConfig::new()));
1170        let mut evm_opts = EvmOpts::default();
1171        let backend =
1172            Backend::<EthEvmNetwork>::spawn(None, evm_opts.local_evm_env::<EthEvmNetwork>())
1173                .unwrap();
1174        assert!(builder.create2_deployer_available(&evm_opts, &backend));
1175
1176        evm_opts.fork_url = Some("http://localhost:8545".into());
1177        assert!(!builder.create2_deployer_available(&evm_opts, &backend));
1178        evm_opts.fork_url = None;
1179        evm_opts.create2_deployer = Address::ZERO;
1180        assert!(!builder.create2_deployer_available(&evm_opts, &backend));
1181        assert!(
1182            builder
1183                .with_create2_deployer_available(true)
1184                .create2_deployer_available(&evm_opts, &backend)
1185        );
1186    }
1187}