Skip to main content

forge/cmd/test/
mod.rs

1use super::{fuzz::FuzzRunArgs, watch::WatchArgs};
2use crate::{
3    MultiContractRunner, MultiContractRunnerBuilder, brutalizer,
4    decode::decode_console_logs,
5    gas_report::GasReport,
6    multi_runner::{
7        FuzzFailureReplayConfig, FuzzMinimizeConfig, FuzzMinimizeEdgeIndices, FuzzMinimizeMode,
8        FuzzMinimizeObservation, MultiNetworkConfig, ShowmapConfig, SymbolicArtifactReplayConfig,
9        TestFunctionMatcher, is_generated_symbolic_regression_contract,
10    },
11    mutation::{MutationRunConfig, run_mutation_testing},
12    result::{
13        SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA, SuiteResult, SymbolicCounterexampleArtifact,
14        SymbolicReplayStatus, TestKind, TestKindReport, TestOutcome, TestResult, TestStatus,
15    },
16    runner::{effective_test_function_kind, inline_config_for},
17    symbolic_regression::{
18        SymbolicRegression, SymbolicRegressionConfig, attach_symbolic_regressions_to_suites,
19        collect_symbolic_artifacts_from_suites, emit_symbolic_regressions,
20    },
21    traces::{
22        CallTraceDecoder, CallTraceDecoderBuilder, InternalTraceMode, TraceKind,
23        debug::{ContractSources, DebugTraceIdentifier},
24        decode_trace_arena, folded_stack_trace,
25        identifier::SignaturesIdentifier,
26        render_trace_arena_inner, speedscope,
27    },
28    workspace,
29};
30use alloy_json_abi::JsonAbi;
31use alloy_network::TransactionBuilder;
32use alloy_primitives::U256;
33use chrono::Utc;
34use clap::{Parser, ValueEnum, ValueHint};
35use dialoguer::{Select, console::Term};
36use evm2::interpreter::opcode::OpCode;
37use eyre::{Context, OptionExt, Result, bail};
38use foundry_cli::{
39    opts::{BuildOpts, EvmArgs, GlobalArgs, TracingArgs},
40    utils::{self, FoundryPathExt, LoadConfig},
41};
42use foundry_common::{
43    ContractsByArtifact, EmptyTestFilter, TestFilter, TestFunctionExt, TestFunctionKind,
44    compile::{ProjectCompiler, compile_abi_project_cached},
45    external_compiler::is_external_artifact,
46    fs,
47    fs::canonicalize_path,
48    sh_status, sh_warn, shell,
49};
50use foundry_compilers::{
51    Artifact, ArtifactId, Graph, ProjectCompileOutput,
52    artifacts::{
53        BytecodeObject, ConfigurableContractArtifact, Libraries, Source, ast::NodeType,
54        output_selection::ContractOutputSelection,
55    },
56    compilers::{
57        Language,
58        multi::{MultiCompiler, MultiCompilerLanguage, MultiCompilerParser},
59    },
60    utils::source_files_iter,
61};
62use foundry_config::{
63    Config, InlineConfig, InvariantDepthMode, InvariantWorkers, figment,
64    figment::{
65        Metadata, Profile, Provider,
66        value::{Dict, Map, Value},
67    },
68    filter::GlobMatcher,
69    fs_permissions::FsAccessPermission,
70};
71use foundry_debugger::{DebuggerBuilder, ensure_dump_dir};
72use foundry_evm::{
73    backend::Backend,
74    core::evm::{EthEvmNetwork, EvmFactoryFor, FoundryEvmNetwork, TempoEvmNetwork},
75    executors::{ExecutorBuilder, ShowmapDomain},
76    fuzz::{BaseCounterExample, BasicTxDetails, CounterExample},
77    opts::{EvmOpts, ExecutionSpecContext, resolve_execution_spec},
78    traces::{
79        backtrace::BacktraceBuilder, identifier::TraceIdentifiers, prune_trace_depth,
80        trace_arena_at_depth,
81    },
82};
83use foundry_evm_networks::NetworkVariant;
84use foundry_tui::tui_mode;
85use quick_junit::{NonSuccessKind, Report, TestCase, TestCaseStatus, TestSuite};
86use rand::Rng;
87use regex::Regex;
88use solar::ast::{ContractKind as SolarContractKind, ItemKind};
89use std::{
90    collections::{BTreeMap, BTreeSet, HashSet},
91    fmt::Write,
92    path::{Path, PathBuf},
93    sync::{Arc, Mutex, mpsc::channel},
94    time::{Duration, Instant},
95};
96use tempfile::TempDir;
97use yansi::Paint;
98
99#[cfg(feature = "base")]
100use foundry_evm::core::evm::BaseEvmNetwork;
101
102#[cfg(feature = "monad")]
103use foundry_evm::core::evm::MonadEvmNetwork;
104
105#[cfg(feature = "optimism")]
106use foundry_evm::core::evm::OpEvmNetwork;
107
108mod evm_profile_server;
109mod filter;
110mod summary;
111use filter::RerunFailures;
112use summary::{TestSummaryReport, format_invariant_metrics_table};
113
114pub use filter::{FilterArgs, ProjectPathsAwareFilter, RerunFailure};
115
116const DEBUGGER_MATCHING_TESTS_DISPLAY_LIMIT: usize = 12;
117const AUTO_FUZZ_FAILURE_DIR: &str = "fuzz";
118const AUTO_CORPUS_DIR: &str = "corpus";
119
120// Loads project's figment and merges the build cli arguments into it
121foundry_config::merge_impl_figment_convert!(TestArgs, build, evm);
122
123fn validate_showmap_config(showmap: &ShowmapConfig) -> Result<()> {
124    for (kind, name) in [("approach", &showmap.approach), ("trial", &showmap.trial)] {
125        let path = Path::new(name);
126        if name.is_empty()
127            || path.is_absolute()
128            || path.components().count() != 1
129            || name.contains(['/', '\\'])
130            || matches!(name.as_str(), "." | "..")
131        {
132            bail!(
133                "invalid showmap {kind} `{name}`: expected a single file-name component without path separators"
134            );
135        }
136    }
137    Ok(())
138}
139
140/// Compiled runners for every network pass of a `forge fuzz` minimization command.
141pub(crate) struct FuzzMinimizeReplaySession {
142    filter: ProjectPathsAwareFilter,
143    passes: Vec<FuzzMinimizeReplayPass>,
144}
145
146type FuzzMinimizeReplay = Box<dyn Fn(&ProjectPathsAwareFilter, FuzzMinimizeConfig) -> Result<()>>;
147
148struct FuzzMinimizeReplayPass {
149    target_count: usize,
150    replay: FuzzMinimizeReplay,
151}
152
153impl FuzzMinimizeReplaySession {
154    pub(crate) fn replay(
155        &self,
156        sequence: Vec<BasicTxDetails>,
157        evm_edge_indices: FuzzMinimizeEdgeIndices,
158        mode: FuzzMinimizeMode,
159    ) -> Result<Vec<FuzzMinimizeObservation>> {
160        let observations = Arc::new(Mutex::new(Vec::new()));
161        let fuzz_minimize = FuzzMinimizeConfig {
162            input: sequence.into(),
163            mode,
164            evm_edge_indices,
165            observations: observations.clone(),
166        };
167        for pass in self.passes.iter().filter(|pass| pass.target_count > 0) {
168            (pass.replay)(&self.filter, fuzz_minimize.clone())?;
169        }
170        let observations = observations
171            .lock()
172            .map_err(|_| eyre::eyre!("minimize observations lock poisoned"))?
173            .clone();
174        if observations.is_empty() {
175            bail!("fuzz minimization replay produced no observation for the matched test");
176        }
177        Ok(observations)
178    }
179}
180
181fn fuzz_minimize_pass<FEN: FoundryEvmNetwork>(
182    runner: MultiContractRunner<FEN>,
183    filter: &ProjectPathsAwareFilter,
184) -> FuzzMinimizeReplayPass {
185    let target_count = count_fuzz_minimize_targets(&runner, filter);
186    let replay = move |filter: &ProjectPathsAwareFilter, fuzz_minimize| -> Result<()> {
187        let mut runner = runner.clone();
188        // Release forks that this replay creates when the replay ends.
189        runner.backend = runner.backend.clone_with_fork_scope()?;
190        runner.tcfg.fuzz_minimize = Some(fuzz_minimize);
191        for (suite, suite_result) in runner.test_collect(filter)? {
192            for (test, test_result) in suite_result.test_results {
193                if test_result.status.is_failure() {
194                    bail!(
195                        "fuzz minimization replay failed for {suite}::{test}: {}",
196                        test_result.reason.as_deref().unwrap_or("unknown error")
197                    );
198                }
199            }
200        }
201        Ok(())
202    };
203    FuzzMinimizeReplayPass { target_count, replay: Box::new(replay) }
204}
205
206fn count_fuzz_minimize_targets<FEN: FoundryEvmNetwork>(
207    runner: &MultiContractRunner<FEN>,
208    filter: &dyn TestFilter,
209) -> usize {
210    let matcher = runner.test_function_matcher();
211    runner
212        .matching_contracts(filter)
213        .map(|(id, contract)| {
214            let (fuzz, invariant) = matcher.count_fuzz_engine_targets(
215                filter,
216                id,
217                &contract.abi,
218                &runner.tcfg.multi_network,
219            );
220            fuzz + invariant
221        })
222        .sum()
223}
224
225/// Evaluates `$body` with `$fen` bound to the concrete network type selected by `$evm_opts`.
226macro_rules! dispatch_network {
227    ($evm_opts:expr, | $fen:ident | $body:expr) => {
228        match $evm_opts.networks.execution_network() {
229            #[cfg(feature = "base")]
230            NetworkVariant::Base => {
231                type $fen = BaseEvmNetwork;
232                $body
233            }
234            NetworkVariant::Tempo => {
235                type $fen = TempoEvmNetwork;
236                $body
237            }
238            #[cfg(feature = "monad")]
239            NetworkVariant::Monad => {
240                type $fen = MonadEvmNetwork;
241                $body
242            }
243            #[cfg(feature = "optimism")]
244            NetworkVariant::Optimism => {
245                type $fen = OpEvmNetwork;
246                $body
247            }
248            NetworkVariant::Ethereum => {
249                type $fen = EthEvmNetwork;
250                $body
251            }
252        }
253    };
254}
255
256/// Output format for EVM execution profiles.
257#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, ValueEnum)]
258pub enum EvmProfileFormat {
259    /// Speedscope format, opens in speedscope.app.
260    #[default]
261    Speedscope,
262}
263
264#[derive(Clone, Copy, Debug, PartialEq, Eq)]
265enum TraceOutputKind {
266    Flamegraph,
267    Flamechart,
268    EvmProfile(EvmProfileFormat),
269}
270
271impl TraceOutputKind {
272    const fn label(self) -> &'static str {
273        match self {
274            Self::Flamegraph => "flamegraph",
275            Self::Flamechart => "flamechart",
276            Self::EvmProfile(_) => "EVM profile",
277        }
278    }
279}
280
281/// CLI mirror of `foundry_evm::executors::ShowmapDomain`.
282#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, ValueEnum)]
283#[clap(rename_all = "lowercase")]
284pub enum ShowmapDomainArg {
285    #[default]
286    Evm,
287    Sancov,
288    Both,
289}
290
291impl From<ShowmapDomainArg> for ShowmapDomain {
292    fn from(d: ShowmapDomainArg) -> Self {
293        match d {
294            ShowmapDomainArg::Evm => Self::Evm,
295            ShowmapDomainArg::Sancov => Self::Sancov,
296            ShowmapDomainArg::Both => Self::Both,
297        }
298    }
299}
300
301#[derive(Clone, Debug)]
302pub(crate) struct TestExecutionOptions {
303    pub(crate) coverage: bool,
304    pub(crate) decode_internal: InternalTraceMode,
305    pub(crate) multi_network: MultiNetworkConfig,
306    pub(crate) fuzz_input: Option<FuzzFailureReplayConfig>,
307    pub(crate) replay_symbolic_artifact: Option<SymbolicArtifactReplayConfig>,
308    pub(crate) inline_config: Arc<InlineConfig>,
309    pub(crate) selected_sources: BTreeSet<PathBuf>,
310}
311
312impl TestExecutionOptions {
313    pub(crate) fn default_run(inline_config: Arc<InlineConfig>) -> Self {
314        Self {
315            coverage: false,
316            decode_internal: InternalTraceMode::None,
317            multi_network: MultiNetworkConfig::default(),
318            fuzz_input: None,
319            replay_symbolic_artifact: None,
320            inline_config,
321            selected_sources: BTreeSet::new(),
322        }
323    }
324
325    pub(crate) fn coverage(inline_config: Arc<InlineConfig>) -> Self {
326        Self { coverage: true, ..Self::default_run(inline_config) }
327    }
328}
329
330/// Config and EVM options for one network pass of a multi-network run.
331struct NetworkPass {
332    config: Config,
333    evm_opts: EvmOpts,
334    multi_network: MultiNetworkConfig,
335}
336
337/// Splits a run into the default network pass and one override pass per annotated network.
338fn network_passes(
339    config: Config,
340    evm_opts: EvmOpts,
341    override_networks: &[NetworkVariant],
342) -> (NetworkPass, Vec<NetworkPass>) {
343    let multi_network = |pass_network| MultiNetworkConfig {
344        all_override_networks: override_networks.to_vec(),
345        pass_network,
346    };
347    let override_passes = override_networks
348        .iter()
349        .map(|&network| {
350            let mut evm_opts = evm_opts.clone();
351            evm_opts.set_explicit_network(network);
352            let mut config = config.clone();
353            config.networks = evm_opts.networks;
354            NetworkPass { config, evm_opts, multi_network: multi_network(Some(network)) }
355        })
356        .collect();
357    (NetworkPass { config, evm_opts, multi_network: multi_network(None) }, override_passes)
358}
359
360struct CompiledTestProject {
361    project_root: PathBuf,
362    config: Config,
363    evm_opts: EvmOpts,
364    output: ProjectCompileOutput,
365    filter: ProjectPathsAwareFilter,
366    inline_config: Arc<InlineConfig>,
367    replay_symbolic_artifact: Option<SymbolicArtifactReplayConfig>,
368    selected_sources: BTreeSet<PathBuf>,
369    /// Keeps the brutalized copy of the project alive while its tests run.
370    _brutalized_workspace: Option<TempDir>,
371}
372
373/// Shared campaign arguments for `forge fuzz run`.
374#[derive(Clone, Debug, Parser)]
375#[command(next_help_heading = "Campaign options")]
376pub struct CampaignArgs {
377    /// Number of runs to execute for each fuzz or invariant campaign.
378    #[arg(long, value_name = "RUNS")]
379    pub runs: Option<u64>,
380
381    /// Campaign-global timeout in seconds.
382    #[arg(long, value_name = "TIMEOUT")]
383    pub timeout: Option<u32>,
384
385    /// Set seed used to generate randomness during fuzz runs.
386    #[arg(long)]
387    pub seed: Option<U256>,
388
389    /// Number of calls executed to try to break invariants in one run.
390    #[arg(long, value_name = "DEPTH")]
391    pub depth: Option<u32>,
392
393    /// Minimum sampled invariant depth when `--depth-mode random` is active.
394    #[arg(long, value_name = "DEPTH")]
395    pub min_depth: Option<u32>,
396
397    /// How invariant run depth is selected.
398    #[arg(long, value_name = "fixed|random")]
399    pub depth_mode: Option<InvariantDepthMode>,
400
401    /// Number of workers to use for invariant test campaigns, or `auto` to derive from `--jobs`.
402    #[arg(long, value_name = "WORKERS")]
403    pub workers: Option<InvariantWorkers>,
404
405    /// Directory for fuzz and invariant corpus persistence.
406    #[arg(long, value_name = "PATH", value_hint = ValueHint::DirPath)]
407    pub corpus_dir: Option<PathBuf>,
408
409    /// Percent of calldata generated from the dictionary.
410    #[arg(long, value_name = "PERCENT")]
411    pub dictionary_weight: Option<u32>,
412
413    /// Maximum dictionary addresses, or `max`.
414    #[arg(long, value_name = "N|max")]
415    pub dictionary_addresses: Option<String>,
416
417    /// Maximum dictionary values, or `max`.
418    #[arg(long, value_name = "N|max")]
419    pub dictionary_values: Option<String>,
420
421    /// Maximum dictionary literals, or `max`.
422    #[arg(long, value_name = "N|max")]
423    pub dictionary_literals: Option<String>,
424
425    /// Percent chance that coverage-guided fuzzing generates fresh input instead of mutating
426    /// corpus input.
427    #[arg(long, value_name = "PERCENT")]
428    pub corpus_random_sequence_weight: Option<u32>,
429
430    /// Percent chance that fuzzed payable calls carry non-zero msg.value.
431    #[arg(long, value_name = "PERCENT")]
432    pub payable_value_weight: Option<u32>,
433
434    /// Corpus mutation weight for splice.
435    #[arg(long, value_name = "WEIGHT")]
436    pub mutation_weight_splice: Option<u32>,
437
438    /// Corpus mutation weight for repeat.
439    #[arg(long, value_name = "WEIGHT")]
440    pub mutation_weight_repeat: Option<u32>,
441
442    /// Corpus mutation weight for interleave.
443    #[arg(long, value_name = "WEIGHT")]
444    pub mutation_weight_interleave: Option<u32>,
445
446    /// Corpus mutation weight for prefix replacement.
447    #[arg(long, value_name = "WEIGHT")]
448    pub mutation_weight_prefix: Option<u32>,
449
450    /// Corpus mutation weight for suffix replacement.
451    #[arg(long, value_name = "WEIGHT")]
452    pub mutation_weight_suffix: Option<u32>,
453
454    /// Corpus mutation weight for ABI argument mutation.
455    #[arg(long, value_name = "WEIGHT")]
456    pub mutation_weight_abi: Option<u32>,
457
458    /// Corpus mutation weight for comparison-operand mutation.
459    #[arg(long, value_name = "WEIGHT")]
460    pub mutation_weight_cmp: Option<u32>,
461
462    /// Directory for fuzz branch frontier artifacts.
463    #[arg(long, value_name = "PATH", value_hint = ValueHint::DirPath)]
464    pub frontier_dir: Option<PathBuf>,
465
466    /// Maximum number of fuzz branch frontier records to write per test.
467    #[arg(long, value_name = "COUNT")]
468    pub frontier_limit: Option<usize>,
469}
470
471/// CLI arguments for `forge test`.
472#[derive(Clone, Debug, Default, Parser)]
473#[command(next_help_heading = "Test options")]
474pub struct TestArgs {
475    /// Internal mode used by `forge fuzz` to run only fuzz and invariant tests.
476    #[arg(skip)]
477    fuzz_only: bool,
478
479    /// Internal mode used by `forge fuzz run` to default the fuzz corpus dir.
480    #[arg(skip)]
481    auto_fuzz_corpus: bool,
482
483    /// Internal showmap/replay override used by `forge fuzz replay`.
484    #[arg(skip)]
485    pub(crate) showmap_override: Option<ShowmapConfig>,
486
487    /// Internal mode used by `forge fuzz replay` to replay persisted fuzz failures.
488    #[arg(skip)]
489    pub(crate) fuzz_failure_replay: bool,
490
491    /// Internal override used by `forge fuzz run --runs` for invariant campaigns.
492    #[arg(skip)]
493    pub(crate) invariant_runs_override: Option<u64>,
494
495    /// Internal override used by `forge fuzz run --timeout` for invariant campaigns.
496    #[arg(skip)]
497    pub(crate) invariant_timeout_override: Option<u32>,
498
499    // Include global options for users of this struct.
500    #[command(flatten)]
501    pub global: GlobalArgs,
502
503    /// The contract file you want to test, it's a shortcut for --match-path.
504    #[arg(value_hint = ValueHint::FilePath)]
505    pub path: Option<GlobMatcher>,
506
507    /// Run a single test in the debugger.
508    ///
509    /// The matching test will be opened in the debugger regardless of the outcome of the test.
510    ///
511    /// If the matching test is a fuzz test, then it will open the debugger on the first failure
512    /// case. If the fuzz test does not fail, it will open the debugger on the last fuzz case.
513    #[arg(long, conflicts_with_all = ["flamegraph", "flamechart", "evm_profile", "decode_internal", "rerun"])]
514    debug: bool,
515
516    /// Generate a flamegraph for a single test. Implies `--decode-internal`.
517    ///
518    /// A flame graph is used to visualize which functions or operations within the smart contract
519    /// are consuming the most gas overall in a sorted manner.
520    #[arg(
521        long,
522        group = "trace_output",
523        conflicts_with_all = ["flamechart", "evm_profile", "json", "junit", "list"]
524    )]
525    flamegraph: bool,
526
527    /// Generate a flamechart for a single test. Implies `--decode-internal`.
528    ///
529    /// A flame chart shows the gas usage over time, illustrating when each function is
530    /// called (execution order) and how much gas it consumes at each point in the timeline.
531    #[arg(
532        long,
533        group = "trace_output",
534        conflicts_with_all = ["flamegraph", "evm_profile", "json", "junit", "list"]
535    )]
536    flamechart: bool,
537
538    /// Generate an execution profile for a single test.
539    ///
540    /// Creates a profile where each EVM call is recorded with gas consumption.
541    /// Opens the profile in speedscope.app unless `--no-open` is passed.
542    /// Implies `--decode-internal`.
543    #[arg(
544        long,
545        value_name = "FORMAT",
546        num_args = 0..=1,
547        default_missing_value = "speedscope",
548        value_enum,
549        group = "trace_output",
550        conflicts_with_all = ["flamegraph", "flamechart", "json", "junit", "list"]
551    )]
552    evm_profile: Option<EvmProfileFormat>,
553
554    /// Don't open the generated profile, flamegraph, or flamechart.
555    ///
556    /// The profile is saved to disk without starting the local viewer server.
557    #[arg(long, requires = "trace_output")]
558    no_open: bool,
559
560    #[command(flatten)]
561    tracing: TracingArgs,
562
563    /// Writes a SolDB trace and source bundle to a directory.
564    ///
565    /// Read the bundle with SolDB tools, for example:
566    /// `soldb profile --trace-file <PATH>/trace.json --contracts <PATH>/contracts.json`.
567    #[arg(
568        long,
569        requires = "debug",
570        value_hint = ValueHint::DirPath,
571        value_name = "PATH"
572    )]
573    dump: Option<PathBuf>,
574
575    /// Print a gas report.
576    #[arg(long, env = "FORGE_GAS_REPORT")]
577    gas_report: bool,
578
579    /// Check gas snapshots against previous runs.
580    #[arg(long, env = "FORGE_SNAPSHOT_CHECK")]
581    gas_snapshot_check: Option<bool>,
582
583    /// Enable/disable recording of gas snapshot results.
584    #[arg(long, env = "FORGE_SNAPSHOT_EMIT")]
585    gas_snapshot_emit: Option<bool>,
586
587    /// Exit with code 0 even if a test fails.
588    #[arg(long, env = "FORGE_ALLOW_FAILURE")]
589    allow_failure: bool,
590
591    /// Suppress successful test traces and show only traces for failures.
592    #[arg(long, short, env = "FORGE_SUPPRESS_SUCCESSFUL_TRACES", help_heading = "Trace options")]
593    suppress_successful_traces: bool,
594
595    /// Write test results as JSON to the specified file.
596    #[arg(
597        long,
598        value_name = "PATH",
599        value_hint = ValueHint::FilePath,
600        conflicts_with = "list",
601        help_heading = "Display options"
602    )]
603    json_file: Option<PathBuf>,
604
605    /// Output test results as JUnit XML report.
606    #[arg(long, conflicts_with_all = ["quiet", "json", "gas_report", "summary", "list", "show_progress"], help_heading = "Display options")]
607    pub junit: bool,
608
609    /// Stop running tests after the first failure.
610    #[arg(long)]
611    pub fail_fast: bool,
612
613    /// The Etherscan (or equivalent) API key.
614    #[arg(long, env = "ETHERSCAN_API_KEY", value_name = "KEY")]
615    etherscan_api_key: Option<String>,
616
617    /// List tests instead of running them.
618    #[arg(long, short, conflicts_with_all = ["show_progress", "decode_internal", "summary"], help_heading = "Display options")]
619    list: bool,
620
621    /// Set seed used to generate randomness during your fuzz runs.
622    #[arg(long)]
623    pub fuzz_seed: Option<U256>,
624
625    #[arg(long, env = "FOUNDRY_FUZZ_RUNS", value_name = "RUNS")]
626    pub fuzz_runs: Option<u64>,
627
628    /// Number of workers to use for invariant test campaigns, or `auto` to derive from `--jobs`.
629    #[arg(long, env = "FOUNDRY_INVARIANT_WORKERS", value_name = "WORKERS")]
630    pub invariant_workers: Option<InvariantWorkers>,
631
632    /// Run only the fuzz case at the given 1-based run index.
633    #[arg(long, env = "FOUNDRY_FUZZ_RUN", value_name = "RUN")]
634    pub fuzz_run: Option<u32>,
635
636    /// Run the fuzz case from the given worker. Requires `--fuzz-run`.
637    #[arg(long, env = "FOUNDRY_FUZZ_WORKER", value_name = "WORKER", requires = "fuzz_run")]
638    pub fuzz_worker: Option<u32>,
639
640    /// Timeout for each fuzz run in seconds.
641    #[arg(long, env = "FOUNDRY_FUZZ_TIMEOUT", value_name = "TIMEOUT")]
642    pub fuzz_timeout: Option<u64>,
643
644    /// Percent of fuzz calldata generated from the dictionary.
645    #[arg(long, env = "FOUNDRY_FUZZ_DICTIONARY_WEIGHT", value_name = "PERCENT")]
646    pub fuzz_dictionary_weight: Option<u32>,
647
648    /// Maximum fuzz dictionary addresses, or `max`.
649    #[arg(long, env = "FOUNDRY_FUZZ_MAX_FUZZ_DICTIONARY_ADDRESSES", value_name = "N|max")]
650    pub fuzz_dictionary_addresses: Option<String>,
651
652    /// Maximum fuzz dictionary values, or `max`.
653    #[arg(long, env = "FOUNDRY_FUZZ_MAX_FUZZ_DICTIONARY_VALUES", value_name = "N|max")]
654    pub fuzz_dictionary_values: Option<String>,
655
656    /// Maximum fuzz dictionary literals, or `max`.
657    #[arg(long, env = "FOUNDRY_FUZZ_MAX_FUZZ_DICTIONARY_LITERALS", value_name = "N|max")]
658    pub fuzz_dictionary_literals: Option<String>,
659
660    /// Percent chance that coverage-guided fuzzing generates fresh input instead of mutating
661    /// corpus input.
662    #[arg(long, env = "FOUNDRY_FUZZ_CORPUS_RANDOM_SEQUENCE_WEIGHT", value_name = "PERCENT")]
663    pub fuzz_corpus_random_sequence_weight: Option<u32>,
664
665    /// Directory for fuzz corpus persistence.
666    #[arg(long, env = "FOUNDRY_FUZZ_CORPUS_DIR", value_name = "PATH", value_hint = ValueHint::DirPath)]
667    pub fuzz_corpus_dir: Option<PathBuf>,
668
669    /// Directory for fuzz branch frontier artifacts.
670    #[arg(long, env = "FOUNDRY_FUZZ_FRONTIER_DIR", value_name = "PATH", value_hint = ValueHint::DirPath)]
671    pub fuzz_frontier_dir: Option<PathBuf>,
672
673    /// Maximum number of fuzz branch frontier records to write per test.
674    #[arg(long, env = "FOUNDRY_FUZZ_FRONTIER_LIMIT", value_name = "COUNT")]
675    pub fuzz_frontier_limit: Option<usize>,
676
677    /// Percent chance that fuzzed payable calls carry non-zero msg.value.
678    #[arg(long, env = "FOUNDRY_FUZZ_PAYABLE_VALUE_WEIGHT", value_name = "PERCENT")]
679    pub fuzz_payable_value_weight: Option<u32>,
680
681    /// Corpus mutation weight for splice.
682    #[arg(long, env = "FOUNDRY_FUZZ_MUTATION_WEIGHT_SPLICE", value_name = "WEIGHT")]
683    pub fuzz_mutation_weight_splice: Option<u32>,
684
685    /// Corpus mutation weight for repeat.
686    #[arg(long, env = "FOUNDRY_FUZZ_MUTATION_WEIGHT_REPEAT", value_name = "WEIGHT")]
687    pub fuzz_mutation_weight_repeat: Option<u32>,
688
689    /// Corpus mutation weight for interleave.
690    #[arg(long, env = "FOUNDRY_FUZZ_MUTATION_WEIGHT_INTERLEAVE", value_name = "WEIGHT")]
691    pub fuzz_mutation_weight_interleave: Option<u32>,
692
693    /// Corpus mutation weight for prefix replacement.
694    #[arg(long, env = "FOUNDRY_FUZZ_MUTATION_WEIGHT_PREFIX", value_name = "WEIGHT")]
695    pub fuzz_mutation_weight_prefix: Option<u32>,
696
697    /// Corpus mutation weight for suffix replacement.
698    #[arg(long, env = "FOUNDRY_FUZZ_MUTATION_WEIGHT_SUFFIX", value_name = "WEIGHT")]
699    pub fuzz_mutation_weight_suffix: Option<u32>,
700
701    /// Corpus mutation weight for ABI argument mutation.
702    #[arg(long, env = "FOUNDRY_FUZZ_MUTATION_WEIGHT_ABI", value_name = "WEIGHT")]
703    pub fuzz_mutation_weight_abi: Option<u32>,
704
705    /// Corpus mutation weight for comparison-operand mutation.
706    #[arg(long, env = "FOUNDRY_FUZZ_MUTATION_WEIGHT_CMP", value_name = "WEIGHT")]
707    pub fuzz_mutation_weight_cmp: Option<u32>,
708
709    /// File to rerun fuzz failures from.
710    #[arg(
711        long,
712        value_name = "PATH",
713        value_hint = ValueHint::FilePath,
714        conflicts_with_all = ["fuzz_run", "list"]
715    )]
716    pub fuzz_input_file: Option<PathBuf>,
717
718    /// Number of calls executed to try to break invariants in one run.
719    #[arg(long, env = "FOUNDRY_INVARIANT_DEPTH", value_name = "DEPTH")]
720    pub invariant_depth: Option<u32>,
721
722    /// Minimum sampled invariant depth when `--invariant-depth-mode random` is active.
723    #[arg(long, env = "FOUNDRY_INVARIANT_MIN_DEPTH", value_name = "DEPTH")]
724    pub invariant_min_depth: Option<u32>,
725
726    /// How invariant run depth is selected.
727    #[arg(long, env = "FOUNDRY_INVARIANT_DEPTH_MODE", value_name = "fixed|random")]
728    pub invariant_depth_mode: Option<InvariantDepthMode>,
729
730    /// Percent of invariant calldata/senders generated from the dictionary.
731    #[arg(long, env = "FOUNDRY_INVARIANT_DICTIONARY_WEIGHT", value_name = "PERCENT")]
732    pub invariant_dictionary_weight: Option<u32>,
733
734    /// Maximum invariant dictionary addresses, or `max`.
735    #[arg(long, env = "FOUNDRY_INVARIANT_MAX_FUZZ_DICTIONARY_ADDRESSES", value_name = "N|max")]
736    pub invariant_dictionary_addresses: Option<String>,
737
738    /// Maximum invariant dictionary values, or `max`.
739    #[arg(long, env = "FOUNDRY_INVARIANT_MAX_FUZZ_DICTIONARY_VALUES", value_name = "N|max")]
740    pub invariant_dictionary_values: Option<String>,
741
742    /// Maximum invariant dictionary literals, or `max`.
743    #[arg(long, env = "FOUNDRY_INVARIANT_MAX_FUZZ_DICTIONARY_LITERALS", value_name = "N|max")]
744    pub invariant_dictionary_literals: Option<String>,
745
746    /// Percent chance that coverage-guided invariant fuzzing injects fresh calls while extending
747    /// corpus sequences.
748    #[arg(long, env = "FOUNDRY_INVARIANT_CORPUS_RANDOM_SEQUENCE_WEIGHT", value_name = "PERCENT")]
749    pub invariant_corpus_random_sequence_weight: Option<u32>,
750
751    /// Directory for invariant corpus persistence.
752    #[arg(long, env = "FOUNDRY_INVARIANT_CORPUS_DIR", value_name = "PATH", value_hint = ValueHint::DirPath)]
753    pub invariant_corpus_dir: Option<PathBuf>,
754
755    /// Directory for invariant branch frontier artifacts.
756    #[arg(long, env = "FOUNDRY_INVARIANT_FRONTIER_DIR", value_name = "PATH", value_hint = ValueHint::DirPath)]
757    pub invariant_frontier_dir: Option<PathBuf>,
758
759    /// Maximum number of invariant branch frontier records to write per campaign.
760    #[arg(long, env = "FOUNDRY_INVARIANT_FRONTIER_LIMIT", value_name = "COUNT")]
761    pub invariant_frontier_limit: Option<usize>,
762
763    /// Percent chance that fuzzed payable invariant calls carry non-zero msg.value.
764    #[arg(long, env = "FOUNDRY_INVARIANT_PAYABLE_VALUE_WEIGHT", value_name = "PERCENT")]
765    pub invariant_payable_value_weight: Option<u32>,
766
767    /// Corpus mutation weight for splice.
768    #[arg(long, env = "FOUNDRY_INVARIANT_MUTATION_WEIGHT_SPLICE", value_name = "WEIGHT")]
769    pub invariant_mutation_weight_splice: Option<u32>,
770
771    /// Corpus mutation weight for repeat.
772    #[arg(long, env = "FOUNDRY_INVARIANT_MUTATION_WEIGHT_REPEAT", value_name = "WEIGHT")]
773    pub invariant_mutation_weight_repeat: Option<u32>,
774
775    /// Corpus mutation weight for interleave.
776    #[arg(long, env = "FOUNDRY_INVARIANT_MUTATION_WEIGHT_INTERLEAVE", value_name = "WEIGHT")]
777    pub invariant_mutation_weight_interleave: Option<u32>,
778
779    /// Corpus mutation weight for prefix replacement.
780    #[arg(long, env = "FOUNDRY_INVARIANT_MUTATION_WEIGHT_PREFIX", value_name = "WEIGHT")]
781    pub invariant_mutation_weight_prefix: Option<u32>,
782
783    /// Corpus mutation weight for suffix replacement.
784    #[arg(long, env = "FOUNDRY_INVARIANT_MUTATION_WEIGHT_SUFFIX", value_name = "WEIGHT")]
785    pub invariant_mutation_weight_suffix: Option<u32>,
786
787    /// Corpus mutation weight for ABI argument mutation.
788    #[arg(long, env = "FOUNDRY_INVARIANT_MUTATION_WEIGHT_ABI", value_name = "WEIGHT")]
789    pub invariant_mutation_weight_abi: Option<u32>,
790
791    /// Corpus mutation weight for comparison-operand mutation.
792    #[arg(long, env = "FOUNDRY_INVARIANT_MUTATION_WEIGHT_CMP", value_name = "WEIGHT")]
793    pub invariant_mutation_weight_cmp: Option<u32>,
794
795    /// Run symbolic check*/prove*/invariant*/statefulFuzz* tests.
796    #[arg(long, env = "FOUNDRY_SYMBOLIC")]
797    pub symbolic: bool,
798
799    /// Replay a durable symbolic counterexample artifact emitted by `forge test --symbolic`.
800    #[arg(
801        long,
802        value_name = "PATH",
803        value_hint = ValueHint::FilePath,
804        conflicts_with_all = [
805            "debug",
806            "flamegraph",
807            "flamechart",
808            "rerun",
809            "fuzz_input_file",
810            "showmap_out",
811            "path",
812            "test_pattern",
813            "test_pattern_inverse",
814            "contract_pattern",
815            "contract_pattern_inverse",
816            "path_pattern",
817            "no-match-path",
818        ],
819    )]
820    pub replay_symbolic_artifact: Option<PathBuf>,
821
822    /// Emit Solidity regression tests for confirmed symbolic counterexamples.
823    #[arg(long, env = "FOUNDRY_SYMBOLIC_EMIT_REGRESSION")]
824    pub emit_regression: bool,
825
826    /// File or directory for generated symbolic regression tests.
827    #[arg(
828        long,
829        env = "FOUNDRY_SYMBOLIC_REGRESSION_OUT",
830        value_name = "PATH",
831        value_hint = ValueHint::AnyPath,
832        requires = "emit_regression"
833    )]
834    pub regression_out: Option<PathBuf>,
835
836    /// Overwrite existing generated symbolic regression tests.
837    #[arg(long, env = "FOUNDRY_SYMBOLIC_REGRESSION_OVERWRITE", requires = "emit_regression")]
838    pub regression_overwrite: bool,
839
840    /// Run fuzz tests symbolically and persist non-failing concrete inputs to the fuzz corpus.
841    #[arg(long, env = "FOUNDRY_SYMBOLIC_SEED_CORPUS")]
842    pub symbolic_seed_corpus: bool,
843
844    /// Run fuzz tests symbolically using existing fuzz corpus entries as path-priority hints.
845    #[arg(long, env = "FOUNDRY_SYMBOLIC_USE_FUZZ_CORPUS")]
846    pub symbolic_use_fuzz_corpus: bool,
847
848    /// Maximum number of fuzz corpus entries to import for one symbolic test.
849    #[arg(long, env = "FOUNDRY_SYMBOLIC_CORPUS_SEED_LIMIT", value_name = "COUNT")]
850    pub symbolic_corpus_seed_limit: Option<usize>,
851
852    /// Run targeted symbolic solving from existing fuzz branch frontier artifacts.
853    #[arg(long, env = "FOUNDRY_SYMBOLIC_USE_FUZZ_FRONTIERS")]
854    pub symbolic_use_fuzz_frontiers: bool,
855
856    /// Check invariants from imported stateful fuzz frontier prefixes before flipping comparisons.
857    /// Also enables invariant frontier seeding.
858    #[arg(long, env = "FOUNDRY_SYMBOLIC_CHECK_INVARIANT_FRONTIERS")]
859    pub symbolic_check_invariant_frontiers: bool,
860
861    /// Assist invariant campaigns with one bounded live symbolic worker.
862    #[arg(long, env = "FOUNDRY_SYMBOLIC_LIVE")]
863    pub symbolic_live: bool,
864
865    /// Maximum number of imported or live branch frontiers to try per test.
866    #[arg(long, env = "FOUNDRY_SYMBOLIC_FRONTIER_LIMIT", value_name = "COUNT")]
867    pub symbolic_frontier_limit: Option<usize>,
868
869    /// Comma-separated fuzz branch frontier artifact IDs to try.
870    #[arg(long, env = "FOUNDRY_SYMBOLIC_FRONTIER_IDS", value_name = "IDS", value_delimiter = ',')]
871    pub symbolic_frontier_ids: Option<Vec<u64>>,
872
873    /// Comma-separated fuzz branch frontier comparison PCs to try.
874    #[arg(long, env = "FOUNDRY_SYMBOLIC_FRONTIER_PCS", value_name = "PCS", value_delimiter = ',')]
875    pub symbolic_frontier_pcs: Option<Vec<usize>>,
876
877    /// Comma-separated fuzz branch frontier calldata selectors to try.
878    #[arg(
879        long,
880        env = "FOUNDRY_SYMBOLIC_FRONTIER_SELECTORS",
881        value_name = "SELECTORS",
882        value_delimiter = ','
883    )]
884    pub symbolic_frontier_selectors: Option<Vec<String>>,
885
886    /// Solver executable used for symbolic tests.
887    #[arg(long, env = "FOUNDRY_SYMBOLIC_SOLVER", value_name = "PATH_OR_NAME")]
888    pub symbolic_solver: Option<String>,
889
890    /// Exact solver command used for symbolic tests.
891    #[arg(long, env = "FOUNDRY_SYMBOLIC_SOLVER_COMMAND", value_name = "COMMAND")]
892    pub symbolic_solver_command: Option<String>,
893
894    /// Comma-separated SMT solver names or commands to race in parallel for symbolic tests.
895    #[arg(
896        long,
897        env = "FOUNDRY_SYMBOLIC_SOLVER_PORTFOLIO",
898        value_delimiter = ',',
899        value_name = "SOLVER_OR_COMMAND,..."
900    )]
901    pub symbolic_solver_portfolio: Option<Vec<String>>,
902
903    /// SMT solver timeout in seconds; also bounds symbolic invariant exploration.
904    #[arg(long, env = "FOUNDRY_SYMBOLIC_TIMEOUT", value_name = "SECONDS")]
905    pub symbolic_timeout: Option<u32>,
906
907    /// Halmos-compatible symbolic loop bound.
908    #[arg(long, env = "FOUNDRY_SYMBOLIC_LOOP", value_name = "N")]
909    pub symbolic_loop: Option<u32>,
910
911    /// Halmos-compatible symbolic execution depth alias.
912    #[arg(long, env = "FOUNDRY_SYMBOLIC_DEPTH", value_name = "N")]
913    pub symbolic_depth: Option<u32>,
914
915    /// Halmos-compatible symbolic path width alias.
916    #[arg(long, env = "FOUNDRY_SYMBOLIC_WIDTH", value_name = "N")]
917    pub symbolic_width: Option<u32>,
918
919    /// Maximum number of opcodes executed along a symbolic path.
920    #[arg(long, env = "FOUNDRY_SYMBOLIC_MAX_DEPTH", value_name = "N")]
921    pub symbolic_max_depth: Option<u32>,
922
923    /// Maximum number of symbolic paths to explore per test.
924    #[arg(long, env = "FOUNDRY_SYMBOLIC_MAX_PATHS", value_name = "N")]
925    pub symbolic_max_paths: Option<u32>,
926
927    /// Maximum number of calls in a bounded symbolic invariant sequence.
928    #[arg(long, env = "FOUNDRY_SYMBOLIC_INVARIANT_DEPTH", value_name = "N")]
929    pub symbolic_invariant_depth: Option<u32>,
930
931    /// Maximum number of solver queries per symbolic test.
932    #[arg(long, env = "FOUNDRY_SYMBOLIC_MAX_SOLVER_QUERIES", value_name = "N")]
933    pub symbolic_max_solver_queries: Option<u32>,
934
935    /// Default bounded length for symbolic dynamic ABI inputs.
936    #[arg(long, env = "FOUNDRY_SYMBOLIC_DEFAULT_DYNAMIC_LENGTH", value_name = "N")]
937    pub symbolic_default_dynamic_length: Option<u32>,
938
939    /// Maximum permitted bounded length for symbolic dynamic ABI inputs.
940    #[arg(long, env = "FOUNDRY_SYMBOLIC_MAX_DYNAMIC_LENGTH", value_name = "N")]
941    pub symbolic_max_dynamic_length: Option<u32>,
942
943    /// Per-dynamic-input symbolic lengths, applied in ABI traversal order.
944    #[arg(
945        long,
946        env = "FOUNDRY_SYMBOLIC_ARRAY_LENGTHS",
947        value_delimiter = ',',
948        value_name = "N,..."
949    )]
950    pub symbolic_array_lengths: Option<Vec<u32>>,
951
952    /// Maximum symbolic calldata size in bytes.
953    #[arg(long, env = "FOUNDRY_SYMBOLIC_MAX_CALLDATA_BYTES", value_name = "N")]
954    pub symbolic_max_calldata_bytes: Option<u32>,
955
956    /// Expand symbolic external call targets over known deployed contracts.
957    #[arg(long, env = "FOUNDRY_SYMBOLIC_CALL_TARGETS")]
958    pub symbolic_call_targets: bool,
959
960    /// Dump SMT-LIB queries issued by symbolic tests.
961    #[arg(long, env = "FOUNDRY_SYMBOLIC_DUMP_SMT")]
962    pub symbolic_dump_smt: bool,
963
964    /// Symbolic storage modelling mode.
965    #[arg(
966        long,
967        env = "FOUNDRY_SYMBOLIC_STORAGE_LAYOUT",
968        value_name = "solidity|generic|zero_init",
969        value_parser = ["solidity", "generic", "zero_init"]
970    )]
971    pub symbolic_storage_layout: Option<String>,
972
973    /// Show test execution progress.
974    #[arg(long, conflicts_with_all = ["quiet", "json"], help_heading = "Display options")]
975    pub show_progress: bool,
976
977    /// Re-run recorded test failures from last run.
978    /// If no failure recorded then regular test run is performed.
979    #[arg(long)]
980    pub rerun: bool,
981
982    /// Print the given opcodes in trace output, with their gas
983    /// cost and the storage slot and value, if available.
984    ///
985    /// Accepts a comma-separated list of opcode names, e.g.
986    /// `--opcodes SLOAD,MLOAD,SSTORE`. Names are in uppercase.
987    /// Requires `-vvvvv` to render.
988    #[arg(long, value_parser = parse_opcode, value_delimiter(','), conflicts_with_all = ["json", "junit", "list", "debug"])]
989    pub opcodes: Vec<OpCode>,
990
991    /// Print test summary table.
992    #[arg(long, help_heading = "Display options")]
993    pub summary: bool,
994
995    /// Print detailed test summary table.
996    #[arg(long, help_heading = "Display options", requires = "summary")]
997    pub detailed: bool,
998
999    /// Replay the persisted corpus and emit AFL-`afl-showmap`-style coverage
1000    /// files at the given output directory. Disables the regular fuzz/invariant
1001    /// campaign and skips unit tests.
1002    #[arg(
1003        long,
1004        value_name = "DIR",
1005        value_hint = ValueHint::DirPath,
1006        help_heading = "Showmap replay",
1007        conflicts_with_all = ["debug", "flamegraph", "flamechart", "evm_profile", "rerun", "fuzz_input_file", "gas_report"],
1008    )]
1009    pub showmap_out: Option<PathBuf>,
1010
1011    /// Emit one showmap file per corpus entry (default: one aggregated file per test).
1012    #[arg(long, help_heading = "Showmap replay", requires = "showmap_out")]
1013    pub showmap_per_input: bool,
1014
1015    /// Coverage domain(s) to dump.
1016    #[arg(
1017        long,
1018        value_enum,
1019        default_value_t = ShowmapDomainArg::Evm,
1020        help_heading = "Showmap replay",
1021        requires = "showmap_out",
1022    )]
1023    pub showmap_domain: ShowmapDomainArg,
1024
1025    /// Approach name (used as a subdirectory of `--showmap-out`).
1026    #[arg(
1027        long,
1028        default_value = "replay",
1029        help_heading = "Showmap replay",
1030        requires = "showmap_out"
1031    )]
1032    pub showmap_approach: String,
1033
1034    /// Trial identifier embedded in each showmap filename. Defaults to a unique
1035    /// `trial-<unix_nanos>` so reruns don't overwrite previous trials.
1036    #[arg(long, help_heading = "Showmap replay", requires = "showmap_out")]
1037    pub showmap_trial: Option<String>,
1038
1039    /// Override the corpus directory to replay (defaults to the per-test
1040    /// `corpus_dir` resolved from config).
1041    #[arg(
1042        long,
1043        value_name = "PATH",
1044        value_hint = ValueHint::DirPath,
1045        help_heading = "Showmap replay",
1046        requires = "showmap_out",
1047    )]
1048    pub showmap_corpus_dir: Option<PathBuf>,
1049
1050    /// Decode the storage layouts of contracts outside the local project in state diffs, by
1051    /// compiling the verified source a block explorer has for them.
1052    #[arg(long)]
1053    pub decode_external_storage: bool,
1054
1055    #[command(flatten)]
1056    filter: FilterArgs,
1057
1058    #[command(flatten)]
1059    evm: EvmArgs,
1060
1061    #[command(flatten)]
1062    pub build: BuildOpts,
1063
1064    #[command(flatten)]
1065    pub watch: WatchArgs,
1066
1067    /// Enable mutation testing.
1068    /// If passed with file paths, only those files will be tested.
1069    #[arg(long, num_args(0..), value_name = "PATH")]
1070    pub mutate: Option<Vec<PathBuf>>,
1071
1072    /// Specify which files to mutate with glob pattern matching.
1073    ///
1074    /// Mutually exclusive with passing explicit paths to `--mutate`; either
1075    /// supply paths to `--mutate` or use this glob filter, not both.
1076    #[arg(long, value_name = "PATTERN", requires = "mutate", conflicts_with = "mutate_contract")]
1077    pub mutate_path: Option<GlobMatcher>,
1078
1079    /// Only mutate contracts whose name matches the specified regex pattern.
1080    ///
1081    /// Mutually exclusive with `--mutate-path`.
1082    #[arg(long, value_name = "REGEX", requires = "mutate")]
1083    pub mutate_contract: Option<regex::Regex>,
1084
1085    /// Number of parallel workers for mutation testing.
1086    /// Defaults to the number of CPU cores.
1087    #[arg(long, value_name = "JOBS", requires = "mutate")]
1088    pub mutation_jobs: Option<usize>,
1089
1090    /// Best-effort per-mutant wall-clock timeout in seconds. Mutants that
1091    /// exceed it are recorded as "timed out" and cleanup continues in the
1092    /// background with bounded pending workers.
1093    ///
1094    /// Analogous to `--invariant-timeout` for invariant campaigns.
1095    #[arg(long, value_name = "TIMEOUT", requires = "mutate")]
1096    pub mutation_timeout: Option<u32>,
1097
1098    /// Override optimizer runs for mutation testing compile-and-test runs.
1099    #[arg(long, value_name = "RUNS", requires = "mutate")]
1100    pub mutation_optimizer_runs: Option<u32>,
1101
1102    /// Override via-ir for mutation testing compile-and-test runs.
1103    #[arg(long, default_missing_value = "true", num_args = 0..=1, requires = "mutate")]
1104    pub mutation_via_ir: Option<bool>,
1105
1106    /// Enable brutalization mode.
1107    ///
1108    /// Catches latent bugs that normal tests miss because the EVM initializes
1109    /// memory to zero and registers to clean values. Applies source-level
1110    /// sanitizers before compiling:
1111    ///
1112    /// - Dirties unused bits in sub-256-bit type casts (address, uint8, bytes4, etc.) to catch
1113    ///   assembly code that assumes clean upper bits when using legacy codegen. Via-IR may clean
1114    ///   these bits before inline assembly observes them.
1115    /// - Fills scratch space (0x00-0x3f) and memory beyond the free memory pointer with junk to
1116    ///   catch uninitialized memory reads
1117    /// - Misaligns the free memory pointer to catch word-alignment assumptions
1118    ///
1119    /// If `forge test` passes but `forge test --brutalize` fails, the code has
1120    /// a robustness issue that could manifest when called in a different context.
1121    // TODO: evaluate if we can relax the conflict with replay_symbolic_artifact
1122    #[arg(long, conflicts_with_all = ["mutate", "replay_symbolic_artifact"])]
1123    pub brutalize: bool,
1124
1125    /// Make every cheatcode that opens a network connection fail. `forge properties` sets it for
1126    /// generated tests.
1127    #[arg(long, hide = true)]
1128    pub no_network: bool,
1129
1130    /// Let inline config only lower fuzz and invariant runs, depth, and rejects and change a few
1131    /// settings that steer them. `forge properties` and `forge exploit` set it for generated
1132    /// tests.
1133    #[arg(long, hide = true)]
1134    pub restrict_inline_config: bool,
1135}
1136
1137impl TestArgs {
1138    pub async fn run(mut self) -> Result<TestOutcome> {
1139        trace!(target: "forge::test", "executing test command");
1140        self.compile_and_run().await
1141    }
1142
1143    pub(crate) fn ensure_mutation_mode_compatible(&self, coverage: bool) -> Result<()> {
1144        if self.mutate.is_none() {
1145            return Ok(());
1146        }
1147        // Mutation testing has bespoke orchestration that is not compatible with these modes.
1148        // Run this before compiling when the caller owns the build step so project errors do not
1149        // mask CLI conflicts.
1150        let conflicts = enabled_flags([
1151            (self.list, "--list"),
1152            (self.debug, "--debug"),
1153            (self.flamegraph, "--flamegraph"),
1154            (self.flamechart, "--flamechart"),
1155            (self.evm_profile.is_some(), "--evm-profile"),
1156            (self.junit, "--junit"),
1157            (self.json_file.is_some(), "--json-file"),
1158            (coverage, "coverage"),
1159            (self.showmap_out.is_some(), "--showmap-out"),
1160            (self.replay_symbolic_artifact.is_some(), "--replay-symbolic-artifact"),
1161        ]);
1162        if !conflicts.is_empty() {
1163            bail!(
1164                "`--mutate` cannot be combined with: {}. Re-run without those flags to use \
1165                 mutation testing.",
1166                conflicts.join(", ")
1167            );
1168        }
1169        Ok(())
1170    }
1171
1172    pub(crate) fn ensure_coverage_mode_compatible(&self) -> Result<()> {
1173        self.ensure_mutation_mode_compatible(true)?;
1174        let conflicts = enabled_flags([
1175            (shell::is_json(), "--json"),
1176            (self.junit, "--junit"),
1177            (self.json_file.is_some(), "--json-file"),
1178            (self.list, "--list"),
1179            (self.debug, "--debug"),
1180            (self.flamegraph, "--flamegraph"),
1181            (self.flamechart, "--flamechart"),
1182            (self.evm_profile.is_some(), "--evm-profile"),
1183            (self.showmap_out.is_some(), "--showmap-out"),
1184            (self.brutalize, "--brutalize"),
1185            (self.replay_symbolic_artifact.is_some(), "--replay-symbolic-artifact"),
1186        ]);
1187        if !conflicts.is_empty() {
1188            bail!(
1189                "`forge coverage` cannot be combined with: {}. Use `--report lcov` for an \
1190                 interoperable coverage report or `--report attribution` for per-test JSON \
1191                attribution.",
1192                conflicts.join(", ")
1193            );
1194        }
1195        Ok(())
1196    }
1197
1198    /// Builds a `ShowmapConfig` from the showmap CLI flags, if `--showmap-out` is set.
1199    fn showmap_config(&self) -> Result<Option<ShowmapConfig>> {
1200        let showmap = match (&self.showmap_override, &self.showmap_out) {
1201            (Some(showmap), _) => showmap.clone(),
1202            (None, Some(out_dir)) => ShowmapConfig {
1203                out_dir: out_dir.clone(),
1204                approach: self.showmap_approach.clone(),
1205                // Default trial id uses nanosecond precision so back-to-back invocations
1206                // don't collide and overwrite each other's output files.
1207                trial: self.showmap_trial.clone().unwrap_or_else(|| {
1208                    let ns = std::time::SystemTime::now()
1209                        .duration_since(std::time::UNIX_EPOCH)
1210                        .map(|d| d.as_nanos())
1211                        .unwrap_or(0);
1212                    format!("trial-{ns}")
1213                }),
1214                per_input: self.showmap_per_input,
1215                domain: self.showmap_domain.into(),
1216                corpus_dir: self.showmap_corpus_dir.clone(),
1217                emit_files: true,
1218            },
1219            (None, None) => return Ok(None),
1220        };
1221        validate_showmap_config(&showmap)?;
1222        Ok(Some(showmap))
1223    }
1224
1225    /// Restricts this test invocation to fuzz and invariant tests.
1226    pub(crate) const fn enable_fuzz_only(&mut self) {
1227        self.fuzz_only = true;
1228    }
1229
1230    /// Restricts this test invocation to fuzz and invariant tests and enables a default fuzz corpus
1231    /// dir after user config is loaded.
1232    pub(crate) const fn enable_fuzz_only_with_auto_fuzz_corpus(&mut self) {
1233        self.fuzz_only = true;
1234        self.auto_fuzz_corpus = true;
1235    }
1236
1237    fn apply_test_config_overrides(&self, config: &mut Config) {
1238        if self.auto_fuzz_corpus && config.fuzz.corpus.corpus_dir.is_none() {
1239            config.fuzz.corpus.corpus_dir = Some(match &config.fuzz.failure_persist_dir {
1240                Some(root) => root.join(AUTO_CORPUS_DIR),
1241                None => config.cache_path.join(AUTO_FUZZ_FAILURE_DIR).join(AUTO_CORPUS_DIR),
1242            });
1243        }
1244        // `--json` and `--junit` keep stdout for the report, so logs are captured into it.
1245        if shell::is_json() || self.junit {
1246            config.live_logs = false;
1247        }
1248        // The debugger labels slots from the layout, and symbolic execution learns the mapping
1249        // roots behind constant-folded slots from it.
1250        if (self.debug || config.symbolic.enabled)
1251            && !config.extra_output.contains(&ContractOutputSelection::StorageLayout)
1252        {
1253            config.extra_output.push(ContractOutputSelection::StorageLayout);
1254        }
1255        if self.debug {
1256            // Full build infos keep the sources the compiler saw, which dynamic test linking
1257            // rewrites in test files.
1258            if let Err(error) = config.enable_debug_build_info() {
1259                let _ = sh_warn!(
1260                    "the debugger may show source files that differ from the compiled ones: {error:#}"
1261                );
1262            }
1263        }
1264    }
1265
1266    /// Disables gas report sampling unless a gas report is requested, in which case isolation is
1267    /// enabled for more correct gas accounting.
1268    const fn apply_gas_report_overrides(&self, config: &mut Config, evm_opts: &mut EvmOpts) {
1269        if self.gas_report {
1270            evm_opts.isolate = true;
1271        } else {
1272            config.fuzz.gas_report_samples = 0;
1273            config.invariant.gas_report_samples = 0;
1274        }
1275    }
1276
1277    /// Overrides showmap config for callers that reuse replay mode without the
1278    /// `forge test --showmap-*` CLI flags.
1279    pub(crate) fn set_showmap_override(&mut self, showmap: ShowmapConfig) {
1280        self.showmap_override = Some(showmap);
1281    }
1282
1283    /// Sets replay-critical options for internal fuzz minimizer callers.
1284    pub(crate) fn set_fuzz_minimize_replay_options(
1285        &mut self,
1286        global: GlobalArgs,
1287        evm: EvmArgs,
1288        build: BuildOpts,
1289        filter: FilterArgs,
1290    ) {
1291        self.global = global;
1292        self.evm = evm;
1293        self.build = build;
1294        self.filter = filter;
1295    }
1296
1297    /// Replays persisted fuzz failures without running a new fuzz campaign.
1298    pub(crate) const fn enable_fuzz_failure_replay(&mut self) {
1299        self.fuzz_failure_replay = true;
1300    }
1301
1302    fn warn_unsupported_engine_flags(
1303        &self,
1304        output: &ProjectCompileOutput,
1305        config: &Config,
1306        inline_config: &InlineConfig,
1307        filter: &ProjectPathsAwareFilter,
1308        multi_network: &MultiNetworkConfig,
1309    ) -> Result<()> {
1310        if !self.fuzz_only {
1311            return Ok(());
1312        }
1313        let matcher = TestFunctionMatcher::new(config, inline_config, None);
1314        let (mut fuzz, mut invariant) = (0, 0);
1315        for (id, _, abi) in matching_test_contracts(output, config, &matcher, filter) {
1316            let (f, i) = matcher.count_fuzz_engine_targets(filter, &id, abi, multi_network);
1317            fuzz += f;
1318            invariant += i;
1319        }
1320        let unused: &[(bool, &str, &str)] = if fuzz == 0 && invariant > 0 {
1321            &[
1322                (
1323                    self.fuzz_frontier_dir.is_some() && self.invariant_frontier_dir.is_none(),
1324                    "--frontier-dir",
1325                    "fuzz",
1326                ),
1327                (
1328                    self.fuzz_frontier_limit.is_some() && self.invariant_frontier_limit.is_none(),
1329                    "--frontier-limit",
1330                    "fuzz",
1331                ),
1332                (self.fuzz_run.is_some(), "--fuzz-run", "fuzz"),
1333            ]
1334        } else if invariant == 0 && fuzz > 0 {
1335            &[
1336                (self.invariant_depth.is_some(), "--depth", "invariant"),
1337                (self.invariant_min_depth.is_some(), "--min-depth", "invariant"),
1338                (self.invariant_depth_mode.is_some(), "--depth-mode", "invariant"),
1339                (self.invariant_workers.is_some(), "--workers", "invariant"),
1340            ]
1341        } else {
1342            &[]
1343        };
1344        for (set, flag, engine) in unused {
1345            if *set {
1346                sh_warn!(
1347                    "`{flag}` only applies to {engine} tests; no matched {engine} tests were found."
1348                )?;
1349            }
1350        }
1351        Ok(())
1352    }
1353
1354    /// Warns about test contracts that the project compiles from outside its `src`, `test` and
1355    /// `script` directories and `libs`, since they no longer run as test suites.
1356    fn warn_skipped_test_suites(
1357        &self,
1358        output: &ProjectCompileOutput,
1359        config: &Config,
1360        inline_config: &InlineConfig,
1361        filter: &ProjectPathsAwareFilter,
1362    ) -> Result<()> {
1363        let matcher = TestFunctionMatcher::new(config, inline_config, None);
1364        let mut skipped = output
1365            .artifact_ids()
1366            .filter_map(|(id, artifact)| {
1367                let abi = artifact.abi.as_ref()?;
1368                let id = id.with_stripped_file_prefixes(&config.root);
1369                (filter.is_outside_test_roots(&id.source)
1370                    && filter.matches_contract(&id.name)
1371                    && is_runnable_test_contract(output, config, &id, artifact, abi)
1372                    && matcher
1373                        .test_functions(id.identifier(), abi, |contract_id, func, kind| {
1374                            filter.matches_test_function_kind_in_contract(contract_id, func, kind)
1375                        })
1376                        .next()
1377                        .is_some())
1378                .then(|| id.identifier())
1379            })
1380            .collect::<Vec<_>>();
1381        skipped.sort();
1382        skipped.dedup();
1383        if !skipped.is_empty() {
1384            sh_warn!(
1385                "Skipping test contracts outside the configured `src`, `test` and `script` directories:\n\t{}\n\
1386                 They are compiled because other files import them, but do not run as test \
1387                 suites. To run them, set `test` (currently `{}`) to a directory that contains \
1388                 them.",
1389                skipped.join("\n\t"),
1390                config.test.strip_prefix(&config.root).unwrap_or(&config.test).display(),
1391            )?;
1392        }
1393        Ok(())
1394    }
1395
1396    /// Builds the delegated `forge test` invocation for `forge fuzz run`.
1397    pub(crate) fn from_fuzz_run(args: FuzzRunArgs) -> Self {
1398        let campaign = args.campaign;
1399        Self {
1400            fuzz_only: true,
1401            global: args.global,
1402            path: args.path,
1403            gas_report: args.gas_report,
1404            allow_failure: args.allow_failure,
1405            junit: args.junit,
1406            fail_fast: args.fail_fast,
1407            etherscan_api_key: args.etherscan_api_key,
1408            list: args.list,
1409            fuzz_input_file: args.fuzz_input_file,
1410            show_progress: args.show_progress,
1411            rerun: args.rerun,
1412            showmap_out: args.showmap_out,
1413            showmap_per_input: args.showmap_per_input,
1414            showmap_domain: args.showmap_domain,
1415            showmap_approach: args.showmap_approach,
1416            showmap_trial: args.showmap_trial,
1417            showmap_corpus_dir: args.showmap_corpus_dir,
1418            filter: args.filter,
1419            evm: args.evm,
1420            build: args.build,
1421            fuzz_seed: campaign.seed,
1422            fuzz_runs: campaign.runs,
1423            invariant_runs_override: campaign.runs,
1424            fuzz_timeout: campaign.timeout.map(u64::from),
1425            invariant_timeout_override: campaign.timeout,
1426            fuzz_dictionary_weight: campaign.dictionary_weight,
1427            invariant_dictionary_weight: campaign.dictionary_weight,
1428            fuzz_dictionary_addresses: campaign.dictionary_addresses.clone(),
1429            invariant_dictionary_addresses: campaign.dictionary_addresses,
1430            fuzz_dictionary_values: campaign.dictionary_values.clone(),
1431            invariant_dictionary_values: campaign.dictionary_values,
1432            fuzz_dictionary_literals: campaign.dictionary_literals.clone(),
1433            invariant_dictionary_literals: campaign.dictionary_literals,
1434            fuzz_corpus_random_sequence_weight: campaign.corpus_random_sequence_weight,
1435            invariant_corpus_random_sequence_weight: campaign.corpus_random_sequence_weight,
1436            fuzz_corpus_dir: campaign.corpus_dir.clone(),
1437            invariant_corpus_dir: campaign.corpus_dir,
1438            fuzz_payable_value_weight: campaign.payable_value_weight,
1439            invariant_payable_value_weight: campaign.payable_value_weight,
1440            fuzz_mutation_weight_splice: campaign.mutation_weight_splice,
1441            invariant_mutation_weight_splice: campaign.mutation_weight_splice,
1442            fuzz_mutation_weight_repeat: campaign.mutation_weight_repeat,
1443            invariant_mutation_weight_repeat: campaign.mutation_weight_repeat,
1444            fuzz_mutation_weight_interleave: campaign.mutation_weight_interleave,
1445            invariant_mutation_weight_interleave: campaign.mutation_weight_interleave,
1446            fuzz_mutation_weight_prefix: campaign.mutation_weight_prefix,
1447            invariant_mutation_weight_prefix: campaign.mutation_weight_prefix,
1448            fuzz_mutation_weight_suffix: campaign.mutation_weight_suffix,
1449            invariant_mutation_weight_suffix: campaign.mutation_weight_suffix,
1450            fuzz_mutation_weight_abi: campaign.mutation_weight_abi,
1451            invariant_mutation_weight_abi: campaign.mutation_weight_abi,
1452            fuzz_mutation_weight_cmp: campaign.mutation_weight_cmp,
1453            invariant_mutation_weight_cmp: campaign.mutation_weight_cmp,
1454            fuzz_frontier_dir: campaign.frontier_dir.clone(),
1455            invariant_frontier_dir: campaign.frontier_dir,
1456            fuzz_frontier_limit: campaign.frontier_limit,
1457            invariant_frontier_limit: campaign.frontier_limit,
1458            invariant_depth: campaign.depth,
1459            invariant_min_depth: campaign.min_depth,
1460            invariant_depth_mode: campaign.depth_mode,
1461            invariant_workers: campaign.workers,
1462            ..Self::default()
1463        }
1464    }
1465
1466    fn load_symbolic_artifact_replay(&self) -> Result<Option<SymbolicArtifactReplayConfig>> {
1467        let Some(path) = &self.replay_symbolic_artifact else {
1468            return Ok(None);
1469        };
1470        if !self.filter.is_empty() || self.path.is_some() {
1471            bail!(
1472                "symbolic artifact mode cannot be combined with test selection filters; \
1473                 the artifact selects its original target"
1474            );
1475        }
1476
1477        let display = path.display();
1478        let value = fs::read_json_file::<serde_json::Value>(path)
1479            .wrap_err(format!("failed to read symbolic counterexample artifact {display}"))?;
1480        let schema_version =
1481            value.get("schema_version").and_then(serde_json::Value::as_u64).ok_or_else(|| {
1482                eyre::eyre!(
1483                    "symbolic counterexample artifact {display} is missing numeric schema_version"
1484                )
1485            })?;
1486        if schema_version != 1 {
1487            bail!(
1488                "unsupported symbolic counterexample artifact schema version {schema_version} in {display}"
1489            );
1490        }
1491        let schema = value.get("schema").and_then(serde_json::Value::as_str).ok_or_else(|| {
1492            eyre::eyre!("symbolic counterexample artifact {display} is missing string schema")
1493        })?;
1494        if schema != SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA {
1495            bail!("unsupported symbolic counterexample artifact schema `{schema}` in {display}");
1496        }
1497        let artifact = serde_json::from_value::<SymbolicCounterexampleArtifact>(value)
1498            .wrap_err(format!("failed to parse symbolic counterexample artifact {display}"))?;
1499        if artifact.calls.is_empty() {
1500            bail!("symbolic counterexample artifact {display} has no calls");
1501        }
1502        if artifact.replay.status != SymbolicReplayStatus::Confirmed {
1503            bail!(
1504                "symbolic counterexample artifact {display} replay status must be confirmed, got {:?}",
1505                artifact.replay.status,
1506            );
1507        }
1508        let contract = &artifact.test.contract;
1509        if !matches!(contract.rsplit_once(':'), Some((p, n)) if !p.is_empty() && !n.is_empty()) {
1510            bail!(
1511                "symbolic counterexample artifact {display} test.contract must be `path:Contract`, got `{contract}`"
1512            );
1513        }
1514        Ok(Some(SymbolicArtifactReplayConfig { artifact, path: path.clone() }))
1515    }
1516
1517    fn load_fuzz_input(
1518        &self,
1519        output: &ProjectCompileOutput,
1520        config: &Config,
1521        inline_config: &InlineConfig,
1522        filter: &ProjectPathsAwareFilter,
1523    ) -> Result<Option<FuzzFailureReplayConfig>> {
1524        let Some(path) = &self.fuzz_input_file else {
1525            return Ok(None);
1526        };
1527        let failure = fs::read_json_file::<BaseCounterExample>(path)?;
1528        let Some(selector) = failure.calldata.get(..4) else {
1529            bail!(
1530                "fuzz input file {} contains calldata shorter than a 4-byte selector",
1531                path.display()
1532            );
1533        };
1534        let targets =
1535            matching_fuzz_replay_targets(output, config, inline_config, filter, selector)?;
1536        let [(contract, test)] = targets.as_slice() else {
1537            if targets.is_empty() {
1538                bail!(
1539                    "fuzz input file {} does not match any selected stateless fuzz test",
1540                    path.display()
1541                );
1542            }
1543            bail!(
1544                "fuzz input file {} matches {} selected stateless fuzz tests; replay requires exactly one target",
1545                path.display(),
1546                targets.len()
1547            );
1548        };
1549        Ok(Some(FuzzFailureReplayConfig {
1550            failure: Arc::new(failure),
1551            contract: contract.clone(),
1552            test: test.clone(),
1553        }))
1554    }
1555
1556    /// Discovers test ABIs before contract and function filters select compilation roots.
1557    fn compile_test_abis(
1558        &self,
1559        config: &Config,
1560        test_filter: &ProjectPathsAwareFilter,
1561    ) -> Result<(BTreeSet<PathBuf>, ProjectCompileOutput)> {
1562        let mut project = config.create_project(config.cache, true)?;
1563        let sources = source_files_iter(&config.src, MultiCompilerLanguage::FILE_EXTENSIONS)
1564            .chain(
1565                // Preserve path-filter behavior for conventional test files while still
1566                // scanning non-test fixtures under the test root.
1567                source_files_iter(&config.test, MultiCompilerLanguage::FILE_EXTENSIONS)
1568                    .filter(|path| !path.is_sol_test() || test_filter.matches_path(path)),
1569            )
1570            .collect::<BTreeSet<_>>();
1571        // ABI discovery does not need dynamic linking, whose job-specific cache prevents
1572        // incremental ABI compilation after edits.
1573        let output = compile_abi_project_cached(
1574            &mut project,
1575            ProjectCompiler::new()
1576                .external_compilers(config)
1577                .files(sources.iter().cloned())
1578                .source_order_fallback(
1579                    source_files_iter(&config.src, MultiCompilerLanguage::FILE_EXTENSIONS).chain(
1580                        source_files_iter(&config.test, MultiCompilerLanguage::FILE_EXTENSIONS),
1581                    ),
1582                )
1583                .quiet(true),
1584        )?;
1585        if output.has_compiler_errors() {
1586            sh_println!("{output}")?;
1587            bail!("Compilation failed");
1588        }
1589
1590        Ok((sources, output))
1591    }
1592
1593    /// Returns a list of files that need to be compiled in order to run all the tests that match
1594    /// the given filter, and the inline config parsed from the ABI-only compilation when one was
1595    /// needed.
1596    ///
1597    /// For filtered runs, this includes all configured source roots, non-test fixture roots, and
1598    /// runnable tests that match the filter. Imported dependencies remain attached to those roots
1599    /// so compiler profiles and restrictions apply to the complete source graph.
1600    #[instrument(target = "forge::test", skip_all)]
1601    fn get_sources_to_compile(
1602        &self,
1603        config: &Config,
1604        test_filter: &ProjectPathsAwareFilter,
1605        symbolic_artifact_replay: Option<&SymbolicArtifactReplayConfig>,
1606    ) -> Result<(BTreeSet<PathBuf>, Option<Arc<InlineConfig>>)> {
1607        let src_files = || source_files_iter(&config.src, MultiCompilerLanguage::FILE_EXTENSIONS);
1608        let test_files = || source_files_iter(&config.test, MultiCompilerLanguage::FILE_EXTENSIONS);
1609
1610        // An empty filter doesn't filter out anything.
1611        // We can still optimize slightly by excluding scripts.
1612        if test_filter.is_empty() {
1613            return Ok((src_files().chain(test_files()).collect(), None));
1614        }
1615
1616        let (sources, output) = self.compile_test_abis(config, test_filter)?;
1617
1618        let inline_config = Arc::new(InlineConfig::new_parsed(&output, config)?);
1619        let test_matcher =
1620            TestFunctionMatcher::new(config, &inline_config, symbolic_artifact_replay);
1621        let paths = config.project_paths::<MultiCompilerLanguage>();
1622        let empty_filter = EmptyTestFilter::default();
1623        let filter_args = test_filter.args();
1624        let has_contract_or_test_filter = filter_args.test_pattern.is_some()
1625            || filter_args.test_pattern_inverse.is_some()
1626            || filter_args.contract_pattern.is_some()
1627            || filter_args.contract_pattern_inverse.is_some();
1628
1629        // `MultiContractRunner::build` strips the root prefix from artifact source paths so the
1630        // identifiers it constructs are project-relative. Match that here for the filter check
1631        // (notably for the `--rerun` failure list, which is persisted relative) but return the
1632        // original absolute source paths so downstream compilation can locate them.
1633        let files = output
1634            .artifact_ids()
1635            .filter_map(|(id, artifact)| artifact.abi.as_ref().map(|abi| (id, abi)))
1636            // Imported dependencies must remain attached to their roots so compilation restrictions
1637            // apply to the entire source graph instead of compiling dependencies with default
1638            // settings.
1639            .filter(|(id, _)| sources.contains(&id.source))
1640            .filter(|(id, abi)| {
1641                if id.source.starts_with(&paths.sources) {
1642                    return true;
1643                }
1644                if paths.is_script(&id.source) && !paths.is_test(&id.source) {
1645                    return false;
1646                }
1647                let stripped = id.clone().with_stripped_file_prefixes(&config.root);
1648                // ABI-only compilation can omit test functions with invalid bodies, so preserve the
1649                // existing filter behavior for conventional test files instead of treating them as
1650                // fixtures.
1651                if stripped.source.is_sol_test() {
1652                    return if has_contract_or_test_filter {
1653                        test_matcher.matches_contract(test_filter, &stripped, abi)
1654                    } else {
1655                        test_filter.matches_path(&stripped.source)
1656                    };
1657                }
1658                !test_matcher.matches_contract(&empty_filter, &stripped, abi)
1659                    || test_matcher.matches_contract(test_filter, &stripped, abi)
1660            })
1661            .map(|(id, _)| id.source)
1662            .collect();
1663        Ok((files, Some(inline_config)))
1664    }
1665
1666    /// Executes all the tests in the project.
1667    ///
1668    /// This will trigger the build process first. On success all test contracts that match the
1669    /// configured filter will be executed
1670    ///
1671    /// Returns the test results for all matching tests.
1672    pub async fn compile_and_run(&mut self) -> Result<TestOutcome> {
1673        self.ensure_mutation_mode_compatible(false)?;
1674        if let Some(dir) = &self.dump {
1675            ensure_dump_dir(dir)?;
1676        }
1677        let compiled = self.compile_project().await?;
1678        self.run_tests(
1679            &compiled.project_root,
1680            compiled.config,
1681            compiled.evm_opts,
1682            &compiled.output,
1683            &compiled.filter,
1684            TestExecutionOptions {
1685                replay_symbolic_artifact: compiled.replay_symbolic_artifact,
1686                selected_sources: compiled.selected_sources,
1687                ..TestExecutionOptions::default_run(compiled.inline_config)
1688            },
1689        )
1690        .await
1691    }
1692
1693    /// Copies the project into a temporary workspace, brutalizes its sources and rebases `config`
1694    /// onto that workspace.
1695    fn brutalize_workspace(&self, config: &mut Config) -> Result<TempDir> {
1696        let silent = shell::is_json();
1697        let temp_dir = TempDir::with_prefix("forge_brutalize_")?;
1698        let temp_path = temp_dir.path();
1699
1700        if config.via_ir && !silent {
1701            sh_warn!(
1702                "--brutalize value cast dirty-bits checks are ineffective with via-IR; memory and free-memory-pointer checks still apply"
1703            )?;
1704        }
1705        if !silent {
1706            sh_status!("Brutalizing source files...")?;
1707        }
1708        workspace::copy_project(config, temp_path)?;
1709        let count = brutalizer::brutalize_project(config, temp_path)?;
1710        if !silent {
1711            sh_status!("Brutalized {count} source files, compiling from temp workspace...")?;
1712        }
1713
1714        let test_failures_file = config.test_failures_file.clone();
1715        *config = workspace::rebase_config_paths(config, temp_path).sanitized();
1716        config.test_failures_file = test_failures_file;
1717        Ok(temp_dir)
1718    }
1719
1720    async fn compile_project(&mut self) -> Result<CompiledTestProject> {
1721        // Merge all configs.
1722        let (mut config, mut evm_opts) = self.load_config_and_evm_opts()?;
1723        evm_opts.no_network = self.no_network;
1724
1725        self.install_missing_dependencies(&mut config)?;
1726        // After the install, which can reload the config.
1727        config.restrict_inline_config = self.restrict_inline_config;
1728        let brutalized_workspace =
1729            if self.brutalize { Some(self.brutalize_workspace(&mut config)?) } else { None };
1730        let should_mutate = self.mutate.is_some();
1731        if should_mutate {
1732            // Force dyn test linking and cache usage for mutation testing after any config reload.
1733            config.dynamic_test_linking = true;
1734            config.cache = true;
1735            apply_mutation_compiler_overrides(&mut config);
1736        }
1737        self.apply_test_config_overrides(&mut config);
1738
1739        // Set up the project.
1740        let project = config.project()?;
1741        let project_root = project.paths.root.clone();
1742
1743        let replay_symbolic_artifact = self.load_symbolic_artifact_replay()?;
1744        let mut filter = self.filter(&config)?;
1745        if let Some(replay) = &replay_symbolic_artifact {
1746            let filter_args = filter.args_mut();
1747            filter_args.test_pattern_inverse = None;
1748            filter_args.contract_pattern_inverse = None;
1749            filter_args.path_pattern_inverse = None;
1750            let contract = replay.artifact.test.contract.as_str();
1751            let (path, contract) = contract.rsplit_once(':').unwrap_or(("", contract));
1752            filter_args.test_pattern =
1753                Some(Regex::new(&format!("^{}$", regex::escape(&replay.artifact.test.test)))?);
1754            filter_args.contract_pattern =
1755                Some(Regex::new(&format!("^{}$", regex::escape(contract)))?);
1756            if !path.is_empty() {
1757                filter_args.path_pattern = Some(globset::escape(path).parse::<GlobMatcher>()?);
1758            }
1759        }
1760        trace!(target: "forge::test", ?filter, "using filter");
1761
1762        let compiler = || {
1763            ProjectCompiler::new()
1764                .allow_linked_libraries(config.allow_linked_libraries || self.list)
1765                .external_compilers(&config)
1766                .dynamic_test_linking(config.dynamic_test_linking)
1767                .quiet(shell::is_json() || self.junit)
1768        };
1769        let (output, selected_sources, inline_config) = if self.list {
1770            let compiler = compiler().external_artifacts(false);
1771            // Only the ABI is needed to list tests, so skip the full compile when possible.
1772            let compiler = if filter.args().path_pattern.is_some()
1773                && config.extra_output.is_empty()
1774                && config.extra_output_files.is_empty()
1775                && !config.build_info
1776            {
1777                let files = project
1778                    .paths
1779                    .input_files_iter()
1780                    .filter(|path| filter.matches_path(path))
1781                    .collect::<Vec<_>>();
1782                if files.is_empty() { compiler } else { compiler.files(files) }
1783            } else {
1784                compiler
1785            };
1786            // Listing must not replace full artifacts with ABI-only ones, which later cached
1787            // builds would treat as fresh.
1788            let mut project = config.create_project(config.cache, true)?;
1789            (compile_abi_project_cached(&mut project, compiler)?, BTreeSet::new(), None)
1790        } else {
1791            let (files, inline_config) =
1792                self.get_sources_to_compile(&config, &filter, replay_symbolic_artifact.as_ref())?;
1793            let compile = |files: &BTreeSet<PathBuf>| {
1794                let compiler = if filter.is_empty() {
1795                    compiler()
1796                } else {
1797                    compiler().source_order_fallback(
1798                        source_files_iter(&config.src, MultiCompilerLanguage::FILE_EXTENSIONS)
1799                            .chain(source_files_iter(
1800                                &config.test,
1801                                MultiCompilerLanguage::FILE_EXTENSIONS,
1802                            )),
1803                    )
1804                };
1805                compiler.files(files.iter().cloned()).compile(&project)
1806            };
1807            let mut output = compile(&files);
1808            let mut reresolved = false;
1809            // A build without storage layouts keeps a cached profile that requested them, so its
1810            // artifacts are reused here without layouts. Delete them so they are recompiled.
1811            // Artifacts of sources without contracts never have layouts, and their AST has no
1812            // contract definition.
1813            while config.extra_output.contains(&ContractOutputSelection::StorageLayout)
1814                && let Ok(compiled) = &output
1815            {
1816                let mut stale = compiled
1817                    .cached_artifacts()
1818                    .iter()
1819                    .flat_map(|(source, artifacts)| {
1820                        artifacts.values().flatten().map(move |file| (source, file))
1821                    })
1822                    .filter(|(_, file)| {
1823                        file.artifact.storage_layout.is_none()
1824                            && file.artifact.ast.as_ref().is_none_or(|ast| {
1825                                ast.nodes
1826                                    .iter()
1827                                    .any(|node| node.node_type == NodeType::ContractDefinition)
1828                            })
1829                    })
1830                    .collect::<Vec<_>>();
1831                if stale.is_empty() {
1832                    break;
1833                }
1834                // Cached artifacts of other profiles are reused for every source in scope, but
1835                // only the profiles compiled from these roots are rewritten. Deleting any other
1836                // artifact would leave the cache pointing at a missing file, and every later build
1837                // would recompile. The roots are those of the compilation that produced the output,
1838                // which differ from `files` after a source order fallback.
1839                let graph = compiled.graph();
1840                let roots = graph
1841                    .source_files()
1842                    .map(|id| graph.node_path(id).to_path_buf())
1843                    .collect::<BTreeSet<_>>();
1844                let scope = Graph::<MultiCompilerParser>::resolve_sources(
1845                    &project.paths,
1846                    Source::read_all(&roots)?,
1847                )?
1848                .into_sources_by_version(&project)?
1849                .sources
1850                .into_values()
1851                .flatten()
1852                .flat_map(|(version, sources, (profile, _))| {
1853                    sources.into_iter().map(move |(path, _)| (path, version.clone(), profile))
1854                })
1855                .collect::<HashSet<_>>();
1856                // Resolving the roots again can pick another compiler version than the compilation
1857                // that produced the output, such as one it installed. The recompile would not
1858                // rewrite stale artifacts of the old version, so recompile once with the new
1859                // versions instead of deleting them.
1860                if !reresolved
1861                    && stale.iter().any(|(source, file)| {
1862                        !scope
1863                            .iter()
1864                            .any(|(path, version, _)| path == *source && *version == file.version)
1865                    })
1866                {
1867                    reresolved = true;
1868                    output = compile(&roots);
1869                    continue;
1870                }
1871                stale.retain(|(source, file)| {
1872                    scope.contains(&(
1873                        (*source).clone(),
1874                        file.version.clone(),
1875                        file.profile.as_str(),
1876                    ))
1877                });
1878                if stale.is_empty() {
1879                    break;
1880                }
1881                if !(shell::is_json() || self.junit) {
1882                    sh_status!("Recompiling cached artifacts without storage layouts...")?;
1883                }
1884                for (_, file) in stale {
1885                    fs::remove_file(&file.file)?;
1886                }
1887                output = compile(&roots);
1888            }
1889            let output = if should_mutate {
1890                output.wrap_err(
1891                    "Mutation testing compiler profile failed to compile before applying mutations",
1892                )?
1893            } else {
1894                output?
1895            };
1896            (output, files, inline_config)
1897        };
1898        let inline_config = match inline_config {
1899            Some(inline_config) => inline_config,
1900            None => Arc::new(InlineConfig::new_parsed(&output, &config)?),
1901        };
1902
1903        Ok(CompiledTestProject {
1904            project_root,
1905            config,
1906            evm_opts,
1907            output,
1908            filter,
1909            inline_config,
1910            replay_symbolic_artifact,
1911            selected_sources,
1912            _brutalized_workspace: brutalized_workspace,
1913        })
1914    }
1915
1916    pub(crate) async fn prepare_fuzz_minimize_replay(
1917        &mut self,
1918        corpus_dir: &Path,
1919    ) -> Result<FuzzMinimizeReplaySession> {
1920        let CompiledTestProject { mut config, mut evm_opts, output, filter, inline_config, .. } =
1921            self.compile_project().await?;
1922
1923        if config.fuzz.run == Some(0) {
1924            bail!("`fuzz.run` must be greater than 0");
1925        }
1926        self.apply_gas_report_overrides(&mut config, &mut evm_opts);
1927        for corpus in [&mut config.fuzz.corpus, &mut config.invariant.corpus] {
1928            corpus.corpus_dir.get_or_insert_with(|| corpus_dir.to_path_buf());
1929        }
1930        config.fuzz.seed = config.fuzz.seed.or(Some(U256::ZERO));
1931
1932        evm_opts.infer_network_from_fork().await?;
1933        config.networks = evm_opts.networks;
1934
1935        let override_networks = inline_config.referenced_override_networks(&config.profile);
1936        let (default_pass, override_passes) = network_passes(config, evm_opts, &override_networks);
1937        let mut passes = Vec::new();
1938        for NetworkPass { config, evm_opts, multi_network } in
1939            std::iter::once(default_pass).chain(override_passes)
1940        {
1941            let execution = TestExecutionOptions {
1942                multi_network,
1943                ..TestExecutionOptions::default_run(inline_config.clone())
1944            };
1945            let config = Arc::new(config);
1946            passes.push(dispatch_network!(&evm_opts, |Net| {
1947                let backend = spawn_backend::<Net>(&config, &evm_opts)?;
1948                let runner = self
1949                    .build_runner::<Net>(
1950                        config,
1951                        evm_opts,
1952                        &output,
1953                        execution,
1954                        backend,
1955                        ExecutorBuilder::<Net>::new(),
1956                    )
1957                    .await?;
1958                fuzz_minimize_pass(runner, &filter)
1959            }));
1960        }
1961
1962        if passes.iter().all(|pass| pass.target_count == 0) {
1963            bail!("fuzz minimization requires at least one matched fuzz or invariant test");
1964        }
1965        Ok(FuzzMinimizeReplaySession { filter, passes })
1966    }
1967
1968    /// Executes all the tests in the project.
1969    ///
1970    /// See [`Self::compile_and_run`] for more details.
1971    pub(crate) async fn run_tests(
1972        &mut self,
1973        project_root: &Path,
1974        mut config: Config,
1975        mut evm_opts: EvmOpts,
1976        output: &ProjectCompileOutput,
1977        filter: &ProjectPathsAwareFilter,
1978        mut execution: TestExecutionOptions,
1979    ) -> Result<TestOutcome> {
1980        self.ensure_mutation_mode_compatible(execution.coverage)?;
1981
1982        if config.fuzz.run == Some(0) {
1983            bail!("`fuzz.run` must be greater than 0");
1984        }
1985
1986        if self.list {
1987            return list_from_output(
1988                output,
1989                &config,
1990                &execution.inline_config,
1991                filter,
1992                self.fuzz_only,
1993                execution.replay_symbolic_artifact.as_ref(),
1994            );
1995        }
1996
1997        execution.fuzz_input =
1998            self.load_fuzz_input(output, &config, &execution.inline_config, filter)?;
1999        self.warn_unsupported_engine_flags(
2000            output,
2001            &config,
2002            &execution.inline_config,
2003            filter,
2004            &execution.multi_network,
2005        )?;
2006        self.warn_skipped_test_suites(output, &config, &execution.inline_config, filter)?;
2007
2008        let mut filter = filter.clone();
2009        self.apply_gas_report_overrides(&mut config, &mut evm_opts);
2010
2011        // Generate a random fuzz seed if none provided, for reproducibility.
2012        config.fuzz.seed = config
2013            .fuzz
2014            .seed
2015            .or_else(|| Some(U256::from_be_bytes(rand::rng().random::<[u8; 32]>())));
2016
2017        let trace_output = if self.flamegraph {
2018            Some(TraceOutputKind::Flamegraph)
2019        } else if self.flamechart {
2020            Some(TraceOutputKind::Flamechart)
2021        } else {
2022            self.evm_profile.map(TraceOutputKind::EvmProfile)
2023        };
2024
2025        // Determine executor verbosity.
2026        if evm_opts.verbosity < 3 && (self.gas_report || trace_output.is_some()) {
2027            evm_opts.verbosity = 3;
2028        }
2029
2030        // Enable internal tracing for more informative flamegraph/profile. Simple tracing is
2031        // upgraded to full tracing in `run_tests_inner` when exactly one test matches.
2032        config.tracing = self.tracing.resolve(&config.tracing, evm_opts.verbosity);
2033        let json_trace_depth = config.tracing.trace_depth;
2034        execution.decode_internal = if config.tracing.decode_internal || trace_output.is_some() {
2035            InternalTraceMode::Simple
2036        } else {
2037            InternalTraceMode::None
2038        };
2039
2040        // Auto-detect network from fork chain ID when not explicitly configured.
2041        evm_opts.infer_network_from_fork().await?;
2042        // Inline configuration starts from this base config. Materialize the inferred execution
2043        // network so unrelated inline overrides cannot erase the fork's EVM family.
2044        config.networks = evm_opts.networks;
2045        let verbosity = evm_opts.verbosity;
2046
2047        let build_info_dir = config.project_paths::<MultiCompilerLanguage>().build_infos;
2048        // Box each network's run so the dispatch arms' locals stay off this frame.
2049        dispatch_network!(&evm_opts, |Net| {
2050            Box::pin(async {
2051                let backend = spawn_backend::<Net>(&config, &evm_opts)?;
2052                // Retain the baseline inputs for the mutation campaign.
2053                let config_for_mutation = config.clone();
2054                let evm_opts_for_mutation = evm_opts.clone();
2055
2056                // Run each distinct per-test network annotation as a separate pass and merge
2057                // results.
2058                let override_networks =
2059                    execution.inline_config.referenced_override_networks(&config.profile);
2060                let is_multi_pass = !override_networks.is_empty();
2061                let multi_pass_timer = Instant::now();
2062                let (default_pass, override_passes) =
2063                    network_passes(config, evm_opts, &override_networks);
2064                let default_config = Arc::new(default_pass.config);
2065                let default_verbosity = default_pass.evm_opts.verbosity;
2066                let runner = self
2067                    .build_runner::<Net>(
2068                        default_config.clone(),
2069                        default_pass.evm_opts,
2070                        output,
2071                        TestExecutionOptions {
2072                            multi_network: default_pass.multi_network,
2073                            ..execution.clone()
2074                        },
2075                        backend.clone(),
2076                        ExecutorBuilder::<Net>::new(),
2077                    )
2078                    .await?;
2079                let libraries = runner.libraries.clone();
2080                let mut outcome = self
2081                    .run_tests_inner(runner, default_config, default_verbosity, &mut filter, output)
2082                    .await?;
2083                for pass in override_passes {
2084                    let (_, pass_outcome) =
2085                        self.run_network_pass(pass, output, &mut filter, execution.clone()).await?;
2086                    merge_outcomes(&mut outcome, pass_outcome);
2087                }
2088                if is_multi_pass {
2089                    // Per-pass summaries are suppressed in `run_tests_inner`.
2090                    self.print_summary(&outcome, multi_pass_timer.elapsed())?;
2091                }
2092
2093                // Record failures once after merging all network passes, including successful runs.
2094                persist_run_failures(&config_for_mutation, &outcome);
2095
2096                if let Some(replay) = &execution.replay_symbolic_artifact {
2097                    let target = &replay.artifact.test;
2098                    match outcome.tests().count() {
2099                        0 => bail!(
2100                            "symbolic artifact target `{}::{}` was not found",
2101                            target.contract,
2102                            target.test
2103                        ),
2104                        1 => {}
2105                        replayed => bail!(
2106                            "symbolic artifact target `{}::{}` matched {replayed} tests; replay requires exactly one target",
2107                            target.contract,
2108                            target.test
2109                        ),
2110                    }
2111                }
2112
2113                if let Some(path) = &self.json_file {
2114                    let mut results =
2115                        outcome.json_file_results.take().unwrap_or_else(|| outcome.results.clone());
2116                    prepare_results_for_json(&mut results, verbosity, json_trace_depth);
2117                    fs::write_json_file(path, &results)?;
2118                }
2119
2120                if let Some(trace_output) = trace_output {
2121                    self.render_trace_output(trace_output, &mut outcome).await?;
2122                }
2123
2124                if self.debug {
2125                    // Get first non-empty suite result. We will have only one such entry.
2126                    let (_, _, test_result) =
2127                        outcome.remove_first().ok_or_eyre("no tests were executed")?;
2128                    let mut sources = ContractSources::from_project_output(
2129                        output,
2130                        project_root,
2131                        Some(&libraries),
2132                    )?;
2133                    sources.insert_compiled_sources(&build_info_dir);
2134
2135                    let mut builder = DebuggerBuilder::new()
2136                        .traces(test_result.traces)
2137                        .sources(sources)
2138                        .breakpoints(test_result.breakpoints);
2139                    if let Some(decoder) = &outcome.last_run_decoder {
2140                        builder = builder.decoder(decoder);
2141                    }
2142                    if let Some(known_contracts) = &outcome.known_contracts {
2143                        builder = builder.known_contracts(known_contracts);
2144                    }
2145                    builder.run(self.dump.as_deref())?;
2146                }
2147
2148                // All tests have been run once before reaching this point
2149                if let Some(mutate) = &self.mutate {
2150                    if outcome.failed() > 0 {
2151                        bail!(
2152                            "Mutation testing compiler profile failed its unmutated baseline run; \
2153                         adjust `--mutation-via-ir` / `--mutation-optimizer-runs` or fix the tests \
2154                         before running mutation testing"
2155                        );
2156                    }
2157                    // A green baseline that ran zero non-skipped tests would report every
2158                    // compileable mutant as `Alive`, so hard-error instead of producing a
2159                    // misleading report.
2160                    if outcome.successes().next().is_none() {
2161                        bail!(
2162                            "Mutation testing requires at least one passing baseline test; the \
2163                             current filter/path selection matched zero non-skipped tests. Loosen \
2164                             `--match-test` / `--match-contract` / `--match-path` or check the \
2165                             project layout."
2166                        );
2167                    }
2168                    // Clap can't express this conflict because `--mutate` takes an optional list of
2169                    // paths.
2170                    if !mutate.is_empty() && self.mutate_path.is_some() {
2171                        bail!(
2172                            "`--mutate-path <PATTERN>` cannot be combined with explicit paths passed to `--mutate`; pass either paths or a glob pattern, not both"
2173                        );
2174                    }
2175                    // The mutation runner builds a single-pass `MultiContractRunner` and does not
2176                    // honor inline per-test network annotations, which would silently run tests on
2177                    // the wrong network and produce false survivors / kills.
2178                    if is_multi_pass {
2179                        bail!(
2180                            "Mutation testing does not yet support inline per-test network \
2181                             overrides (found {} annotated network(s)). Re-run without `--mutate` \
2182                             or remove the per-test network annotations.",
2183                            override_networks.len()
2184                        );
2185                    }
2186                    ensure_mutation_workspace_safe(&config_for_mutation)?;
2187
2188                    let json_output = shell::is_json();
2189                    let selected_sources_relative = execution
2190                        .selected_sources
2191                        .iter()
2192                        .filter_map(|path| {
2193                            path.strip_prefix(&config_for_mutation.root).ok().map(PathBuf::from)
2194                        })
2195                        .collect::<Vec<_>>();
2196                    let mutation_config = MutationRunConfig {
2197                        mutate_paths: mutate.clone(),
2198                        mutate_path_pattern: self.mutate_path.clone(),
2199                        mutate_contract_pattern: self.mutate_contract.clone(),
2200                        num_workers: self.mutation_jobs.unwrap_or(0),
2201                        show_progress: self.show_progress,
2202                        json_output,
2203                        // Carry the filter the baseline actually used (positional path shorthand
2204                        // folded into `path_pattern`, `--rerun` failures injected into
2205                        // `test_pattern`) and its isolation flag so every mutant exercises the
2206                        // exact same test set.
2207                        filter_args: filter.args().clone(),
2208                        rerun_failures: filter.rerun_failures().map(<[RerunFailure]>::to_vec),
2209                        selected_sources_relative,
2210                        isolate: evm_opts_for_mutation.isolate,
2211                    };
2212                    let result = run_mutation_testing(
2213                        Arc::new(config_for_mutation),
2214                        output,
2215                        evm_opts_for_mutation,
2216                        backend,
2217                        ExecutorBuilder::<Net>::new(),
2218                        mutation_config,
2219                    )
2220                    .await?;
2221                    if result.cancelled {
2222                        std::process::exit(130);
2223                    }
2224                    if json_output {
2225                        let json_output = result.summary.to_json_output(result.duration_secs);
2226                        sh_println!("{}", serde_json::to_string(&json_output)?)?;
2227                    }
2228                    outcome = TestOutcome::empty(None, true);
2229                }
2230
2231                Ok::<_, eyre::Report>(outcome)
2232            })
2233            .await
2234        })
2235    }
2236
2237    /// Renders the flamegraph, flamechart or EVM profile of the single executed test.
2238    async fn render_trace_output(
2239        &self,
2240        trace_output: TraceOutputKind,
2241        outcome: &mut TestOutcome,
2242    ) -> Result<()> {
2243        let label = trace_output.label();
2244        let no_tests = match trace_output {
2245            TraceOutputKind::EvmProfile(_) => "cannot generate EVM profile: no tests were executed",
2246            TraceOutputKind::Flamegraph | TraceOutputKind::Flamechart => "no tests were executed",
2247        };
2248        if outcome.tests().next().is_none() {
2249            bail!("{no_tests}");
2250        }
2251        let decoder = outcome
2252            .last_run_decoder
2253            .clone()
2254            .ok_or_else(|| eyre::eyre!("cannot generate {label}: missing trace decoder"))?;
2255        let (suite_name, test_name, test_result) =
2256            outcome
2257                .results
2258                .iter_mut()
2259                .find_map(|(suite_name, suite)| {
2260                    suite.test_results.iter_mut().next().map(|(test_name, result)| {
2261                        (suite_name.as_str(), test_name.as_str(), result)
2262                    })
2263                })
2264                .ok_or_else(|| eyre::eyre!("{no_tests}"))?;
2265        let contract = suite_name.split(':').next_back().unwrap();
2266        let test_name = test_name.trim_end_matches("()");
2267        let (_, arena) =
2268            test_result.traces.iter_mut().find(|(kind, _)| kind.is_execution()).ok_or_else(
2269                || {
2270                    eyre::eyre!(
2271                        "cannot generate {label} for {contract}::{test_name}: no execution trace \
2272                     (test may have failed in setUp/constructor or been skipped)"
2273                    )
2274                },
2275            )?;
2276        decode_trace_arena(arena, &decoder).await;
2277
2278        match trace_output {
2279            TraceOutputKind::Flamegraph | TraceOutputKind::Flamechart => {
2280                let mut folded_stack_trace = folded_stack_trace::build(arena);
2281                let flame_chart = trace_output == TraceOutputKind::Flamechart;
2282                if flame_chart {
2283                    folded_stack_trace.reverse();
2284                }
2285                let file_name = format!("cache/{label}_{contract}_{test_name}.svg");
2286                let file = std::fs::File::create(&file_name).wrap_err("failed to create file")?;
2287                let mut options = inferno::flamegraph::Options::default();
2288                options.title = format!("{label} {contract}::{test_name}");
2289                options.count_name = "gas".to_string();
2290                options.flame_chart = flame_chart;
2291                inferno::flamegraph::from_lines(
2292                    &mut options,
2293                    folded_stack_trace.iter().map(String::as_str),
2294                    std::io::BufWriter::new(file),
2295                )
2296                .wrap_err("failed to write svg")?;
2297                sh_println!("Saved to {file_name}")?;
2298                if !self.no_open
2299                    && let Err(e) = opener::open(&file_name)
2300                {
2301                    sh_err!("Failed to open {file_name}; please open it manually: {e}")?;
2302                }
2303            }
2304            TraceOutputKind::EvmProfile(EvmProfileFormat::Speedscope) => {
2305                let profile = speedscope::builder::build(arena, test_name, contract);
2306                let profile_json = serde_json::to_vec(&profile)?;
2307                let profile_path = format!("cache/evm_profile_{contract}_{test_name}.json");
2308                fs::write(&profile_path, &profile_json)?;
2309                sh_println!("Profile saved to {profile_path}")?;
2310                if !self.no_open {
2311                    evm_profile_server::serve_and_open(profile_json, test_name, contract).await?;
2312                }
2313            }
2314        }
2315        Ok(())
2316    }
2317
2318    /// Builds the test runner for the network selected by `evm_opts`.
2319    async fn build_runner<FEN: FoundryEvmNetwork>(
2320        &self,
2321        config: Arc<Config>,
2322        evm_opts: EvmOpts,
2323        output: &ProjectCompileOutput,
2324        execution: TestExecutionOptions,
2325        backend: Backend<FEN>,
2326        executor_builder: ExecutorBuilder<FEN>,
2327    ) -> Result<MultiContractRunner<FEN>> {
2328        let (evm_env, tx) = backend.env(&evm_opts).await?;
2329        let create2_deployer_available =
2330            backend.can_use_create2_deployer(evm_opts.create2_deployer).await?;
2331
2332        MultiContractRunnerBuilder::new(config.clone(), execution.inline_config)
2333            .set_debug(self.debug)
2334            .set_decode_internal(execution.decode_internal)
2335            .set_record_all_steps(self.evm_profile.is_some())
2336            .initial_balance(evm_opts.initial_balance)
2337            .sender(evm_opts.sender)
2338            .enable_isolation(evm_opts.isolate)
2339            .fail_fast(self.fail_fast)
2340            .set_coverage(execution.coverage)
2341            .with_multi_network(execution.multi_network)
2342            .with_showmap(self.showmap_config()?)
2343            .with_fuzz_only(self.fuzz_only)
2344            .with_fuzz_failure_replay(self.fuzz_failure_replay)
2345            .with_fuzz_input(execution.fuzz_input)
2346            .with_symbolic_artifact_replay(execution.replay_symbolic_artifact)
2347            .with_create2_deployer_available(create2_deployer_available)
2348            .build::<FEN, MultiCompiler>(output, evm_env, tx, evm_opts, backend, executor_builder)
2349    }
2350
2351    /// Builds the runner for one network pass and runs its tests.
2352    async fn run_network_pass(
2353        &self,
2354        pass: NetworkPass,
2355        output: &ProjectCompileOutput,
2356        filter: &mut ProjectPathsAwareFilter,
2357        execution: TestExecutionOptions,
2358    ) -> Result<(Libraries, TestOutcome)> {
2359        let NetworkPass { config, evm_opts, multi_network } = pass;
2360        let execution = TestExecutionOptions { multi_network, ..execution };
2361        let verbosity = evm_opts.verbosity;
2362        let config = Arc::new(config);
2363        dispatch_network!(&evm_opts, |Net| {
2364            let backend = spawn_backend::<Net>(&config, &evm_opts)?;
2365            let runner = self
2366                .build_runner::<Net>(
2367                    config.clone(),
2368                    evm_opts,
2369                    output,
2370                    execution,
2371                    backend,
2372                    ExecutorBuilder::<Net>::new(),
2373                )
2374                .await?;
2375            let libraries = runner.libraries.clone();
2376            let outcome = self.run_tests_inner(runner, config, verbosity, filter, output).await?;
2377            Ok((libraries, outcome))
2378        })
2379    }
2380
2381    /// Emits symbolic regression tests for the counterexample artifacts in `results` when
2382    /// `--emit-regression` is set, and attaches them to the results.
2383    fn emit_symbolic_regressions(
2384        &self,
2385        config: &Config,
2386        known_contracts: &ContractsByArtifact,
2387        results: &mut BTreeMap<String, SuiteResult>,
2388    ) -> Result<Vec<SymbolicRegression>> {
2389        if !self.emit_regression {
2390            return Ok(Vec::new());
2391        }
2392        let regression = SymbolicRegressionConfig {
2393            out: self
2394                .regression_out
2395                .clone()
2396                .map(|path| if path.is_relative() { config.root.join(path) } else { path }),
2397            overwrite: self.regression_overwrite,
2398        };
2399        let artifacts = collect_symbolic_artifacts_from_suites(results.values());
2400        let regressions =
2401            emit_symbolic_regressions(config, &regression, known_contracts, &artifacts)?;
2402        attach_symbolic_regressions_to_suites(results.values_mut(), &regressions);
2403        Ok(regressions)
2404    }
2405
2406    /// Prints the run summary, or the detailed summary table when `--summary` is set.
2407    fn print_summary(&self, outcome: &TestOutcome, duration: Duration) -> Result<()> {
2408        if !self.summary && !shell::is_json() {
2409            sh_println!("{}", outcome.summary(duration))?;
2410        }
2411        if self.summary && !outcome.results.is_empty() {
2412            sh_println!("{}", TestSummaryReport::new(self.detailed, outcome))?;
2413        }
2414        Ok(())
2415    }
2416
2417    /// Run all tests that matches the filter predicate from a test runner
2418    async fn run_tests_inner<FEN: FoundryEvmNetwork>(
2419        &self,
2420        mut runner: MultiContractRunner<FEN>,
2421        config: Arc<Config>,
2422        verbosity: u8,
2423        filter: &mut ProjectPathsAwareFilter,
2424        output: &ProjectCompileOutput,
2425    ) -> Result<TestOutcome> {
2426        let fuzz_seed = config.fuzz.seed;
2427
2428        trace!(target: "forge::test", "running all tests");
2429
2430        // If we need to render to a serialized format, we should not print anything else to stdout.
2431        let silent = shell::is_json() && (self.gas_report || self.summary || self.mutate.is_some());
2432        let tracing = &config.tracing;
2433        let trace_verbosity = tracing.verbosity;
2434
2435        let mut num_filtered = runner.matching_test_functions(filter).count();
2436
2437        if !self.opcodes.is_empty() && trace_verbosity < 5 {
2438            sh_eprintln!()?;
2439            bail!("Not enough verbosity. Use -vvvvv to show opcodes.");
2440        }
2441
2442        if num_filtered == 0 {
2443            let empty_filter = EmptyTestFilter::default();
2444            let mut has_tests = runner.matching_test_functions(&empty_filter).next().is_some();
2445            // Selective compilation omits unmatched contracts. Consult ABI discovery only
2446            // when diagnostics need the tests that the runner cannot see.
2447            let discovery = if filter.is_empty() {
2448                None
2449            } else {
2450                Some(self.compile_test_abis(&config, filter)?.1)
2451            };
2452            let mut candidates =
2453                runner.all_test_functions(filter).map(|f| &f.name).collect::<Vec<_>>();
2454            if let Some(output) = &discovery {
2455                let matcher = runner.test_function_matcher();
2456                for (id, artifact) in output.artifact_ids() {
2457                    let id = id.with_stripped_file_prefixes(&config.root);
2458                    if let Some(abi) = &artifact.abi
2459                        && matcher.matches_contract(&empty_filter, &id, abi)
2460                        && is_runnable_test_contract(output, &config, &id, artifact, abi)
2461                    {
2462                        has_tests = true;
2463                        if filter.matches_path(&id.source) && filter.matches_contract(&id.name) {
2464                            candidates.extend(
2465                                matcher
2466                                    .test_functions(id.identifier(), abi, |_, _, kind| {
2467                                        kind.is_any_test()
2468                                    })
2469                                    .map(|function| &function.name),
2470                            );
2471                        }
2472                    }
2473                }
2474            }
2475            if has_tests {
2476                let mut msg = format!("no tests match the provided pattern:\n{filter}");
2477                // Try to suggest a test when there's no match.
2478                if let Some(test_pattern) = &filter.args().test_pattern
2479                    && let Some(suggestion) =
2480                        utils::did_you_mean(test_pattern.as_str(), candidates).pop()
2481                {
2482                    write!(msg, "\nDid you mean `{suggestion}`?")?;
2483                }
2484                sh_warn!("{msg}")?;
2485            } else {
2486                sh_warn!(
2487                    "No tests found in project! Forge looks for functions that start with `test`"
2488                )?;
2489            }
2490            // Machine-readable modes still get a well-formed, empty document on stdout.
2491            if self.junit {
2492                sh_println!("{}", junit_xml_report(&BTreeMap::new(), verbosity).to_string()?)?;
2493            } else if self.mutate.is_none() && !self.gas_report && !self.summary && shell::is_json()
2494            {
2495                sh_println!("{}", serde_json::to_string(&BTreeMap::<String, SuiteResult>::new())?)?;
2496            }
2497            return Ok(TestOutcome::empty(Some(runner.known_contracts.clone()), false));
2498        }
2499
2500        let debug_selection_term = Term::stderr();
2501        let interactive_debug_selection = self.debug
2502            && num_filtered != 1
2503            && tui_mode().is_interactive()
2504            && debug_selection_term.is_term();
2505        let mut matching_debug_tests = if interactive_debug_selection {
2506            collect_matching_debug_tests(&runner.list_signatures(filter))
2507        } else if self.debug && num_filtered != 1 {
2508            collect_matching_debug_tests(&runner.list(filter))
2509        } else {
2510            Vec::new()
2511        };
2512        if interactive_debug_selection {
2513            ctrlc::set_handler(|| {
2514                let _ = Term::stderr().show_cursor();
2515                std::process::exit(130);
2516            })?;
2517
2518            let Some(selected) = Select::new()
2519                .with_prompt("Select a test to debug")
2520                .items(
2521                    matching_debug_tests
2522                        .iter()
2523                        .map(|test| format!("{}.{}", test.contract, test.test)),
2524                )
2525                .max_length(DEBUGGER_MATCHING_TESTS_DISPLAY_LIMIT)
2526                .interact_on_opt(&debug_selection_term)?
2527            else {
2528                bail!("Debugger test selection cancelled");
2529            };
2530
2531            filter.set_rerun_failures(vec![matching_debug_tests.swap_remove(selected)]);
2532            num_filtered = 1;
2533        }
2534
2535        if num_filtered != 1
2536            && (self.debug || self.flamegraph || self.flamechart || self.evm_profile.is_some())
2537        {
2538            let action = if self.flamegraph {
2539                "generate a flamegraph"
2540            } else if self.flamechart {
2541                "generate a flamechart"
2542            } else if self.evm_profile.is_some() {
2543                "generate an EVM profile"
2544            } else {
2545                "run the debugger"
2546            };
2547            let filter_hint = if filter.is_empty() {
2548                String::new()
2549            } else {
2550                format!("\n\nFilter used:\n{filter}")
2551            };
2552            let matching_tests_hint = if self.debug {
2553                format_matching_debug_tests(&matching_debug_tests)
2554            } else {
2555                String::new()
2556            };
2557            let narrowing_hint = if self.debug {
2558                "Use --match-test <TEST_NAME>, --match-contract, and --match-path to further limit the search."
2559            } else {
2560                "Use --match-contract and --match-path to further limit the search."
2561            };
2562            bail!(
2563                "{num_filtered} tests matched your criteria, but exactly 1 test must match in order to {action}.{matching_tests_hint}\n\n\
2564                 {narrowing_hint}{filter_hint}",
2565            );
2566        }
2567
2568        // If exactly one test matched, we enable full tracing.
2569        if num_filtered == 1 && runner.decode_internal != InternalTraceMode::None {
2570            runner.decode_internal = InternalTraceMode::Full;
2571        }
2572
2573        // Run tests in a non-streaming fashion and collect results for serialization.
2574        let serialize_json =
2575            self.mutate.is_none() && !self.gas_report && !self.summary && shell::is_json();
2576        if serialize_json || self.junit {
2577            let mut results = runner.test_collect(filter)?;
2578            if serialize_json {
2579                prepare_results_for_json(&mut results, verbosity, tracing.trace_depth);
2580            }
2581            self.emit_symbolic_regressions(&config, &runner.known_contracts, &mut results)?;
2582            let rendered = if serialize_json {
2583                serde_json::to_string(&results)?
2584            } else {
2585                junit_xml_report(&results, verbosity).to_string()?
2586            };
2587            sh_println!("{rendered}")?;
2588
2589            let mut gas_snapshots = BTreeMap::<String, BTreeMap<String, String>>::new();
2590            for result in results.values().flat_map(|suite| suite.test_results.values()) {
2591                for (group, new_snapshots) in &result.gas_snapshots {
2592                    gas_snapshots.entry(group.clone()).or_default().extend(new_snapshots.clone());
2593                }
2594            }
2595            if !gas_snapshots.is_empty() {
2596                self.check_and_write_gas_snapshots(&config, &gas_snapshots)?;
2597            }
2598
2599            return Ok(TestOutcome::new(
2600                Some(runner.known_contracts),
2601                results,
2602                self.allow_failure,
2603                fuzz_seed,
2604            ));
2605        }
2606
2607        let remote_chain = runner
2608            .backend
2609            .is_forked_mode()
2610            .then(|| runner.tcfg.fork_chain_id.or(runner.tcfg.tx.chain_id()))
2611            .flatten()
2612            .map(Into::into);
2613        let known_contracts = runner.known_contracts.clone();
2614        let libraries = runner.libraries.clone();
2615
2616        // Capture multi-pass state before moving `runner` into the spawn task.
2617        // In multi-pass mode the per-pass summary is suppressed; the merged summary is
2618        // printed once by the caller after all passes complete.
2619        let is_multi_pass = !runner.tcfg.multi_network.all_override_networks.is_empty();
2620        let resolved_hardfork = runner.tcfg.hardfork;
2621        let networks = runner.tcfg.evm_opts.networks;
2622        let extra_cheatcode_addresses = runner.tcfg.executor_builder.extra_cheatcode_addresses();
2623        let decode_internal = runner.decode_internal != InternalTraceMode::None;
2624
2625        // Run tests in a streaming fashion.
2626        let (tx, rx) = channel::<(String, SuiteResult)>();
2627        let timer = Instant::now();
2628        let show_progress = config.show_progress;
2629        let handle = tokio::task::spawn_blocking({
2630            let filter = filter.clone();
2631            move || runner.test(&filter, tx, show_progress).map(|()| runner)
2632        });
2633
2634        // Set up trace identifiers.
2635        let mut identifier = TraceIdentifiers::new().with_local(&known_contracts);
2636
2637        // Avoid using external identifiers for gas report as we decode more traces and this will be
2638        // expensive. Also skip external identifiers for local tests (no remote chain) to avoid
2639        // unnecessary Etherscan API calls that significantly slow down test execution.
2640        if !self.gas_report && remote_chain.is_some() {
2641            identifier = identifier.with_external(&config, remote_chain)?;
2642        }
2643
2644        // Build the trace decoder.
2645        let mut builder = CallTraceDecoderBuilder::new()
2646            .with_tracing_config(tracing)
2647            .with_known_contracts(&known_contracts)
2648            .with_networks(networks)
2649            .with_chain_id(remote_chain.map(|c| c.id()))
2650            .with_hardfork(resolved_hardfork);
2651        // Signatures are of no value for gas reports.
2652        if !self.gas_report {
2653            builder =
2654                builder.with_signature_identifier(SignaturesIdentifier::from_config(&config)?);
2655        }
2656        // SolDB decodes internal calls from compiler sources.
2657        if decode_internal && !self.debug {
2658            let sources =
2659                ContractSources::from_project_output(output, &config.root, Some(&libraries))?;
2660            builder = builder.with_debug_identifier(DebugTraceIdentifier::new(sources));
2661        }
2662        let mut decoder = builder.build();
2663
2664        let mut gas_report = self.gas_report.then(|| {
2665            GasReport::new(
2666                config.gas_reports.clone(),
2667                config.gas_reports_ignore.clone(),
2668                config.gas_reports_include_tests,
2669                extra_cheatcode_addresses.iter().copied(),
2670            )
2671        });
2672
2673        let mut gas_snapshots = BTreeMap::<String, BTreeMap<String, String>>::new();
2674
2675        let mut outcome = TestOutcome::empty(None, self.allow_failure);
2676        outcome.fuzz_seed = fuzz_seed;
2677
2678        // Some outputs need trace identities even if the textual trace is not rendered.
2679        let always_identify_traces = self.gas_report
2680            || self.debug
2681            || self.flamegraph
2682            || self.flamechart
2683            || self.evm_profile.is_some();
2684
2685        let mut any_test_failed = false;
2686        let mut backtrace_builder = None;
2687        while let Ok((contract_name, mut suite_result)) = rx.recv() {
2688            let len = suite_result.len();
2689            let tests = &mut suite_result.test_results;
2690            let has_tests = !tests.is_empty();
2691
2692            // In multi-pass (per-test network override) mode, skip suites that contributed no
2693            // tests to this pass so we don't emit a stray blank line in the suite header or
2694            // pollute the outcome with empty entries.
2695            if is_multi_pass && !has_tests && suite_result.warnings.is_empty() {
2696                continue;
2697            }
2698
2699            // Clear the addresses and labels from previous test.
2700            decoder.clear_addresses();
2701
2702            // Print suite header.
2703            if !silent {
2704                sh_println!()?;
2705                for warning in &suite_result.warnings {
2706                    sh_warn!("{warning}")?;
2707                }
2708                if has_tests {
2709                    let tests = if len > 1 { "tests" } else { "test" };
2710                    sh_println!("Ran {len} {tests} for {contract_name}")?;
2711                }
2712            }
2713
2714            // Process individual test results, printing logs and traces when necessary.
2715            for (name, result) in tests {
2716                let test_failed = result.status.is_failure();
2717                let show_traces = !self.suppress_successful_traces || test_failed;
2718                // Trace verbosity.
2719                // - 0..3: nothing.
2720                // - 3: only display traces for failed tests.
2721                // - 4: also display the setup trace for failed tests.
2722                // - 5..: display all traces for all tests, including storage changes.
2723                let should_include_trace = |kind: &TraceKind| match kind {
2724                    TraceKind::Execution => {
2725                        (trace_verbosity == 3 && test_failed) || trace_verbosity >= 4
2726                    }
2727                    TraceKind::Setup => {
2728                        (trace_verbosity == 4 && test_failed) || trace_verbosity >= 5
2729                    }
2730                    TraceKind::Deployment => false,
2731                };
2732                let renders_trace = !silent
2733                    && show_traces
2734                    && result.traces.iter().any(|(kind, _)| should_include_trace(kind));
2735                let identify_addresses = always_identify_traces || renders_trace;
2736
2737                if !silent {
2738                    sh_println!("{}", result.short_result_with_suite(name, &contract_name))?;
2739                    for artifact in &result.counterexample_artifacts {
2740                        sh_warn!("Counterexample artifact: {}", artifact.path.display())?;
2741                    }
2742
2743                    if let TestKind::Invariant { metrics, .. } = &result.kind
2744                        && !metrics.is_empty()
2745                    {
2746                        let _ = sh_println!("\n{}\n", format_invariant_metrics_table(metrics));
2747                    }
2748
2749                    // We only display logs at level 2 and above
2750                    if verbosity >= 2 && show_traces {
2751                        // We only decode logs from Hardhat and DS-style console events
2752                        let console_logs = decode_console_logs(&result.logs);
2753                        if !console_logs.is_empty() {
2754                            sh_println!("Logs:")?;
2755                            for log in console_logs {
2756                                sh_println!("  {log}")?;
2757                            }
2758                            sh_println!()?;
2759                        }
2760                    }
2761                }
2762
2763                // We shouldn't break out of the outer loop directly here so that we finish
2764                // processing the remaining tests and print the suite summary.
2765                any_test_failed |= result.status.is_failure();
2766
2767                // Clear the addresses and labels from previous runs.
2768                decoder.clear_addresses();
2769                if identify_addresses {
2770                    decoder.labels.extend(result.labels.iter().map(|(k, v)| (*k, v.clone())));
2771                }
2772
2773                // Identify addresses and decode traces.
2774                let mut decoded_traces = Vec::new();
2775                if identify_addresses {
2776                    for (kind, arena) in &mut result.traces {
2777                        if self.debug && !result.debug_bytecodes.is_empty() {
2778                            let mut local_identifier = TraceIdentifiers::new()
2779                                .with_local_and_bytecodes(
2780                                    &known_contracts,
2781                                    &result.debug_bytecodes,
2782                                );
2783                            decoder.identify(arena, &mut local_identifier);
2784                        }
2785                        decoder.identify(arena, &mut identifier);
2786
2787                        if renders_trace && should_include_trace(kind) {
2788                            decoder.opcodes = self.opcodes.clone();
2789                            decode_trace_arena(arena, &decoder).await;
2790                            let rendered = match tracing.trace_depth {
2791                                Some(trace_depth) => {
2792                                    let mut arena = arena.clone();
2793                                    prune_trace_depth(&mut arena, trace_depth);
2794                                    render_trace_arena_inner(&arena, false, trace_verbosity > 4)
2795                                }
2796                                None => render_trace_arena_inner(arena, false, trace_verbosity > 4),
2797                            };
2798                            decoded_traces.push(rendered);
2799                        }
2800                    }
2801                }
2802
2803                if !silent && show_traces && !decoded_traces.is_empty() {
2804                    sh_println!("Traces:")?;
2805                    for trace in &decoded_traces {
2806                        sh_println!("{trace}")?;
2807                    }
2808                }
2809
2810                // Extract and display backtrace for failed tests when trace verbosity >= 3.
2811                // At trace verbosity 3-4 backtraces show contract/function names only.
2812                // At trace verbosity 5 backtraces include source file locations.
2813                if !silent
2814                    && test_failed
2815                    && trace_verbosity >= 3
2816                    && let Some((_, arena)) =
2817                        result.traces.iter().find(|(kind, _)| kind.is_execution())
2818                {
2819                    let builder = backtrace_builder.get_or_insert_with(|| {
2820                        BacktraceBuilder::new(
2821                            output,
2822                            config.root.clone(),
2823                            config.parsed_libraries().ok(),
2824                            config.via_ir,
2825                        )
2826                    });
2827                    let backtrace = builder.from_traces(arena);
2828                    if !backtrace.is_empty() {
2829                        sh_println!("{}", backtrace)?;
2830                    }
2831                }
2832
2833                if let Some(gas_report) = &mut gas_report {
2834                    gas_report.analyze(result.traces.iter().map(|(_, a)| &a.arena), &decoder).await;
2835
2836                    if !result.gas_report_traces.is_empty() {
2837                        decoder.clear_addresses();
2838
2839                        // Identify the setup and deployment traces once to collect identities
2840                        // created in setUp and constructor; every sampled run starts from them.
2841                        for (kind, arena) in &result.traces {
2842                            if !kind.is_execution() {
2843                                decoder.identify_scoped(arena, &mut identifier);
2844                            }
2845                        }
2846                        let identities = decoder.address_identities();
2847
2848                        // Only a run that identified an address changed the decoder.
2849                        let mut identified = false;
2850                        for trace in &result.gas_report_traces {
2851                            if std::mem::take(&mut identified) {
2852                                decoder.restore_address_identities(&identities);
2853                            }
2854
2855                            for arena in trace {
2856                                identified |= decoder.identify_scoped(arena, &mut identifier);
2857                                gas_report.analyze([arena], &decoder).await;
2858                            }
2859                        }
2860                    }
2861                }
2862
2863                if shell::is_json()
2864                    && let Some(trace_depth) = tracing.trace_depth
2865                {
2866                    for (_, arena) in &mut result.traces {
2867                        *arena = trace_arena_at_depth(arena, trace_depth);
2868                    }
2869                }
2870                // Clear memory.
2871                result.gas_report_traces = Default::default();
2872
2873                // Collect and merge gas snapshots.
2874                for (group, new_snapshots) in &result.gas_snapshots {
2875                    gas_snapshots.entry(group.clone()).or_default().extend(new_snapshots.clone());
2876                }
2877            }
2878
2879            // Print suite summary.
2880            if !silent && has_tests {
2881                sh_println!("{}", suite_result.summary())?;
2882            }
2883
2884            // Add the suite result to the outcome.
2885            outcome.results.insert(contract_name, suite_result);
2886
2887            // Stop processing the remaining suites if any test failed and `fail_fast` is set.
2888            if self.fail_fast && any_test_failed {
2889                break;
2890            }
2891        }
2892
2893        // Check and write snapshots once all suites are in, since a group can span several suites.
2894        if !gas_snapshots.is_empty() {
2895            self.check_and_write_gas_snapshots(&config, &gas_snapshots)?;
2896        }
2897
2898        let regressions =
2899            self.emit_symbolic_regressions(&config, &known_contracts, &mut outcome.results)?;
2900        if !silent {
2901            for regression in regressions {
2902                sh_warn!(
2903                    "Regression test: {} (from {})",
2904                    regression.path.display(),
2905                    regression.artifact.display()
2906                )?;
2907            }
2908        }
2909        outcome.last_run_decoder = Some(decoder);
2910        let duration = timer.elapsed();
2911
2912        trace!(target: "forge::test", len=outcome.results.len(), %any_test_failed, "done with results");
2913
2914        if let Some(gas_report) = gas_report {
2915            let finalized = gas_report.finalize();
2916            sh_println!("{finalized}")?;
2917            outcome.gas_report = Some(finalized);
2918        }
2919
2920        if !is_multi_pass {
2921            self.print_summary(&outcome, duration)?;
2922        }
2923
2924        // Keep the receiver alive only when its queued results are needed for the JSON file.
2925        let json_results_rx = self.json_file.is_some().then_some(rx);
2926
2927        // Reattach the task.
2928        match handle.await {
2929            Ok(result) => {
2930                let runner = result?;
2931                outcome.known_contracts = Some(runner.known_contracts);
2932            }
2933            Err(e) => match e.try_into_panic() {
2934                Ok(payload) => std::panic::resume_unwind(payload),
2935                Err(e) => return Err(e.into()),
2936            },
2937        }
2938
2939        // Include suites that completed after fail-fast stopped console output in the JSON file.
2940        if let Some(rx) = json_results_rx {
2941            let mut results = outcome.results.clone();
2942            for (contract_name, suite_result) in rx.try_iter() {
2943                if is_multi_pass
2944                    && suite_result.test_results.is_empty()
2945                    && suite_result.warnings.is_empty()
2946                {
2947                    continue;
2948                }
2949                results.insert(contract_name, suite_result);
2950            }
2951            outcome.json_file_results = Some(results);
2952        }
2953
2954        Ok(outcome)
2955    }
2956
2957    /// Compares the collected gas snapshots against the ones on disk and writes them back,
2958    /// depending on `--gas-snapshot-check` / `--gas-snapshot-emit` and their config defaults.
2959    ///
2960    /// The CLI flags override the config and environment, so `--gas-snapshot-check=false` disables
2961    /// a check enabled in the config. Exits with code 1 if differences are found.
2962    fn check_and_write_gas_snapshots(
2963        &self,
2964        config: &Config,
2965        gas_snapshots: &BTreeMap<String, BTreeMap<String, String>>,
2966    ) -> Result<()> {
2967        if self.gas_snapshot_check.unwrap_or(config.gas_snapshot_check) {
2968            let mut differences_found = false;
2969            for (group, snapshots) in gas_snapshots {
2970                let path = config.snapshots.join(format!("{group}.json"));
2971                // If the snapshot file doesn't exist, we can't compare so we skip.
2972                if !path.exists() {
2973                    continue;
2974                }
2975                let previous_snapshots: BTreeMap<String, String> = fs::read_json_file(&path)?;
2976                let diff = snapshots
2977                    .iter()
2978                    .filter_map(|(k, v)| {
2979                        previous_snapshots
2980                            .get(k)
2981                            .filter(|previous| *previous != v)
2982                            .map(|p| (k, p, v))
2983                    })
2984                    .collect::<Vec<_>>();
2985                if diff.is_empty() {
2986                    continue;
2987                }
2988                let _ = sh_eprintln!(
2989                    "{}",
2990                    format!("\n[{group}] Failed to match snapshots:").red().bold()
2991                );
2992                for (key, previous_snapshot, snapshot) in diff {
2993                    let _ = sh_eprintln!(
2994                        "{}",
2995                        format!("- [{key}] {previous_snapshot} → {snapshot}").red()
2996                    );
2997                }
2998                differences_found = true;
2999            }
3000            if differences_found {
3001                sh_eprintln!()?;
3002                bail!("Snapshots differ from previous run");
3003            }
3004        }
3005
3006        if self.gas_snapshot_emit.unwrap_or(config.gas_snapshot_emit) {
3007            for (group, snapshots) in gas_snapshots {
3008                // Groups may be nested, such as `core/Pool`.
3009                let path = config.snapshots.join(format!("{group}.json"));
3010                fs::create_dir_all(path.parent().unwrap_or(&config.snapshots))?;
3011                fs::write_pretty_json_file(&path, &snapshots)?;
3012            }
3013        }
3014        Ok(())
3015    }
3016
3017    /// Returns the flattened [`FilterArgs`] arguments merged with [`Config`].
3018    /// Loads and applies filter from file if only last test run failures performed.
3019    pub fn filter(&self, config: &Config) -> Result<ProjectPathsAwareFilter> {
3020        let mut filter = self.filter.clone();
3021        let rerun_failures = if self.rerun {
3022            let failures = last_run_failures(config);
3023            filter.test_pattern = failures.test_pattern;
3024            failures.failures
3025        } else {
3026            None
3027        };
3028        if filter.path_pattern.is_some() {
3029            if self.path.is_some() {
3030                bail!("Can not supply both --match-path and |path|");
3031            }
3032        } else {
3033            filter.path_pattern = self.path.clone();
3034        }
3035        let mut filter = filter.merge_with_config(config);
3036        if let Some(failures) = rerun_failures {
3037            filter.set_rerun_failures(failures);
3038        }
3039        Ok(filter)
3040    }
3041
3042    /// Returns whether `BuildArgs` was configured with `--watch`
3043    pub const fn is_watch(&self) -> bool {
3044        self.watch.watch.is_some()
3045    }
3046
3047    /// Returns the [`watchexec::Config`] necessary to bootstrap a new watch loop.
3048    pub(crate) fn watchexec_config(&self) -> Result<watchexec::Config> {
3049        self.watch.watchexec_config(|| {
3050            let config = self.load_config()?;
3051            Ok([config.src, config.test])
3052        })
3053    }
3054}
3055
3056/// Returns the names of the enabled flags.
3057fn enabled_flags<const N: usize>(flags: [(bool, &'static str); N]) -> Vec<&'static str> {
3058    flags.into_iter().filter_map(|(enabled, name)| enabled.then_some(name)).collect()
3059}
3060
3061fn prepare_results_for_json(
3062    results: &mut BTreeMap<String, SuiteResult>,
3063    verbosity: u8,
3064    trace_depth: Option<usize>,
3065) {
3066    let decoder = CallTraceDecoder::new();
3067    for test_result in results.values_mut().flat_map(|suite| suite.test_results.values_mut()) {
3068        if verbosity >= 2 {
3069            test_result.decoded_logs = decode_console_logs(&test_result.logs);
3070        } else {
3071            test_result.logs = Vec::new();
3072        }
3073        for (_, arena) in &mut test_result.traces {
3074            // Discard presentation-only decoding populated by the streaming renderer.
3075            for node in arena.nodes_mut() {
3076                decoder.redact_raw_cheatcode_secrets(&mut node.trace);
3077                node.trace.decoded = None;
3078                for log in &mut node.logs {
3079                    log.decoded = None;
3080                }
3081                for step in &mut node.trace.steps {
3082                    step.decoded = None;
3083                }
3084            }
3085            if let Some(trace_depth) = trace_depth {
3086                *arena = trace_arena_at_depth(arena, trace_depth);
3087            }
3088        }
3089    }
3090}
3091
3092/// Bails if mutation testing could corrupt the real dependency trees.
3093///
3094/// The mutation runner symlinks dependency directories (`lib`, `node_modules`, `dependencies`)
3095/// into each per-mutant TempDir for performance (see `workspace::copy_project`). That isolation
3096/// breaks down if tests can write to those shared trees, either via `vm.writeFile` (broad
3097/// `fs_permissions`) or arbitrary `ffi` calls.
3098fn ensure_mutation_workspace_safe(config: &Config) -> Result<()> {
3099    if config.ffi {
3100        bail!(
3101            "Mutation testing is unsafe with `ffi = true`: per-mutant workspaces share \
3102             symlinked dependency directories, and arbitrary FFI commands run by tests \
3103             can race or corrupt the real `lib`/`node_modules`/`dependencies` trees. \
3104             Disable ffi in your foundry.toml to run mutation tests."
3105        );
3106    }
3107
3108    // Only refuse write-capable `fs_permissions` whose path can actually reach one of the
3109    // symlinked dependency trees. Scoped writes (e.g. `./out`, `./snapshots`) are safe.
3110    let root = &config.root;
3111    let canonicalize_through_existing_ancestor = |path: &Path| -> PathBuf {
3112        let resolved = if path.is_absolute() { path.to_path_buf() } else { root.join(path) };
3113        if let Ok(canon) = canonicalize_path(&resolved) {
3114            return canon;
3115        }
3116        let mut missing = Vec::new();
3117        let mut ancestor = resolved.as_path();
3118        while !ancestor.exists() {
3119            let Some(name) = ancestor.file_name() else { break };
3120            missing.push(name.to_owned());
3121            let Some(parent) = ancestor.parent() else { break };
3122            ancestor = parent;
3123        }
3124        let mut canon = canonicalize_path(ancestor).unwrap_or_else(|_| ancestor.into());
3125        canon.extend(missing.iter().rev());
3126        canon
3127    };
3128
3129    let shared_dep_dirs = config
3130        .libs
3131        .iter()
3132        .filter(|p| p.exists())
3133        .cloned()
3134        .chain(
3135            ["node_modules", "dependencies"]
3136                .into_iter()
3137                .map(|dep_dir| root.join(dep_dir))
3138                .filter(|dep_path| dep_path.is_dir()),
3139        )
3140        .map(|p| canonicalize_through_existing_ancestor(&p))
3141        .collect::<Vec<_>>();
3142
3143    let permissions = &config.fs_permissions.permissions;
3144    let effective_permission = |path: &Path| -> Option<FsAccessPermission> {
3145        let mut max_path_len = 0;
3146        let mut highest_permission = FsAccessPermission::None;
3147        for perm in permissions {
3148            let permission_path = canonicalize_through_existing_ancestor(&perm.path);
3149            if !path.starts_with(&permission_path) {
3150                continue;
3151            }
3152            let path_len = permission_path.components().count();
3153            if path_len > max_path_len {
3154                max_path_len = path_len;
3155                highest_permission = perm.access;
3156            } else if path_len == max_path_len {
3157                highest_permission = match (highest_permission, perm.access) {
3158                    (FsAccessPermission::ReadWrite, _)
3159                    | (FsAccessPermission::Read, FsAccessPermission::Write)
3160                    | (FsAccessPermission::Write, FsAccessPermission::Read) => {
3161                        FsAccessPermission::ReadWrite
3162                    }
3163                    (FsAccessPermission::None, perm) => perm,
3164                    (existing_perm, _) => existing_perm,
3165                };
3166            }
3167        }
3168        (max_path_len > 0).then_some(highest_permission)
3169    };
3170    let grants_write = |path: &Path| {
3171        matches!(
3172            effective_permission(path),
3173            Some(FsAccessPermission::Write | FsAccessPermission::ReadWrite)
3174        )
3175    };
3176
3177    let unsafe_write_paths = permissions
3178        .iter()
3179        .filter(|perm| {
3180            matches!(perm.access, FsAccessPermission::Write | FsAccessPermission::ReadWrite)
3181        })
3182        .filter(|perm| {
3183            let perm_path = canonicalize_through_existing_ancestor(&perm.path);
3184            shared_dep_dirs.iter().any(|dep| {
3185                if perm_path.starts_with(dep) {
3186                    grants_write(&perm_path)
3187                } else if dep.starts_with(&perm_path) {
3188                    grants_write(dep)
3189                } else {
3190                    false
3191                }
3192            })
3193        })
3194        .map(|perm| format!("  - {}", perm.path.display()))
3195        .collect::<Vec<_>>();
3196    if !unsafe_write_paths.is_empty() {
3197        bail!(
3198            "Mutation testing is unsafe with write-capable `fs_permissions` that can \
3199             reach the symlinked dependency trees (`lib`/`node_modules`/`dependencies`); \
3200             per-mutant workspaces share those trees, so `vm.writeFile` calls would race \
3201             against or corrupt your real dependencies. Restrict the following \
3202             `fs_permissions` entries to read-only or scope them away from dependency \
3203             paths:\n{}",
3204            unsafe_write_paths.join("\n")
3205        );
3206    }
3207    Ok(())
3208}
3209
3210/// Builds a figment dictionary from `key => Option<value>` pairs, skipping unset values.
3211macro_rules! dict {
3212    ($($key:literal => $value:expr),* $(,)?) => {{
3213        let mut dict = Dict::default();
3214        $(if let Some(value) = $value {
3215            dict.insert($key.to_string(), Value::from(value));
3216        })*
3217        dict
3218    }};
3219}
3220
3221/// Renders an optional path for the figment provider.
3222fn path_string(path: &Option<PathBuf>) -> Option<String> {
3223    path.as_ref().map(|path| path.to_string_lossy().to_string())
3224}
3225
3226impl Provider for TestArgs {
3227    fn metadata(&self) -> Metadata {
3228        Metadata::named("Core Build Args Provider")
3229    }
3230
3231    fn data(&self) -> Result<Map<Profile, Dict>, figment::Error> {
3232        let fuzz = dict! {
3233            "seed" => self.fuzz_seed.map(|seed| seed.to_string()),
3234            "runs" => self.fuzz_runs,
3235            "run" => self.fuzz_run,
3236            "worker" => self.fuzz_worker,
3237            "timeout" => self.fuzz_timeout,
3238            "dictionary_weight" => self.fuzz_dictionary_weight,
3239            "max_fuzz_dictionary_addresses" => self.fuzz_dictionary_addresses.clone(),
3240            "max_fuzz_dictionary_values" => self.fuzz_dictionary_values.clone(),
3241            "max_fuzz_dictionary_literals" => self.fuzz_dictionary_literals.clone(),
3242            "corpus_random_sequence_weight" => self.fuzz_corpus_random_sequence_weight,
3243            "corpus_dir" => path_string(&self.fuzz_corpus_dir),
3244            "frontier_dir" => path_string(&self.fuzz_frontier_dir),
3245            "frontier_limit" => self.fuzz_frontier_limit,
3246            "payable_value_weight" => self.fuzz_payable_value_weight,
3247            "mutation_weight_splice" => self.fuzz_mutation_weight_splice,
3248            "mutation_weight_repeat" => self.fuzz_mutation_weight_repeat,
3249            "mutation_weight_interleave" => self.fuzz_mutation_weight_interleave,
3250            "mutation_weight_prefix" => self.fuzz_mutation_weight_prefix,
3251            "mutation_weight_suffix" => self.fuzz_mutation_weight_suffix,
3252            "mutation_weight_abi" => self.fuzz_mutation_weight_abi,
3253            "mutation_weight_cmp" => self.fuzz_mutation_weight_cmp,
3254        };
3255        let invariant = dict! {
3256            "runs" => self.invariant_runs_override,
3257            "depth" => self.invariant_depth,
3258            "min_depth" => self.invariant_min_depth,
3259            "depth_mode" => self.invariant_depth_mode.map(Value::serialize).transpose()?,
3260            "workers" => self.invariant_workers.map(Value::serialize).transpose()?,
3261            "dictionary_weight" => self.invariant_dictionary_weight,
3262            "max_fuzz_dictionary_addresses" => self.invariant_dictionary_addresses.clone(),
3263            "max_fuzz_dictionary_values" => self.invariant_dictionary_values.clone(),
3264            "max_fuzz_dictionary_literals" => self.invariant_dictionary_literals.clone(),
3265            "corpus_random_sequence_weight" => self.invariant_corpus_random_sequence_weight,
3266            "corpus_random_sequence_weight_configured" =>
3267                self.invariant_corpus_random_sequence_weight.map(|_| true),
3268            "corpus_dir" => path_string(&self.invariant_corpus_dir),
3269            "frontier_dir" => path_string(&self.invariant_frontier_dir),
3270            "frontier_limit" => self.invariant_frontier_limit,
3271            "payable_value_weight" => self.invariant_payable_value_weight,
3272            "timeout" => self.invariant_timeout_override,
3273            "mutation_weight_splice" => self.invariant_mutation_weight_splice,
3274            "mutation_weight_repeat" => self.invariant_mutation_weight_repeat,
3275            "mutation_weight_interleave" => self.invariant_mutation_weight_interleave,
3276            "mutation_weight_prefix" => self.invariant_mutation_weight_prefix,
3277            "mutation_weight_suffix" => self.invariant_mutation_weight_suffix,
3278            "mutation_weight_abi" => self.invariant_mutation_weight_abi,
3279            "mutation_weight_cmp" => self.invariant_mutation_weight_cmp,
3280        };
3281        let symbolic = dict! {
3282            "enabled" => self.symbolic.then_some(true),
3283            "seed_corpus" => self.symbolic_seed_corpus.then_some(true),
3284            "use_fuzz_corpus" => self.symbolic_use_fuzz_corpus.then_some(true),
3285            "corpus_seed_limit" => self.symbolic_corpus_seed_limit,
3286            "use_fuzz_frontiers" => self.symbolic_use_fuzz_frontiers.then_some(true),
3287            "live" => self.symbolic_live.then_some(true),
3288            "check_invariant_frontiers" =>
3289                self.symbolic_check_invariant_frontiers.then_some(true),
3290            "frontier_limit" => self.symbolic_frontier_limit,
3291            "frontier_ids" => self.symbolic_frontier_ids.clone(),
3292            "frontier_pcs" => self.symbolic_frontier_pcs.clone(),
3293            "frontier_selectors" => self.symbolic_frontier_selectors.clone(),
3294            "solver" => self.symbolic_solver.clone(),
3295            "solver_command" => self.symbolic_solver_command.clone(),
3296            "solver_portfolio" => self.symbolic_solver_portfolio.clone(),
3297            "timeout" => self.symbolic_timeout,
3298            "loop" => self.symbolic_loop,
3299            "depth" => self.symbolic_depth,
3300            "width" => self.symbolic_width,
3301            "max_depth" => self.symbolic_max_depth,
3302            "max_paths" => self.symbolic_max_paths,
3303            "invariant_depth" => self.symbolic_invariant_depth,
3304            "max_solver_queries" => self.symbolic_max_solver_queries,
3305            "default_dynamic_length" => self.symbolic_default_dynamic_length,
3306            "max_dynamic_length" => self.symbolic_max_dynamic_length,
3307            "array_lengths" => self.symbolic_array_lengths.clone(),
3308            "max_calldata_bytes" => self.symbolic_max_calldata_bytes,
3309            "symbolic_call_targets" => self.symbolic_call_targets.then_some(true),
3310            "dump_smt" => self.symbolic_dump_smt.then_some(true),
3311            "storage_layout" => self.symbolic_storage_layout.clone(),
3312        };
3313        let mutation = dict! {
3314            "timeout" => self.mutation_timeout,
3315            "optimizer_runs" => self.mutation_optimizer_runs,
3316            "via_ir" => self.mutation_via_ir,
3317        };
3318
3319        let mut dict = dict! {
3320            "fuzz" => Some(fuzz),
3321            "invariant" => (!invariant.is_empty()).then_some(invariant),
3322            "symbolic" => Some(symbolic),
3323            "etherscan_api_key" =>
3324                self.etherscan_api_key.as_ref().filter(|s| !s.trim().is_empty()).cloned(),
3325            "show_progress" => self.show_progress.then_some(true),
3326            "decode_external_storage" => self.decode_external_storage.then_some(true),
3327        };
3328        // Mutation-testing CLI overrides
3329        if !mutation.is_empty() {
3330            dict.insert("mutation".to_string(), mutation.into());
3331        }
3332        Ok(Map::from([(Config::selected_profile(), dict)]))
3333    }
3334}
3335
3336/// Spawns the backend of a test run, starting on the configured fork, if any.
3337fn spawn_backend<FEN: FoundryEvmNetwork>(
3338    config: &Config,
3339    evm_opts: &EvmOpts,
3340) -> Result<Backend<FEN>> {
3341    // Configure the hardfork before seeding network state, using the resolved fork.
3342    let configure_env = |env: &mut _, context| {
3343        resolve_execution_spec::<EvmFactoryFor<FEN>>(
3344            config.evm_version,
3345            config.hardfork,
3346            env,
3347            context,
3348            None,
3349        );
3350    };
3351    if let Some(fork) = evm_opts.get_fork(config, evm_opts.env.chain_id.unwrap_or_default(), None) {
3352        Backend::spawn_fork(fork, configure_env)
3353    } else {
3354        let mut env = evm_opts.local_evm_env::<FEN>();
3355        configure_env(&mut env, ExecutionSpecContext::Local);
3356        Backend::spawn(None, env)
3357    }
3358}
3359
3360fn parse_opcode(s: &str) -> Result<OpCode, String> {
3361    OpCode::parse(s).ok_or_else(|| format!("invalid opcode: {s}"))
3362}
3363
3364const fn apply_mutation_compiler_overrides(config: &mut Config) {
3365    if let Some(optimizer_runs) = config.mutation.optimizer_runs {
3366        let default_optimizer_settings =
3367            matches!(config.optimizer, Some(false)) && matches!(config.optimizer_runs, Some(200));
3368        config.optimizer_runs = Some(optimizer_runs as usize);
3369        if default_optimizer_settings {
3370            config.optimizer = None;
3371        }
3372        config.normalize_optimizer_settings();
3373    }
3374    if let Some(via_ir) = config.mutation.via_ir {
3375        config.via_ir = via_ir;
3376    }
3377}
3378
3379/// Returns whether an ABI-discovered contract could be included in the test runner.
3380fn is_runnable_test_contract(
3381    output: &ProjectCompileOutput,
3382    config: &Config,
3383    id: &ArtifactId,
3384    artifact: &ConfigurableContractArtifact,
3385    abi: &JsonAbi,
3386) -> bool {
3387    if abi.constructor.as_ref().is_some_and(|constructor| !constructor.inputs.is_empty())
3388        || is_external_artifact(&id.build_id)
3389            && artifact.get_bytecode_bytes().is_none_or(|bytecode| bytecode.is_empty())
3390    {
3391        return false;
3392    }
3393
3394    let contract_name = id.name.split('.').next().unwrap_or(&id.name);
3395    let path = config.root.join(&id.source);
3396    let compiler = output.parser().solc().compiler();
3397    compiler.enter_sequential(|compiler| {
3398        if let Some((_, source)) = compiler.gcx().get_ast_source(&path)
3399            && let Some(ast) = &source.ast
3400            && let Some(contract) = ast.items.iter().find_map(|item| match &item.kind {
3401                ItemKind::Contract(contract) if contract.name.as_str() == contract_name => {
3402                    Some(contract)
3403                }
3404                _ => None,
3405            })
3406        {
3407            return matches!(
3408                contract.kind,
3409                SolarContractKind::Contract | SolarContractKind::Library
3410            );
3411        }
3412        true
3413    })
3414}
3415
3416/// Returns the deployable contracts in `output` that match `filter`, with project-relative ids.
3417fn matching_test_contracts<'a>(
3418    output: &'a ProjectCompileOutput,
3419    config: &'a Config,
3420    matcher: &'a TestFunctionMatcher<'a>,
3421    filter: &'a ProjectPathsAwareFilter,
3422) -> impl Iterator<Item = (ArtifactId, &'a ConfigurableContractArtifact, &'a JsonAbi)> + 'a {
3423    output.artifact_ids().filter_map(move |(id, artifact)| {
3424        let abi = artifact.abi.as_ref()?;
3425        let id = id.with_stripped_file_prefixes(&config.root);
3426        let deployable = abi.constructor.as_ref().is_none_or(|c| c.inputs.is_empty());
3427        (deployable && matcher.matches_contract(filter, &id, abi)).then_some((id, artifact, abi))
3428    })
3429}
3430
3431/// Lists all matching tests without building a runner.
3432fn list_from_output(
3433    output: &ProjectCompileOutput,
3434    config: &Config,
3435    inline_config: &InlineConfig,
3436    filter: &ProjectPathsAwareFilter,
3437    fuzz_only: bool,
3438    symbolic_artifact_replay: Option<&SymbolicArtifactReplayConfig>,
3439) -> Result<TestOutcome> {
3440    let matcher = TestFunctionMatcher::new(config, inline_config, symbolic_artifact_replay);
3441    let mut results = BTreeMap::<String, BTreeMap<String, Vec<String>>>::new();
3442    for (id, _, abi) in matching_test_contracts(output, config, &matcher, filter) {
3443        let identifier = id.identifier();
3444        let generated_symbolic_regression = is_generated_symbolic_regression_contract(abi);
3445        let tests = abi
3446            .functions()
3447            .filter(|func| {
3448                let kind =
3449                    matcher.test_function_kind(&identifier, func, generated_symbolic_regression);
3450                (!fuzz_only
3451                    || matches!(
3452                        kind,
3453                        TestFunctionKind::FuzzTest { .. } | TestFunctionKind::InvariantTest
3454                    ))
3455                    && filter.matches_test_function_kind_in_contract(&identifier, func, kind)
3456            })
3457            .map(|func| func.name.clone())
3458            .collect::<Vec<_>>();
3459        if !tests.is_empty() {
3460            results.entry(id.source.display().to_string()).or_default().insert(id.name, tests);
3461        }
3462    }
3463
3464    if shell::is_json() {
3465        sh_println!("{}", serde_json::to_string(&results)?)?;
3466    } else {
3467        for (file, contracts) in &results {
3468            sh_println!("{file}")?;
3469            for (contract, tests) in contracts {
3470                sh_println!("  {contract}")?;
3471                sh_println!("    {}\n", tests.join("\n    "))?;
3472            }
3473        }
3474    }
3475    Ok(TestOutcome::empty(None, false))
3476}
3477
3478fn matching_fuzz_replay_targets(
3479    output: &ProjectCompileOutput,
3480    config: &Config,
3481    inline_config: &InlineConfig,
3482    filter: &ProjectPathsAwareFilter,
3483    selector: &[u8],
3484) -> Result<Vec<(String, String)>> {
3485    let matcher = TestFunctionMatcher::new(config, inline_config, None);
3486    let mut targets = Vec::new();
3487    for (id, artifact, abi) in matching_test_contracts(output, config, &matcher, filter) {
3488        let has_creation_code =
3489            artifact.get_bytecode_object().is_some_and(|object| match object.as_ref() {
3490                BytecodeObject::Bytecode(bytecode) => !bytecode.is_empty(),
3491                BytecodeObject::Unlinked(_) => true,
3492            });
3493        if !has_creation_code {
3494            continue;
3495        }
3496        let contract = id.identifier();
3497        let generated_symbolic_regression = is_generated_symbolic_regression_contract(abi);
3498        for func in abi.functions() {
3499            let kind = matcher.test_function_kind(&contract, func, generated_symbolic_regression);
3500            if !kind.is_fuzz_test()
3501                || !filter.matches_test_function_kind_in_contract(&contract, func, kind)
3502            {
3503                continue;
3504            }
3505            let function_config = inline_config_for(config, inline_config, &contract, Some(func))?;
3506            if effective_test_function_kind(kind, &function_config, func).is_fuzz_test()
3507                && func.selector() == selector
3508            {
3509                targets.push((contract.clone(), func.signature()));
3510            }
3511        }
3512    }
3513    Ok(targets)
3514}
3515
3516/// Merges `other` into `base` by extending suite results.
3517///
3518/// For suites that appear in both, test results are combined (function-level pass routing ensures
3519/// each function appears in exactly one pass, so there are no key conflicts in practice).
3520fn merge_outcomes(base: &mut TestOutcome, mut other: TestOutcome) {
3521    if let Some(other_results) = other.json_file_results.take() {
3522        let base_results = base.json_file_results.get_or_insert_with(|| base.results.clone());
3523        merge_suite_results(base_results, other_results);
3524    }
3525    merge_suite_results(&mut base.results, other.results);
3526    if let Some(decoder) = other.last_run_decoder {
3527        base.last_run_decoder = Some(decoder);
3528    }
3529}
3530
3531fn merge_suite_results(
3532    base: &mut BTreeMap<String, SuiteResult>,
3533    other: BTreeMap<String, SuiteResult>,
3534) {
3535    for (suite_id, other_suite) in other {
3536        if let Some(base_suite) = base.get_mut(&suite_id) {
3537            base_suite.test_results.extend(other_suite.test_results);
3538            base_suite.warnings.extend(other_suite.warnings);
3539            base_suite.duration = base_suite.duration.max(other_suite.duration);
3540        } else {
3541            base.insert(suite_id, other_suite);
3542        }
3543    }
3544}
3545
3546fn collect_matching_debug_tests(
3547    matching_tests: &BTreeMap<String, BTreeMap<String, Vec<String>>>,
3548) -> Vec<RerunFailure> {
3549    matching_tests
3550        .iter()
3551        .flat_map(|(source, contracts)| {
3552            contracts.iter().flat_map(move |(contract, tests)| {
3553                tests.iter().map(move |test| RerunFailure {
3554                    contract: format!("{source}:{contract}"),
3555                    test: test.clone(),
3556                })
3557            })
3558        })
3559        .collect()
3560}
3561
3562fn format_matching_debug_tests(matching_tests: &[RerunFailure]) -> String {
3563    if matching_tests.is_empty() {
3564        return String::new();
3565    }
3566    let mut output = String::from("\n\nMatching tests:");
3567    for test in matching_tests.iter().take(DEBUGGER_MATCHING_TESTS_DISPLAY_LIMIT) {
3568        write!(output, "\n  {}.{}", test.contract, test.test).unwrap();
3569    }
3570    if matching_tests.len() > DEBUGGER_MATCHING_TESTS_DISPLAY_LIMIT {
3571        write!(
3572            output,
3573            "\n  ... and {} more",
3574            matching_tests.len() - DEBUGGER_MATCHING_TESTS_DISPLAY_LIMIT
3575        )
3576        .unwrap();
3577    }
3578    output
3579}
3580
3581struct LastRunFailures {
3582    test_pattern: Option<Regex>,
3583    failures: Option<Vec<RerunFailure>>,
3584}
3585
3586/// Load persisted filter (with last test run failures) from file.
3587fn last_run_failures(config: &Config) -> LastRunFailures {
3588    let Ok(filter) = fs::read_to_string(&config.test_failures_file) else {
3589        return LastRunFailures { test_pattern: None, failures: None };
3590    };
3591
3592    if let Ok(failures) = serde_json::from_str::<RerunFailures>(&filter) {
3593        if failures.failures.is_empty() {
3594            return LastRunFailures { test_pattern: None, failures: None };
3595        }
3596        let test_pattern = failures
3597            .failures
3598            .iter()
3599            .map(|failure| regex::escape(&failure.test))
3600            .collect::<Vec<_>>()
3601            .join("|");
3602        let test_pattern = Regex::new(&test_pattern).ok();
3603        return LastRunFailures { test_pattern, failures: Some(failures.failures) };
3604    }
3605
3606    // Legacy format: a plain regex.
3607    let test_pattern = Regex::new(&filter)
3608        .inspect_err(|e| {
3609            _ = sh_warn!("failed to parse test filter from {:?}: {e}", config.test_failures_file)
3610        })
3611        .ok();
3612    LastRunFailures { test_pattern, failures: None }
3613}
3614
3615/// Replace the last run failures, clearing the record when the run succeeds.
3616fn persist_run_failures(config: &Config, outcome: &TestOutcome) {
3617    if outcome.failed() == 0 {
3618        let _ = fs::remove_file(&config.test_failures_file);
3619    } else if fs::create_file(&config.test_failures_file).is_ok() {
3620        let failures = outcome
3621            .results
3622            .iter()
3623            .flat_map(|(contract, suite)| {
3624                suite.test_results.iter().filter(|(_, result)| result.status.is_failure()).flat_map(
3625                    move |(test_name, test_result)| {
3626                        rerun_filter_matches(test_name, test_result)
3627                            .map(move |test| RerunFailure { contract: contract.clone(), test })
3628                    },
3629                )
3630            })
3631            .collect::<Vec<_>>();
3632
3633        if let Ok(output) = serde_json::to_string(&RerunFailures { version: 1, failures }) {
3634            let _ = fs::write(&config.test_failures_file, output);
3635        }
3636    }
3637}
3638
3639/// Returns the rerun keys of a failed test: its failed invariant predicates, or the test name when
3640/// no predicate failed.
3641fn rerun_filter_matches<'a>(
3642    test_name: &'a str,
3643    test_result: &'a TestResult,
3644) -> impl Iterator<Item = String> + 'a {
3645    let predicate_failures =
3646        test_result.invariant_failures.iter().filter_map(|failure| failure.predicate_name());
3647    let has_predicate_failures = predicate_failures.clone().next().is_some();
3648    let fallback = test_name.is_any_test().then(|| test_name.split('(').next()).flatten();
3649    predicate_failures
3650        .chain(fallback.into_iter().filter(move |_| !has_predicate_failures))
3651        .map(str::to_owned)
3652}
3653
3654/// Generate test report in JUnit XML report format.
3655fn junit_xml_report(results: &BTreeMap<String, SuiteResult>, verbosity: u8) -> Report {
3656    let mut total_duration = Duration::default();
3657    let mut junit_report = Report::new("Test run");
3658    junit_report.set_timestamp(Utc::now());
3659    for (suite_name, suite_result) in results {
3660        let mut test_suite = TestSuite::new(suite_name);
3661        total_duration += suite_result.duration;
3662        test_suite.set_time(suite_result.duration);
3663        test_suite.set_system_out(suite_result.summary());
3664        for (test_name, test_result) in &suite_result.test_results {
3665            add_junit_test_cases(&mut test_suite, test_name, test_result, verbosity);
3666        }
3667        junit_report.add_test_suite(test_suite);
3668    }
3669    junit_report.set_time(total_duration);
3670    junit_report
3671}
3672
3673/// Adds JUnit test cases for a test result.
3674///
3675/// Invariant campaigns are expanded into per-predicate and per-handler cases so CI can report
3676/// contract-level execution without losing failure attribution.
3677fn add_junit_test_cases(
3678    test_suite: &mut TestSuite,
3679    test_name: &str,
3680    test_result: &TestResult,
3681    verbosity: u8,
3682) {
3683    let output = JunitOutput::new(test_result, verbosity);
3684    let expanded_invariant = test_result.kind.is_invariant()
3685        && (!test_result.invariant_predicate_results.is_empty()
3686            || !test_result.invariant_handler_failures.is_empty());
3687
3688    if !expanded_invariant {
3689        add_junit_test_case(
3690            test_suite,
3691            test_name,
3692            test_result.status,
3693            test_result.reason.as_deref(),
3694            test_result.duration,
3695            output.system_out(test_result, test_name),
3696        );
3697        return;
3698    }
3699
3700    let mut add_expanded_case =
3701        |name: &str,
3702         status: TestStatus,
3703         reason: Option<&str>,
3704         counterexample: Option<&CounterExample>| {
3705            add_junit_test_case(
3706                test_suite,
3707                name,
3708                status,
3709                reason,
3710                test_result.duration,
3711                output.case_system_out(status, reason, name, counterexample),
3712            );
3713        };
3714
3715    if test_result.invariant_predicate_results.is_empty() {
3716        let failure = test_result.invariant_failures.first();
3717        let status = if failure.is_some() { TestStatus::Failure } else { TestStatus::Success };
3718        add_expanded_case(
3719            test_name,
3720            status,
3721            failure.map(|failure| failure.reason()),
3722            failure.and_then(|failure| failure.counterexample()),
3723        );
3724    } else {
3725        for predicate in &test_result.invariant_predicate_results {
3726            let failure = test_result
3727                .invariant_failures
3728                .iter()
3729                .find(|failure| failure.name() == predicate.name.as_str());
3730            add_expanded_case(
3731                &format!("{}()", predicate.name),
3732                predicate.status,
3733                predicate.reason.as_deref(),
3734                failure.and_then(|failure| failure.counterexample()),
3735            );
3736        }
3737    }
3738
3739    for failure in &test_result.invariant_handler_failures {
3740        add_expanded_case(
3741            &format!("handler {}", failure.name()),
3742            TestStatus::Failure,
3743            Some(failure.reason()),
3744            failure.counterexample(),
3745        );
3746    }
3747}
3748
3749/// Adds a single JUnit test case to the suite.
3750fn add_junit_test_case(
3751    test_suite: &mut TestSuite,
3752    test_name: &str,
3753    status: TestStatus,
3754    message: Option<&str>,
3755    duration: Duration,
3756    system_out: String,
3757) {
3758    let mut test_status = match status {
3759        TestStatus::Success => TestCaseStatus::success(),
3760        TestStatus::Failure => TestCaseStatus::non_success(NonSuccessKind::Failure),
3761        TestStatus::Skipped => TestCaseStatus::skipped(),
3762    };
3763    if let Some(message) = message {
3764        test_status.set_message(message);
3765    }
3766    let mut test_case = TestCase::new(test_name, test_status);
3767    test_case.set_time(duration);
3768    test_case.set_system_out(system_out);
3769    test_suite.add_test_case(test_case);
3770}
3771
3772/// Helper for assembling JUnit output strings.
3773struct JunitOutput {
3774    result_report: TestKindReport,
3775    logs: Option<Vec<String>>,
3776}
3777
3778impl JunitOutput {
3779    fn new(test_result: &TestResult, verbosity: u8) -> Self {
3780        Self {
3781            result_report: test_result.kind.report(),
3782            logs: (verbosity >= 2 && !test_result.logs.is_empty())
3783                .then(|| decode_console_logs(&test_result.logs)),
3784        }
3785    }
3786
3787    /// Renders the suite-level `system-out` payload.
3788    fn system_out(&self, test_result: &TestResult, test_name: &str) -> String {
3789        let mut sys_out = format!("{test_result} {test_name} {}", self.result_report);
3790        self.append_logs(&mut sys_out);
3791        sys_out
3792    }
3793
3794    /// Renders the case-level `system-out` payload.
3795    fn case_system_out(
3796        &self,
3797        status: TestStatus,
3798        message: Option<&str>,
3799        test_name: &str,
3800        counterexample: Option<&CounterExample>,
3801    ) -> String {
3802        let mut sys_out = match (status, message) {
3803            (TestStatus::Success, _) => "[PASS]".to_string(),
3804            (TestStatus::Failure, message) => format!("[FAIL: {}]", message.unwrap_or_default()),
3805            (TestStatus::Skipped, Some(message)) => format!("[SKIP: {message}]"),
3806            (TestStatus::Skipped, None) => "[SKIP]".to_string(),
3807        };
3808        write!(sys_out, " {test_name} {}", self.result_report).unwrap();
3809        if let Some(CounterExample::Sequence(original, sequence)) = counterexample {
3810            writeln!(sys_out, "\n\t[Sequence] (original: {original}, shrunk: {})", sequence.len())
3811                .unwrap();
3812            for ex in sequence {
3813                writeln!(sys_out, "{ex}").unwrap();
3814            }
3815        }
3816        self.append_logs(&mut sys_out);
3817        sys_out
3818    }
3819
3820    /// Appends captured console logs to the output payload.
3821    fn append_logs(&self, sys_out: &mut String) {
3822        if let Some(logs) = &self.logs {
3823            write!(sys_out, "\\nLogs:\\n").unwrap();
3824            for log in logs {
3825                write!(sys_out, "  {log}\\n").unwrap();
3826            }
3827        }
3828    }
3829}
3830
3831#[cfg(test)]
3832mod tests {
3833    use super::*;
3834
3835    #[test]
3836    fn parses_opcode_names_exactly() {
3837        assert_eq!(parse_opcode("SSTORE"), Ok(OpCode::SSTORE));
3838        assert_eq!(parse_opcode("PUSH32"), Ok(OpCode::PUSH32));
3839        assert_eq!(parse_opcode("sstore"), Err("invalid opcode: sstore".to_string()));
3840        assert_eq!(parse_opcode("NOPE"), Err("invalid opcode: NOPE".to_string()));
3841    }
3842
3843    /// Parses `args` with the given environment variables set, restoring the previous values.
3844    fn parse_with_env(vars: &[(&str, &str)], args: &[&str]) -> TestArgs {
3845        static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
3846        let _guard = ENV_LOCK.lock().unwrap();
3847        let previous = vars.iter().map(|(name, _)| std::env::var_os(name)).collect::<Vec<_>>();
3848        for (name, value) in vars {
3849            unsafe { std::env::set_var(name, value) };
3850        }
3851        let parsed =
3852            TestArgs::try_parse_from(["foundry-cli"].into_iter().chain(args.iter().copied()));
3853        for ((name, _), previous) in vars.iter().zip(previous) {
3854            match previous {
3855                Some(previous) => unsafe { std::env::set_var(name, previous) },
3856                None => unsafe { std::env::remove_var(name) },
3857            }
3858        }
3859        parsed.unwrap()
3860    }
3861
3862    #[test]
3863    fn parses_flags_without_cli_coverage() {
3864        assert!(TestArgs::parse_from(["foundry-cli", "-vw"]).watch.watch.is_some());
3865        assert!(TestArgs::parse_from(["foundry-cli", "--compact-labels"]).tracing.compact_labels);
3866        // <https://github.com/foundry-rs/foundry/issues/5913>
3867        let args =
3868            TestArgs::parse_from(["foundry-cli", "-vvv", "--gas-report", "--fuzz-seed", "0x10"]);
3869        assert!(args.fuzz_seed.is_some());
3870        let args = TestArgs::parse_from(["foundry-cli", "--invariant-workers", "auto"]);
3871        assert_eq!(args.invariant_workers, Some(InvariantWorkers::Auto));
3872        assert_eq!(
3873            figment::Figment::from(&args)
3874                .extract_inner::<InvariantWorkers>("invariant.workers")
3875                .unwrap(),
3876            InvariantWorkers::Auto
3877        );
3878    }
3879
3880    #[test]
3881    fn parses_env_vars() {
3882        let args = parse_with_env(
3883            &[
3884                ("FOUNDRY_INVARIANT_WORKERS", "auto"),
3885                ("FOUNDRY_FUZZ_CORPUS_DIR", "env_fuzz_corpus"),
3886                ("FOUNDRY_INVARIANT_CORPUS_DIR", "env_invariant_corpus"),
3887            ],
3888            &[],
3889        );
3890        assert_eq!(args.invariant_workers, Some(InvariantWorkers::Auto));
3891        assert_eq!(args.fuzz_corpus_dir, Some(PathBuf::from("env_fuzz_corpus")));
3892        assert_eq!(args.invariant_corpus_dir, Some(PathBuf::from("env_invariant_corpus")));
3893    }
3894
3895    #[test]
3896    fn showmap_override_validates_path_component_names() {
3897        let mut args = TestArgs::parse_from(["foundry-cli"]);
3898        args.set_showmap_override(ShowmapConfig {
3899            out_dir: PathBuf::from("showmap"),
3900            approach: "../outside".to_string(),
3901            trial: "trial".to_string(),
3902            per_input: false,
3903            domain: ShowmapDomain::Evm,
3904            corpus_dir: None,
3905            emit_files: false,
3906        });
3907
3908        let err = args.showmap_config().unwrap_err().to_string();
3909        assert!(err.contains("expected a single file-name component"), "{err}");
3910    }
3911
3912    #[test]
3913    fn debugger_test_candidates_preserve_exact_suite_ids() {
3914        let matching = BTreeMap::from([(
3915            "test/Counter.t.sol".to_string(),
3916            BTreeMap::from([(
3917                "CounterTest".to_string(),
3918                vec!["testFuzz_SetNumber(uint256)".to_string(), "test_Increment()".to_string()],
3919            )]),
3920        )]);
3921
3922        let candidates = collect_matching_debug_tests(&matching);
3923
3924        assert_eq!(candidates[0].contract, "test/Counter.t.sol:CounterTest");
3925        assert_eq!(candidates[0].test, "testFuzz_SetNumber(uint256)");
3926        assert_eq!(candidates[1].test, "test_Increment()");
3927        assert_eq!(
3928            format_matching_debug_tests(&candidates),
3929            "\n\nMatching tests:\n  test/Counter.t.sol:CounterTest.testFuzz_SetNumber(uint256)\n  test/Counter.t.sol:CounterTest.test_Increment()"
3930        );
3931    }
3932
3933    #[test]
3934    fn fuzz_run_adapter_writes_unified_campaign_dials_sparsely() {
3935        let args = FuzzRunArgs::parse_from([
3936            "foundry-cli",
3937            "--runs",
3938            "9",
3939            "--timeout",
3940            "3",
3941            "--seed",
3942            "0x10",
3943            "--depth",
3944            "7",
3945            "--workers",
3946            "2",
3947            "--frontier-dir",
3948            "frontiers",
3949            "--frontier-limit",
3950            "17",
3951        ]);
3952        let args = TestArgs::from_fuzz_run(args);
3953        let figment = figment::Figment::from(&args);
3954
3955        assert_eq!(figment.extract_inner::<u64>("fuzz.runs").unwrap(), 9);
3956        assert_eq!(figment.extract_inner::<u64>("fuzz.timeout").unwrap(), 3);
3957        assert_eq!(figment.extract_inner::<String>("fuzz.seed").unwrap(), "16");
3958        assert_eq!(figment.extract_inner::<u64>("invariant.runs").unwrap(), 9);
3959        assert_eq!(figment.extract_inner::<u32>("invariant.timeout").unwrap(), 3);
3960        assert_eq!(figment.extract_inner::<u32>("invariant.depth").unwrap(), 7);
3961        assert_eq!(
3962            figment.extract_inner::<PathBuf>("fuzz.frontier_dir").unwrap(),
3963            PathBuf::from("frontiers")
3964        );
3965        assert_eq!(figment.extract_inner::<usize>("fuzz.frontier_limit").unwrap(), 17);
3966        assert_eq!(
3967            figment.extract_inner::<PathBuf>("invariant.frontier_dir").unwrap(),
3968            PathBuf::from("frontiers")
3969        );
3970        assert_eq!(figment.extract_inner::<usize>("invariant.frontier_limit").unwrap(), 17);
3971        assert_eq!(
3972            figment.extract_inner::<InvariantWorkers>("invariant.workers").unwrap(),
3973            InvariantWorkers::Fixed(std::num::NonZeroUsize::new(2).unwrap())
3974        );
3975    }
3976
3977    #[test]
3978    fn fuzz_run_adapter_writes_invariant_workers_sparsely() {
3979        let args = TestArgs::from_fuzz_run(FuzzRunArgs::parse_from(["foundry-cli"]));
3980        let figment = figment::Figment::from(&args);
3981
3982        assert_eq!(args.invariant_workers, None);
3983        assert!(figment.extract_inner::<InvariantWorkers>("invariant.workers").is_err());
3984    }
3985
3986    #[test]
3987    fn mutation_compiler_overrides_are_extracted() {
3988        let args = TestArgs::parse_from([
3989            "foundry-cli",
3990            "--mutate",
3991            "--mutation-optimizer-runs",
3992            "1",
3993            "--mutation-via-ir",
3994            "false",
3995        ]);
3996        let figment = figment::Figment::from(&args);
3997        assert_eq!(figment.extract_inner::<u32>("mutation.optimizer_runs").unwrap(), 1);
3998        assert!(!figment.extract_inner::<bool>("mutation.via_ir").unwrap());
3999    }
4000
4001    #[test]
4002    fn mutation_compiler_overrides_update_only_mutation_config_clone() {
4003        let mut config = Config {
4004            optimizer_runs: Some(999),
4005            via_ir: true,
4006            mutation: foundry_config::MutationConfig {
4007                optimizer_runs: Some(1),
4008                via_ir: Some(false),
4009                ..Default::default()
4010            },
4011            ..Default::default()
4012        };
4013
4014        apply_mutation_compiler_overrides(&mut config);
4015
4016        assert_eq!(config.optimizer_runs, Some(1));
4017        assert!(!config.via_ir);
4018    }
4019
4020    #[test]
4021    fn mutation_optimizer_runs_normalize_default_optimizer_settings() {
4022        let mut config = Config {
4023            optimizer: Some(false),
4024            optimizer_runs: Some(200),
4025            mutation: foundry_config::MutationConfig {
4026                optimizer_runs: Some(1),
4027                ..Default::default()
4028            },
4029            ..Default::default()
4030        };
4031
4032        apply_mutation_compiler_overrides(&mut config);
4033
4034        assert_eq!(config.optimizer, Some(true));
4035        assert_eq!(config.optimizer_runs, Some(1));
4036    }
4037
4038    #[test]
4039    fn auto_fuzz_corpus_defaults_to_cache_failure_layout() {
4040        let mut args = TestArgs::parse_from(["foundry-cli"]);
4041        args.enable_fuzz_only_with_auto_fuzz_corpus();
4042        let mut config = Config::default();
4043
4044        args.apply_test_config_overrides(&mut config);
4045
4046        assert_eq!(
4047            config.fuzz.corpus.corpus_dir,
4048            Some(config.cache_path.join(AUTO_FUZZ_FAILURE_DIR).join(AUTO_CORPUS_DIR))
4049        );
4050        assert_eq!(config.invariant.corpus.corpus_dir, None);
4051    }
4052
4053    #[test]
4054    fn auto_fuzz_corpus_uses_configured_failure_persist_dirs() {
4055        let mut args = TestArgs::parse_from(["foundry-cli"]);
4056        args.enable_fuzz_only_with_auto_fuzz_corpus();
4057        let mut config = Config::default();
4058        config.fuzz.failure_persist_dir = Some(PathBuf::from("custom_fuzz_failures"));
4059
4060        args.apply_test_config_overrides(&mut config);
4061
4062        assert_eq!(
4063            config.fuzz.corpus.corpus_dir,
4064            Some(PathBuf::from("custom_fuzz_failures").join(AUTO_CORPUS_DIR))
4065        );
4066        assert_eq!(config.invariant.corpus.corpus_dir, None);
4067    }
4068
4069    #[test]
4070    fn auto_fuzz_corpus_preserves_configured_corpus_dirs() {
4071        let mut args = TestArgs::parse_from(["foundry-cli"]);
4072        args.enable_fuzz_only_with_auto_fuzz_corpus();
4073        let mut config = Config::default();
4074        config.fuzz.corpus.corpus_dir = Some(PathBuf::from("configured_fuzz_corpus"));
4075        config.invariant.corpus.corpus_dir = Some(PathBuf::from("configured_invariant_corpus"));
4076
4077        args.apply_test_config_overrides(&mut config);
4078
4079        assert_eq!(config.fuzz.corpus.corpus_dir, Some(PathBuf::from("configured_fuzz_corpus")));
4080        assert_eq!(
4081            config.invariant.corpus.corpus_dir,
4082            Some(PathBuf::from("configured_invariant_corpus"))
4083        );
4084    }
4085
4086    #[test]
4087    fn fuzz_only_does_not_enable_auto_fuzz_corpus() {
4088        let mut args = TestArgs::parse_from(["foundry-cli"]);
4089        args.enable_fuzz_only();
4090        let mut config = Config::default();
4091
4092        args.apply_test_config_overrides(&mut config);
4093
4094        assert_eq!(config.fuzz.corpus.corpus_dir, None);
4095        assert_eq!(config.invariant.corpus.corpus_dir, None);
4096    }
4097
4098    #[test]
4099    fn debug_brutalize_includes_storage_layout_output() {
4100        let args = TestArgs::parse_from(["foundry-cli", "--debug", "--brutalize"]);
4101        let mut config = Config::default();
4102
4103        args.apply_test_config_overrides(&mut config);
4104
4105        assert_eq!(config.extra_output, vec![ContractOutputSelection::StorageLayout]);
4106        assert!(config.build_info);
4107    }
4108
4109    #[test]
4110    fn fuzz_and_invariant_config_flags() {
4111        let args = TestArgs::parse_from([
4112            "foundry-cli",
4113            "--fuzz-dictionary-weight",
4114            "35",
4115            "--fuzz-dictionary-addresses",
4116            "max",
4117            "--fuzz-dictionary-values",
4118            "1234",
4119            "--fuzz-dictionary-literals",
4120            "4321",
4121            "--fuzz-corpus-random-sequence-weight",
4122            "55",
4123            "--fuzz-corpus-dir",
4124            "fuzz_corpus",
4125            "--fuzz-frontier-dir",
4126            "fuzz_frontiers",
4127            "--fuzz-frontier-limit",
4128            "7",
4129            "--fuzz-payable-value-weight",
4130            "12",
4131            "--fuzz-mutation-weight-splice",
4132            "4",
4133            "--fuzz-mutation-weight-abi",
4134            "3",
4135            "--fuzz-mutation-weight-cmp",
4136            "5",
4137            "--symbolic-use-fuzz-frontiers",
4138            "--symbolic-check-invariant-frontiers",
4139            "--symbolic-frontier-limit",
4140            "3",
4141            "--symbolic-frontier-ids",
4142            "4,9",
4143            "--symbolic-frontier-pcs",
4144            "123,456",
4145            "--symbolic-frontier-selectors",
4146            "0x12345678,deadbeef",
4147            "--invariant-depth",
4148            "300",
4149            "--invariant-min-depth",
4150            "20",
4151            "--invariant-depth-mode",
4152            "random",
4153            "--invariant-workers",
4154            "4",
4155            "--invariant-dictionary-weight",
4156            "45",
4157            "--invariant-dictionary-addresses",
4158            "8765",
4159            "--invariant-dictionary-values",
4160            "max",
4161            "--invariant-dictionary-literals",
4162            "6789",
4163            "--invariant-corpus-random-sequence-weight",
4164            "25",
4165            "--invariant-corpus-dir",
4166            "invariant_corpus",
4167            "--invariant-payable-value-weight",
4168            "34",
4169            "--invariant-mutation-weight-splice",
4170            "2",
4171            "--invariant-mutation-weight-cmp",
4172            "7",
4173        ]);
4174
4175        let config = Config::default().merge_inline_provider(&args).unwrap();
4176        assert_eq!(config.fuzz.dictionary.dictionary_weight, 35);
4177        assert_eq!(config.fuzz.dictionary.max_fuzz_dictionary_addresses, usize::MAX);
4178        assert_eq!(config.fuzz.dictionary.max_fuzz_dictionary_values, 1234);
4179        assert_eq!(config.fuzz.dictionary.max_fuzz_dictionary_literals, 4321);
4180        assert_eq!(config.fuzz.corpus.corpus_random_sequence_weight, 55);
4181        assert_eq!(config.fuzz.corpus.corpus_dir, Some(PathBuf::from("fuzz_corpus")));
4182        assert_eq!(config.fuzz.corpus.frontier_dir, Some(PathBuf::from("fuzz_frontiers")));
4183        assert_eq!(config.fuzz.corpus.frontier_limit, 7);
4184        assert_eq!(config.fuzz.corpus.payable_value_weight, 12);
4185        assert_eq!(config.fuzz.corpus.mutation_weights.mutation_weight_splice, 4);
4186        assert_eq!(config.fuzz.corpus.mutation_weights.mutation_weight_abi, 3);
4187        assert_eq!(config.fuzz.corpus.mutation_weights.mutation_weight_cmp, 5);
4188        assert!(config.symbolic.use_fuzz_frontiers);
4189        assert!(config.symbolic.check_invariant_frontiers);
4190        assert_eq!(config.symbolic.frontier_limit, 3);
4191        assert_eq!(config.symbolic.frontier_ids, vec![4, 9]);
4192        assert_eq!(config.symbolic.frontier_pcs, vec![123, 456]);
4193        assert_eq!(config.symbolic.frontier_selectors, vec!["0x12345678", "deadbeef"]);
4194        assert_eq!(config.invariant.depth, 300);
4195        assert_eq!(config.invariant.min_depth, 20);
4196        assert_eq!(config.invariant.depth_mode, InvariantDepthMode::Random);
4197        assert_eq!(config.invariant.dictionary.dictionary_weight, 45);
4198        assert_eq!(config.invariant.dictionary.max_fuzz_dictionary_addresses, 8765);
4199        assert_eq!(config.invariant.dictionary.max_fuzz_dictionary_values, usize::MAX);
4200        assert_eq!(config.invariant.dictionary.max_fuzz_dictionary_literals, 6789);
4201        assert_eq!(config.invariant.corpus.corpus_random_sequence_weight, 25);
4202        assert_eq!(config.invariant.corpus.corpus_dir, Some(PathBuf::from("invariant_corpus")));
4203        assert!(config.invariant.corpus_random_sequence_weight_configured);
4204        assert_eq!(
4205            config.invariant.workers,
4206            InvariantWorkers::Fixed(std::num::NonZeroUsize::new(4).unwrap())
4207        );
4208        assert!(config.invariant.workers_configured);
4209        assert_eq!(config.invariant.corpus.payable_value_weight, 34);
4210        assert_eq!(config.invariant.corpus.mutation_weights.mutation_weight_splice, 2);
4211        assert_eq!(config.invariant.corpus.mutation_weights.mutation_weight_cmp, 7);
4212    }
4213}