Skip to main content

forge/
result.rs

1//! Test outcomes.
2
3use crate::{
4    fuzz::{BaseCounterExample, BasicTxDetails},
5    gas_report::GasReport,
6};
7use alloy_primitives::{
8    Address, B256, Bytes, I256, Log, Selector, U256,
9    map::{AddressHashMap, HashMap},
10};
11use eyre::Report;
12use foundry_common::{ContractsByArtifact, get_contract_name, shell};
13use foundry_config::{SymbolicConfig, SymbolicExplorationOrder, SymbolicStorageLayout};
14use foundry_evm::{
15    core::{Breakpoints, evm::FoundryEvmNetwork},
16    coverage::HitMaps,
17    decode::SkipReason,
18    executors::{
19        RawCallResult,
20        invariant::{
21            CheckSequenceFailureSite, CheckSequenceOutcome, InvariantMetrics, LiveInvariantStats,
22        },
23    },
24    fuzz::{
25        CallDetails, CounterExample, FuzzCase, FuzzFixtures, FuzzTestResult,
26        strategies::EvmFuzzState,
27    },
28    traces::{CallTraceArena, CallTraceDecoder, TraceKind, Traces},
29};
30use foundry_evm_symbolic::{SymbolicStats, SymbolicStopReason, SymbolicStorageAssignment};
31use serde::{Deserialize, Serialize};
32use std::{
33    collections::{BTreeMap, BTreeSet, HashMap as Map},
34    fmt::{self, Write},
35    path::PathBuf,
36    sync::OnceLock,
37    time::Duration,
38};
39use yansi::Paint;
40
41const INVARIANT_CAMPAIGN_FALLBACK_NAME: &str = "Invariant campaign";
42const SYMBOLIC_RESULT_SCHEMA_VERSION: u32 = 1;
43pub const SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA: &str = "foundry:symbolic.counterexample@v1";
44pub const SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA_VERSION: u32 = 1;
45
46/// The aggregated result of a test run.
47#[derive(Clone, Debug)]
48pub struct TestOutcome {
49    /// The results of all test suites by their identifier (`path:contract_name`).
50    ///
51    /// Essentially `identifier => signature => result`.
52    pub results: BTreeMap<String, SuiteResult>,
53    /// Complete results for JSON file output, including suites hidden from fail-fast console
54    /// output.
55    pub(crate) json_file_results: Option<BTreeMap<String, SuiteResult>>,
56    /// Whether to allow test failures without failing the entire test run.
57    pub allow_failure: bool,
58    /// The decoder used to decode traces and logs.
59    ///
60    /// This is `None` if traces and logs were not decoded.
61    ///
62    /// Note that `Address` fields only contain the last executed test case's data.
63    pub last_run_decoder: Option<CallTraceDecoder>,
64    /// The gas report, if requested.
65    pub gas_report: Option<GasReport>,
66    /// Known contracts from the test run (used for coverage).
67    pub known_contracts: Option<ContractsByArtifact>,
68    /// The fuzz seed used for the test run.
69    pub fuzz_seed: Option<U256>,
70}
71
72impl TestOutcome {
73    /// Creates a new test outcome with the given results.
74    pub const fn new(
75        known_contracts: Option<ContractsByArtifact>,
76        results: BTreeMap<String, SuiteResult>,
77        allow_failure: bool,
78        fuzz_seed: Option<U256>,
79    ) -> Self {
80        Self {
81            results,
82            json_file_results: None,
83            allow_failure,
84            last_run_decoder: None,
85            gas_report: None,
86            known_contracts,
87            fuzz_seed,
88        }
89    }
90
91    /// Creates a new empty test outcome.
92    pub const fn empty(known_contracts: Option<ContractsByArtifact>, allow_failure: bool) -> Self {
93        Self::new(known_contracts, BTreeMap::new(), allow_failure, None)
94    }
95
96    /// Returns an iterator over all individual succeeding tests and their names.
97    pub fn successes(&self) -> impl Iterator<Item = (&String, &TestResult)> {
98        self.tests().filter(|(_, t)| t.status.is_success())
99    }
100
101    /// Returns an iterator over all individual skipped tests and their names.
102    pub fn skips(&self) -> impl Iterator<Item = (&String, &TestResult)> {
103        self.tests().filter(|(_, t)| t.status.is_skipped())
104    }
105
106    /// Returns an iterator over all individual failing tests and their names.
107    pub fn failures(&self) -> impl Iterator<Item = (&String, &TestResult)> {
108        self.tests().filter(|(_, t)| t.status.is_failure())
109    }
110
111    /// Returns an iterator over all individual tests and their names.
112    pub fn tests(&self) -> impl Iterator<Item = (&String, &TestResult)> {
113        self.results.values().flat_map(|suite| suite.tests())
114    }
115
116    /// Flattens the test outcome into a list of individual tests.
117    pub fn into_tests(self) -> impl Iterator<Item = SuiteTestResult> {
118        self.results.into_iter().flat_map(|(artifact_id, suite)| {
119            suite.test_results.into_iter().map(move |(signature, result)| SuiteTestResult {
120                artifact_id: artifact_id.clone(),
121                signature,
122                result,
123            })
124        })
125    }
126
127    /// Returns the number of tests that passed.
128    pub fn passed(&self) -> usize {
129        self.results.values().map(SuiteResult::passed).sum()
130    }
131
132    /// Returns the number of tests that were skipped.
133    pub fn skipped(&self) -> usize {
134        self.results.values().map(SuiteResult::skipped).sum()
135    }
136
137    /// Returns the number of tests that failed.
138    pub fn failed(&self) -> usize {
139        self.results.values().map(SuiteResult::failed).sum()
140    }
141
142    /// Returns `true` if any fuzz or invariant test failed.
143    pub fn has_fuzz_failures(&self) -> bool {
144        self.failures().any(|(_, t)| t.kind.is_fuzz() || t.kind.is_invariant())
145    }
146
147    /// Returns `true` if all failing tests can be meaningfully inspected with `forge test --debug`.
148    fn failed_tests_are_debuggable(&self) -> bool {
149        self.failures().all(|(_, result)| result.is_debuggable_failure())
150    }
151
152    /// Returns the shared parallel worker count of all failing invariant tests, if they agree.
153    fn invariant_workers_hint(&self) -> Option<usize> {
154        let mut workers = self.failures().filter_map(|(_, result)| result.kind.invariant_workers());
155        let first = workers.next()?;
156        (first > 1 && workers.all(|workers| workers == first)).then_some(first)
157    }
158
159    /// Sums up all the durations of all individual test suites.
160    ///
161    /// Note that this is not necessarily the wall clock time of the entire test run.
162    pub fn total_time(&self) -> Duration {
163        self.results.values().map(|suite| suite.duration).sum()
164    }
165
166    /// Formats the aggregated summary of all test suites into a string (for printing).
167    pub fn summary(&self, wall_clock_time: Duration) -> String {
168        let num_test_suites = self.results.len();
169        let suites = if num_test_suites == 1 { "suite" } else { "suites" };
170        let (passed, failed, skipped) = (self.passed(), self.failed(), self.skipped());
171        format!(
172            "\nRan {num_test_suites} test {suites} in {wall_clock_time:.2?} ({:.2?} CPU time): {} tests passed, {} failed, {} skipped ({} total tests)",
173            self.total_time(),
174            passed.green(),
175            failed.red(),
176            skipped.yellow(),
177            passed + failed + skipped
178        )
179    }
180
181    /// Checks if there are any failures and failures are disallowed.
182    pub fn ensure_ok(&self, silent: bool) -> eyre::Result<()> {
183        let failures = self.failures().count();
184        if self.allow_failure || failures == 0 {
185            return Ok(());
186        }
187
188        if shell::is_quiet() || silent {
189            std::process::exit(1);
190        }
191
192        sh_println!("\nFailing tests:")?;
193        for (suite_name, suite) in &self.results {
194            let failed = suite.failed();
195            if failed == 0 {
196                continue;
197            }
198
199            let term = if failed > 1 { "tests" } else { "test" };
200            sh_println!("Encountered {failed} failing {term} in {suite_name}")?;
201            for (name, result) in suite.failures() {
202                sh_println!("{}", result.short_result_with_suite(name, suite_name))?;
203            }
204            sh_println!()?;
205        }
206        sh_println!(
207            "Encountered a total of {} failing tests, {} tests succeeded",
208            failures.to_string().red(),
209            self.passed().to_string().green()
210        )?;
211
212        let test_word = if failures == 1 { "test" } else { "tests" };
213        sh_println!(
214            "\nTip: Run {} to retry only the {failures} failed {test_word}",
215            "`forge test --rerun`".cyan()
216        )?;
217        if self.failed_tests_are_debuggable() {
218            sh_println!(
219                "Tip: Run {} to inspect one failing test in the debugger",
220                "`forge test --debug --match-test <TEST_NAME>`".cyan()
221            )?;
222        }
223
224        // Print seed for fuzz/invariant test failures to enable reproduction.
225        if let Some(seed) = self.fuzz_seed
226            && self.has_fuzz_failures()
227        {
228            sh_println!(
229                "\nFuzz seed: {} (use {} to reproduce)",
230                format!("{seed:#x}").cyan(),
231                "`--fuzz-seed`".cyan()
232            )?;
233            if let Some(invariant_workers) = self.invariant_workers_hint() {
234                sh_println!(
235                    "Invariant workers: {invariant_workers} (use {} to reproduce)",
236                    format!("`--invariant-workers {invariant_workers}`").cyan()
237                )?;
238            }
239        }
240
241        std::process::exit(1);
242    }
243
244    /// Removes first test result, if any.
245    pub fn remove_first(&mut self) -> Option<(String, String, TestResult)> {
246        self.results.iter_mut().find_map(|(suite_name, suite)| {
247            let (test_name, result) = suite.test_results.pop_first()?;
248            Some((suite_name.clone(), test_name, result))
249        })
250    }
251}
252
253/// A set of test results for a single test suite, which is all the tests in a single contract.
254#[derive(Clone, Debug, Serialize)]
255pub struct SuiteResult {
256    /// Wall clock time it took to execute all tests in this suite.
257    #[serde(with = "foundry_common::serde_helpers::duration")]
258    pub duration: Duration,
259    /// Individual test results: `test fn signature -> TestResult`.
260    pub test_results: BTreeMap<String, TestResult>,
261    /// Generated warnings.
262    pub warnings: Vec<String>,
263}
264
265impl SuiteResult {
266    pub fn new(
267        duration: Duration,
268        test_results: BTreeMap<String, TestResult>,
269        mut warnings: Vec<String>,
270    ) -> Self {
271        // Add deprecated cheatcodes warning, if any of them used in current test suite.
272        let deprecated_cheatcodes = test_results
273            .values()
274            .flat_map(|result| result.deprecated_cheatcodes.iter().map(|(k, v)| (*k, *v)))
275            .collect::<HashMap<_, _>>();
276        if !deprecated_cheatcodes.is_empty() {
277            let mut warning =
278                "the following cheatcode(s) are deprecated and will be removed in future versions:"
279                    .to_string();
280            for (cheatcode, reason) in deprecated_cheatcodes {
281                write!(warning, "\n  {cheatcode}").unwrap();
282                if let Some(reason) = reason {
283                    write!(warning, ": {reason}").unwrap();
284                }
285            }
286            warnings.push(warning);
287        }
288
289        Self { duration, test_results, warnings }
290    }
291
292    /// Returns an iterator over all individual succeeding tests and their names.
293    pub fn successes(&self) -> impl Iterator<Item = (&String, &TestResult)> {
294        self.tests().filter(|(_, t)| t.status.is_success())
295    }
296
297    /// Returns an iterator over all individual skipped tests and their names.
298    pub fn skips(&self) -> impl Iterator<Item = (&String, &TestResult)> {
299        self.tests().filter(|(_, t)| t.status.is_skipped())
300    }
301
302    /// Returns an iterator over all individual failing tests and their names.
303    pub fn failures(&self) -> impl Iterator<Item = (&String, &TestResult)> {
304        self.tests().filter(|(_, t)| t.status.is_failure())
305    }
306
307    /// Returns the number of tests that passed.
308    pub fn passed(&self) -> usize {
309        self.test_results.values().filter(|t| t.status.is_success()).count()
310    }
311
312    /// Returns the number of tests that were skipped.
313    pub fn skipped(&self) -> usize {
314        self.test_results.values().map(TestResult::skipped_count).sum()
315    }
316
317    /// Returns the number of tests that failed.
318    pub fn failed(&self) -> usize {
319        self.test_results.values().filter(|t| t.status.is_failure()).count()
320    }
321
322    /// Iterator over all tests and their names
323    pub fn tests(&self) -> impl Iterator<Item = (&String, &TestResult)> {
324        self.test_results.iter()
325    }
326
327    /// Whether this test suite is empty.
328    pub fn is_empty(&self) -> bool {
329        self.test_results.is_empty()
330    }
331
332    /// The number of tests in this test suite.
333    pub fn len(&self) -> usize {
334        self.test_results.values().map(TestResult::logical_count).sum()
335    }
336
337    /// Sums up all the durations of all individual tests in this suite.
338    ///
339    /// Note that this is not necessarily the wall clock time of the entire test suite.
340    pub fn total_time(&self) -> Duration {
341        self.test_results.values().map(|result| result.duration).sum()
342    }
343
344    /// Returns the summary of a single test suite.
345    pub fn summary(&self) -> String {
346        let failed = self.failed();
347        let result = if failed == 0 { "ok".green() } else { "FAILED".red() };
348        format!(
349            "Suite result: {result}. {} passed; {} failed; {} skipped; finished in {:.2?} ({:.2?} CPU time)",
350            self.passed().green(),
351            failed.red(),
352            self.skipped().yellow(),
353            self.duration,
354            self.total_time(),
355        )
356    }
357}
358
359/// The result of a single test in a test suite.
360///
361/// This is flattened from a [`TestOutcome`].
362#[derive(Clone, Debug)]
363pub struct SuiteTestResult {
364    /// The identifier of the artifact/contract in the form:
365    /// `<artifact file name>:<contract name>`.
366    pub artifact_id: String,
367    /// The function signature of the Solidity test.
368    pub signature: String,
369    /// The result of the executed test.
370    pub result: TestResult,
371}
372
373impl SuiteTestResult {
374    /// Returns the gas used by the test.
375    pub const fn gas_used(&self) -> u64 {
376        self.result.kind.report().gas()
377    }
378
379    /// Returns the contract name of the artifact ID.
380    pub fn contract_name(&self) -> &str {
381        get_contract_name(&self.artifact_id)
382    }
383}
384
385/// The status of a test.
386#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
387pub enum TestStatus {
388    Success,
389    #[default]
390    Failure,
391    Skipped,
392}
393
394impl TestStatus {
395    /// Returns `true` if the test was successful.
396    #[inline]
397    pub const fn is_success(self) -> bool {
398        matches!(self, Self::Success)
399    }
400
401    /// Returns `true` if the test failed.
402    #[inline]
403    pub const fn is_failure(self) -> bool {
404        matches!(self, Self::Failure)
405    }
406
407    /// Returns `true` if the test was skipped.
408    #[inline]
409    pub const fn is_skipped(self) -> bool {
410        matches!(self, Self::Skipped)
411    }
412}
413
414/// A failure surfaced by an invariant test campaign — either a broken `invariant_*`
415/// predicate ([`Self::Predicate`]) or a handler-side assertion bug ([`Self::Handler`]).
416#[derive(Clone, Debug, Serialize, Deserialize)]
417#[serde(tag = "kind", rename_all = "snake_case")]
418pub enum InvariantFailure {
419    /// A broken `invariant_*` predicate.
420    Predicate {
421        /// Invariant function name (e.g. `invariant_cond3`).
422        name: String,
423        /// Revert reason or assertion failure message.
424        reason: String,
425        /// Counterexample sequence, when one is available.
426        #[serde(default, skip_serializing_if = "Option::is_none")]
427        counterexample: Option<CounterExample>,
428        /// Durable replay artifact for this counterexample, when one was written.
429        #[serde(default, skip_serializing_if = "Option::is_none")]
430        artifact: Option<SymbolicArtifactRef>,
431        /// Deterministic concrete minimization details for this sequence, when minimized.
432        #[serde(default, skip_serializing_if = "Option::is_none")]
433        minimization: Option<SymbolicCounterexampleMinimization>,
434        /// Path where the counterexample was persisted for re-running and shrinking.
435        persisted_path: PathBuf,
436        /// Whether this failure is the stable campaign anchor.
437        /// When `true` and this is the only single-predicate failure, the function name is
438        /// omitted on the `[FAIL: ...]` line (the trailing summary already identifies it).
439        #[serde(default)]
440        is_anchor: bool,
441    },
442    /// A handler-side assertion bug discovered during the campaign.
443    Handler {
444        /// Best-effort human-readable name of the failing call, e.g. `Counter::increment` or
445        /// `0xabc...::0x12345678` when the contract/function cannot be resolved.
446        name: String,
447        /// Address of the handler whose call asserted/reverted with an assertion.
448        reverter: Address,
449        /// 4-byte selector of the failing handler function.
450        selector: Selector,
451        /// Decoded revert/assert reason.
452        reason: String,
453        /// Counterexample sequence leading up to (and including) the failing call.
454        #[serde(default, skip_serializing_if = "Option::is_none")]
455        counterexample: Option<CounterExample>,
456        /// Durable replay artifact for this counterexample, when one was written.
457        #[serde(default, skip_serializing_if = "Option::is_none")]
458        artifact: Option<SymbolicArtifactRef>,
459    },
460}
461
462impl InvariantFailure {
463    /// Reason rendered on the `[FAIL: ...]` line.
464    pub fn reason(&self) -> &str {
465        match self {
466            Self::Predicate { reason, .. } | Self::Handler { reason, .. } => reason,
467        }
468    }
469
470    /// Human-readable name (invariant fn name, or `Contract::function` for handler bugs).
471    pub fn name(&self) -> &str {
472        match self {
473            Self::Predicate { name, .. } | Self::Handler { name, .. } => name,
474        }
475    }
476
477    /// Invariant predicate name, if this is a predicate failure.
478    pub fn predicate_name(&self) -> Option<&str> {
479        match self {
480            Self::Predicate { name, .. } => Some(name),
481            Self::Handler { .. } => None,
482        }
483    }
484
485    /// Counterexample sequence, when one is available.
486    pub const fn counterexample(&self) -> Option<&CounterExample> {
487        match self {
488            Self::Predicate { counterexample, .. } | Self::Handler { counterexample, .. } => {
489                counterexample.as_ref()
490            }
491        }
492    }
493
494    /// Durable replay artifact for this failure, when one was written.
495    pub const fn artifact(&self) -> Option<&SymbolicArtifactRef> {
496        match self {
497            Self::Predicate { artifact, .. } | Self::Handler { artifact, .. } => artifact.as_ref(),
498        }
499    }
500
501    /// Deterministic concrete minimization details for predicate failures.
502    pub const fn minimization(&self) -> Option<&SymbolicCounterexampleMinimization> {
503        match self {
504            Self::Predicate { minimization, .. } => minimization.as_ref(),
505            Self::Handler { .. } => None,
506        }
507    }
508}
509
510/// Pass/fail status for an invariant predicate evaluated inside a contract-level campaign.
511#[derive(Clone, Debug, Serialize, Deserialize)]
512pub struct InvariantPredicateResult {
513    /// Invariant function name (e.g. `invariant_balance`).
514    pub name: String,
515    /// Predicate status within the logical campaign.
516    pub status: TestStatus,
517    /// Revert reason or assertion message when the predicate failed.
518    #[serde(default, skip_serializing_if = "Option::is_none")]
519    pub reason: Option<String>,
520}
521
522/// Stable machine-readable outcome for `forge test --symbolic` JSON output.
523#[derive(Clone, Debug, Serialize, Deserialize)]
524pub struct SymbolicResult {
525    /// Schema version for the symbolic result object.
526    #[serde(default = "symbolic_result_schema_version")]
527    pub schema_version: u32,
528    /// Normalized symbolic outcome.
529    pub status: SymbolicResultStatus,
530    /// Incomplete reason when [`Self::status`] is [`SymbolicResultStatus::Incomplete`].
531    pub incomplete: Option<SymbolicIncomplete>,
532    /// Effective bounds used by this symbolic run.
533    pub bounds: SymbolicBounds,
534    /// Solver identity and counters collected during this run.
535    pub solver: SymbolicSolverMetadata,
536    /// Soundness assumptions that bound what a `pass` proves.
537    pub assumptions: Vec<SymbolicAssumption>,
538    /// Where an agent can find the concrete replay trace, when one was produced.
539    pub call_trace: SymbolicCallTrace,
540    /// Concrete replay metadata for counterexample candidates.
541    pub replay: SymbolicReplayMetadata,
542    /// Concrete counterexample data, when the solver produced a candidate.
543    pub counterexample: Option<SymbolicCounterexample>,
544    /// Fuzz corpus seeds imported into symbolic execution, when enabled.
545    #[serde(default, skip_serializing_if = "Option::is_none")]
546    pub corpus_seeds: Option<SymbolicCorpusSeedMetadata>,
547    /// Durable counterexample artifact, when one was written.
548    #[serde(default, skip_serializing_if = "Option::is_none")]
549    pub artifact: Option<SymbolicArtifactRef>,
550    /// Deterministic concrete minimization details, when a replayed counterexample was minimized.
551    #[serde(default, skip_serializing_if = "Option::is_none")]
552    pub minimization: Option<SymbolicCounterexampleMinimization>,
553}
554
555impl SymbolicResult {
556    /// Creates a symbolic pass result.
557    pub fn pass(config: &SymbolicConfig, stats: SymbolicStats) -> Self {
558        Self::base(config, stats)
559    }
560
561    /// Creates a symbolic counterexample result that concrete replay confirmed.
562    pub fn fail_counterexample(
563        config: &SymbolicConfig,
564        stats: SymbolicStats,
565        call_trace: SymbolicCallTrace,
566        counterexample: SymbolicCounterexample,
567    ) -> Self {
568        Self {
569            counterexample: Some(counterexample),
570            ..Self::fail_counterexample_sequence(config, stats, call_trace)
571        }
572    }
573
574    /// Creates a symbolic sequence counterexample result that concrete replay confirmed.
575    pub fn fail_counterexample_sequence(
576        config: &SymbolicConfig,
577        stats: SymbolicStats,
578        call_trace: SymbolicCallTrace,
579    ) -> Self {
580        Self {
581            status: SymbolicResultStatus::FailCounterexample,
582            replay: SymbolicReplayMetadata::confirmed(),
583            call_trace,
584            ..Self::base(config, stats)
585        }
586    }
587
588    /// Creates an incomplete symbolic result.
589    pub fn incomplete(
590        config: &SymbolicConfig,
591        kind: SymbolicStopReason,
592        reason: impl Into<String>,
593        stats: SymbolicStats,
594        replay: SymbolicReplayMetadata,
595        call_trace: SymbolicCallTrace,
596        counterexample: Option<SymbolicCounterexample>,
597    ) -> Self {
598        Self {
599            status: SymbolicResultStatus::Incomplete,
600            incomplete: Some(SymbolicIncomplete::new(kind, reason)),
601            replay,
602            call_trace,
603            counterexample,
604            ..Self::base(config, stats)
605        }
606    }
607
608    /// A passing result carrying the run's bounds, solver metadata and assumptions.
609    fn base(config: &SymbolicConfig, stats: SymbolicStats) -> Self {
610        Self {
611            schema_version: SYMBOLIC_RESULT_SCHEMA_VERSION,
612            status: SymbolicResultStatus::Pass,
613            incomplete: None,
614            bounds: SymbolicBounds::from_config(config),
615            solver: SymbolicSolverMetadata {
616                name: config.solver.clone(),
617                command: config.solver_command.clone(),
618                portfolio: config.solver_portfolio.clone(),
619                stats,
620            },
621            assumptions: SymbolicAssumption::default_assumptions(),
622            call_trace: SymbolicCallTrace::none(),
623            replay: SymbolicReplayMetadata::not_required(),
624            counterexample: None,
625            corpus_seeds: None,
626            artifact: None,
627            minimization: None,
628        }
629    }
630
631    /// Attaches fuzz corpus import metadata to this symbolic result.
632    pub fn with_corpus_seeds(mut self, corpus_seeds: SymbolicCorpusSeedMetadata) -> Self {
633        self.corpus_seeds = Some(corpus_seeds);
634        self
635    }
636
637    /// Attaches a durable replay artifact reference to this symbolic result.
638    pub fn with_artifact(mut self, artifact: SymbolicArtifactRef) -> Self {
639        self.artifact = Some(artifact);
640        self
641    }
642
643    /// Attaches deterministic minimization metadata to this symbolic result.
644    pub fn with_minimization(mut self, minimization: SymbolicCounterexampleMinimization) -> Self {
645        self.minimization = Some(minimization);
646        self
647    }
648}
649
650/// Fuzz corpus import metadata for a symbolic run.
651#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
652pub struct SymbolicCorpusSeedMetadata {
653    /// Corpus root used for the current test, after contract/test path expansion.
654    pub corpus_dir: Option<PathBuf>,
655    /// Maximum imported seeds allowed by configuration.
656    pub limit: usize,
657    /// Number of corpus files considered.
658    pub loaded: usize,
659    /// Number of corpus files skipped because they were unreadable or not a matching single call.
660    pub skipped: usize,
661    /// Seeds modeled by symbolic execution as path-priority hints.
662    pub used: Vec<SymbolicCorpusSeedRef>,
663}
664
665/// One fuzz corpus seed modeled by symbolic execution.
666#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
667pub struct SymbolicCorpusSeedRef {
668    /// Corpus file path.
669    pub path: PathBuf,
670    /// ABI-encoded calldata imported from the corpus file.
671    pub calldata: Bytes,
672}
673
674/// Reference to a durable symbolic counterexample artifact.
675#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
676pub struct SymbolicArtifactRef {
677    /// Artifact schema id.
678    pub schema: String,
679    /// Path to the artifact file.
680    pub path: PathBuf,
681}
682
683impl SymbolicArtifactRef {
684    /// Creates a reference to a symbolic counterexample artifact.
685    pub fn new(path: impl Into<PathBuf>) -> Self {
686        Self { schema: SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA.to_string(), path: path.into() }
687    }
688}
689
690/// Reference to a generated Solidity regression test for a symbolic counterexample.
691#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
692pub struct SymbolicRegressionRef {
693    /// Source counterexample artifact path.
694    pub artifact: PathBuf,
695    /// Generated Solidity regression test path.
696    pub path: PathBuf,
697}
698
699/// Before/after artifact references and counters for concrete symbolic counterexample minimization.
700#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
701#[serde(deny_unknown_fields)]
702pub struct SymbolicCounterexampleMinimization {
703    /// Original confirmed replay artifact before minimization.
704    pub original: SymbolicArtifactRef,
705    /// Minimized confirmed replay artifact after minimization.
706    pub minimized: SymbolicArtifactRef,
707    /// Number of concrete replay candidates tried.
708    pub attempts: usize,
709    /// Number of replay candidates accepted.
710    pub accepted: usize,
711    /// ABI calldata byte length before minimization.
712    pub original_calldata_bytes: usize,
713    /// ABI calldata byte length after minimization.
714    pub minimized_calldata_bytes: usize,
715    /// Stateful sequence length before minimization, when this minimized a sequence.
716    #[serde(default, skip_serializing_if = "Option::is_none")]
717    pub original_sequence_len: Option<usize>,
718    /// Stateful sequence length after minimization, when this minimized a sequence.
719    #[serde(default, skip_serializing_if = "Option::is_none")]
720    pub minimized_sequence_len: Option<usize>,
721}
722
723impl SymbolicCounterexampleMinimization {
724    /// Creates concrete minimization metadata.
725    pub const fn new(
726        original: SymbolicArtifactRef,
727        minimized: SymbolicArtifactRef,
728        attempts: usize,
729        accepted: usize,
730        original_calldata_bytes: usize,
731        minimized_calldata_bytes: usize,
732    ) -> Self {
733        Self {
734            original,
735            minimized,
736            attempts,
737            accepted,
738            original_calldata_bytes,
739            minimized_calldata_bytes,
740            original_sequence_len: None,
741            minimized_sequence_len: None,
742        }
743    }
744
745    /// Adds stateful sequence lengths to minimization metadata.
746    pub const fn with_sequence_lengths(
747        mut self,
748        original_sequence_len: usize,
749        minimized_sequence_len: usize,
750    ) -> Self {
751        self.original_sequence_len = Some(original_sequence_len);
752        self.minimized_sequence_len = Some(minimized_sequence_len);
753        self
754    }
755}
756
757/// Normalized symbolic outcome names for agents and other JSON consumers.
758#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
759#[serde(rename_all = "snake_case")]
760pub enum SymbolicResultStatus {
761    /// All explored paths completed without a feasible failure.
762    Pass,
763    /// A solver counterexample was replayed concretely and still failed.
764    FailCounterexample,
765    /// The engine stopped before a proof or replayed counterexample.
766    Incomplete,
767}
768
769/// Incomplete symbolic run reason.
770#[derive(Clone, Debug, Serialize, Deserialize)]
771pub struct SymbolicIncomplete {
772    /// Stable reason kind.
773    pub kind: String,
774    /// Human-readable detail.
775    pub reason: String,
776}
777
778impl SymbolicIncomplete {
779    fn new(kind: SymbolicStopReason, reason: impl Into<String>) -> Self {
780        let kind = match kind {
781            SymbolicStopReason::Stuck => "stuck",
782            SymbolicStopReason::RevertAll => "revert_all",
783            SymbolicStopReason::Timeout => "timeout",
784            SymbolicStopReason::Error => "error",
785        };
786        Self { kind: kind.to_string(), reason: reason.into() }
787    }
788}
789
790/// Effective symbolic exploration bounds used by the run.
791#[derive(Clone, Debug, Serialize, Deserialize)]
792pub struct SymbolicBounds {
793    /// Optional solver timeout in seconds.
794    pub timeout_seconds: Option<u32>,
795    /// Optional loop-unrolling bound.
796    pub loop_bound: Option<u32>,
797    /// Effective per-path opcode depth limit.
798    pub max_depth: u32,
799    /// Effective symbolic path width limit.
800    pub max_paths: u32,
801    /// Maximum calls in a bounded symbolic invariant sequence.
802    pub invariant_depth: u32,
803    /// Pending path exploration order.
804    pub exploration_order: SymbolicExplorationOrder,
805    /// Maximum normalized solver queries.
806    pub max_solver_queries: u32,
807    /// Default bounded length for dynamic ABI inputs.
808    pub default_dynamic_length: u32,
809    /// Maximum permitted bounded dynamic ABI input length.
810    pub max_dynamic_length: u32,
811    /// Positional dynamic-leaf bounded lengths.
812    pub array_lengths: Vec<u32>,
813    /// Named dynamic-leaf bounded lengths.
814    pub dynamic_lengths: BTreeMap<String, Vec<u32>>,
815    /// Default array lengths when no explicit dynamic length exists.
816    pub default_array_lengths: Vec<u32>,
817    /// Default bytes/string lengths when no explicit dynamic length exists.
818    pub default_bytes_lengths: Vec<u32>,
819    /// Maximum generated symbolic calldata size in bytes.
820    pub max_calldata_bytes: u32,
821    /// Whether symbolic call targets can range over known deployed contracts.
822    pub symbolic_call_targets: bool,
823    /// Storage modelling mode.
824    pub storage_layout: SymbolicStorageLayout,
825}
826
827impl SymbolicBounds {
828    fn from_config(config: &SymbolicConfig) -> Self {
829        Self {
830            timeout_seconds: config.timeout,
831            loop_bound: config.loop_bound,
832            max_depth: config.execution_depth(),
833            max_paths: config.path_width(),
834            invariant_depth: config.invariant_depth,
835            exploration_order: config.exploration_order,
836            max_solver_queries: config.max_solver_queries,
837            default_dynamic_length: config.default_dynamic_length,
838            max_dynamic_length: config.max_dynamic_length,
839            array_lengths: config.array_lengths.clone(),
840            dynamic_lengths: config.dynamic_lengths.clone(),
841            default_array_lengths: config.default_array_lengths.clone(),
842            default_bytes_lengths: config.default_bytes_lengths.clone(),
843            max_calldata_bytes: config.max_calldata_bytes,
844            symbolic_call_targets: config.symbolic_call_targets,
845            storage_layout: config.storage_layout,
846        }
847    }
848}
849
850/// Solver identity and counters.
851#[derive(Clone, Debug, Serialize, Deserialize)]
852pub struct SymbolicSolverMetadata {
853    /// Configured solver name.
854    pub name: String,
855    /// Exact configured solver command, when set.
856    pub command: Option<String>,
857    /// Configured solver portfolio entries, when any.
858    pub portfolio: Vec<String>,
859    /// Run counters.
860    pub stats: SymbolicStats,
861}
862
863/// Explicit symbolic assumption attached to a result.
864#[derive(Clone, Debug, Serialize, Deserialize)]
865pub struct SymbolicAssumption {
866    /// Stable assumption kind.
867    pub kind: String,
868    /// Human-readable detail.
869    pub description: String,
870}
871
872impl SymbolicAssumption {
873    fn default_assumptions() -> Vec<Self> {
874        vec![
875            Self {
876                kind: "bounded_exploration".to_string(),
877                description: "Result is scoped to the configured path, depth, solver-query, loop, calldata, and dynamic-length bounds.".to_string(),
878            },
879            Self {
880                kind: "hash_model".to_string(),
881                description: "Symbolic Keccak and hash-like precompile reasoning assumes collision and preimage resistance for modeled cases.".to_string(),
882            },
883        ]
884    }
885}
886
887/// Concrete replay trace locator.
888#[derive(Clone, Debug, Serialize, Deserialize)]
889pub struct SymbolicCallTrace {
890    /// Whether replay produced a trace that may be present in this test result.
891    pub available: bool,
892    /// JSON location for the trace when available.
893    pub source: Option<String>,
894    /// Trace format at the source location.
895    pub format: Option<String>,
896}
897
898impl SymbolicCallTrace {
899    /// No concrete trace was produced.
900    pub const fn none() -> Self {
901        Self { available: false, source: None, format: None }
902    }
903
904    /// A concrete replay trace may be available in the normal test result traces field.
905    pub fn test_result_traces(available: bool) -> Self {
906        Self {
907            available,
908            source: available.then(|| "test_result.traces".to_string()),
909            format: available.then(|| "foundry_call_trace_arena".to_string()),
910        }
911    }
912}
913
914/// Counterexample replay status.
915#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
916#[serde(rename_all = "snake_case")]
917pub enum SymbolicReplayStatus {
918    /// No replay was required for this result.
919    NotRequired,
920    /// Concrete replay confirmed the symbolic counterexample.
921    Confirmed,
922    /// Concrete replay did not reproduce the symbolic counterexample.
923    Mismatch,
924    /// Concrete replay could not execute because of an error.
925    Error,
926    /// Concrete replay was skipped by `vm.skip`.
927    Skipped,
928}
929
930/// Replay metadata for symbolic counterexample candidates.
931#[derive(Clone, Debug, Serialize, Deserialize)]
932#[serde(deny_unknown_fields)]
933pub struct SymbolicReplayMetadata {
934    /// Whether the symbolic outcome required concrete replay.
935    pub required: bool,
936    /// Stable replay status.
937    pub status: SymbolicReplayStatus,
938    /// Optional replay detail or mismatch reason.
939    pub reason: Option<String>,
940}
941
942impl SymbolicReplayMetadata {
943    /// No replay was required.
944    pub const fn not_required() -> Self {
945        Self { required: false, status: SymbolicReplayStatus::NotRequired, reason: None }
946    }
947
948    /// Concrete replay confirmed the counterexample.
949    pub const fn confirmed() -> Self {
950        Self { required: true, status: SymbolicReplayStatus::Confirmed, reason: None }
951    }
952
953    /// Concrete replay did not reproduce the symbolic counterexample.
954    pub fn mismatch(reason: impl Into<String>) -> Self {
955        Self { required: true, status: SymbolicReplayStatus::Mismatch, reason: Some(reason.into()) }
956    }
957
958    /// Concrete replay errored before the candidate could be confirmed.
959    pub fn error(reason: impl Into<String>) -> Self {
960        Self { required: true, status: SymbolicReplayStatus::Error, reason: Some(reason.into()) }
961    }
962
963    /// Concrete replay was skipped by the test.
964    pub fn skipped(reason: impl Into<String>) -> Self {
965        Self { required: true, status: SymbolicReplayStatus::Skipped, reason: Some(reason.into()) }
966    }
967}
968
969/// Stable symbolic counterexample payload.
970#[derive(Clone, Debug, Serialize, Deserialize)]
971pub struct SymbolicCounterexample {
972    /// ABI-encoded calldata for replay.
973    pub calldata: Bytes,
974    /// Pretty-formatted ABI arguments, when decoded.
975    pub args: Option<String>,
976    /// Raw ABI arguments, when decoded.
977    pub raw_args: Option<String>,
978    /// Ether value sent with the call, when any.
979    pub value: Option<U256>,
980    /// Return data of each `svm.*` helper call, in call order.
981    #[serde(default, skip_serializing_if = "Vec::is_empty")]
982    pub svm_returns: Vec<Bytes>,
983}
984
985impl From<&BaseCounterExample> for SymbolicCounterexample {
986    fn from(counterexample: &BaseCounterExample) -> Self {
987        Self {
988            calldata: counterexample.calldata.clone(),
989            args: counterexample.args.clone(),
990            raw_args: counterexample.raw_args.clone(),
991            value: counterexample.value,
992            svm_returns: Vec::new(),
993        }
994    }
995}
996
997/// Durable symbolic counterexample artifact.
998#[derive(Clone, Debug, Serialize, Deserialize)]
999#[serde(deny_unknown_fields)]
1000pub struct SymbolicCounterexampleArtifact {
1001    /// Artifact schema version.
1002    pub schema_version: u32,
1003    /// Artifact schema id.
1004    pub schema: String,
1005    /// Whether this counterexample is a single test call or a stateful sequence.
1006    pub kind: SymbolicCounterexampleArtifactKind,
1007    /// Test identity that produced this counterexample.
1008    pub test: SymbolicCounterexampleTestIdentity,
1009    /// Concrete replay metadata for the counterexample candidate.
1010    pub replay: SymbolicReplayMetadata,
1011    /// Replay semantics that must remain stable when this artifact is replayed.
1012    pub replay_semantics: SymbolicCounterexampleReplaySemantics,
1013    /// Effective bounds used by this symbolic run.
1014    pub bounds: SymbolicBounds,
1015    /// Solver identity and counters collected during this run.
1016    pub solver: SymbolicSolverMetadata,
1017    /// Soundness assumptions that bound what a `pass` proves.
1018    pub assumptions: Vec<SymbolicAssumption>,
1019    /// Where an agent can find the concrete replay trace, when one was produced.
1020    pub call_trace: SymbolicCallTrace,
1021    /// Concrete setup-storage assignments required before replaying this artifact.
1022    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1023    pub storage: Vec<SymbolicStorageAssignment>,
1024    /// Stateful invariant failure origin, when this sequence came from symbolic invariants.
1025    #[serde(default, skip_serializing_if = "Option::is_none")]
1026    pub invariant_failure: Option<SymbolicInvariantArtifactFailure>,
1027    /// Concrete replay calls.
1028    pub calls: Vec<SymbolicCounterexampleCall>,
1029}
1030
1031impl SymbolicCounterexampleArtifact {
1032    /// Creates a durable symbolic counterexample artifact from a symbolic result and call list.
1033    pub fn new(
1034        kind: SymbolicCounterexampleArtifactKind,
1035        test: SymbolicCounterexampleTestIdentity,
1036        symbolic: &SymbolicResult,
1037        replay_semantics: SymbolicCounterexampleReplaySemantics,
1038        calls: Vec<SymbolicCounterexampleCall>,
1039    ) -> Self {
1040        Self {
1041            schema_version: SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA_VERSION,
1042            schema: SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA.to_string(),
1043            kind,
1044            test,
1045            replay: symbolic.replay.clone(),
1046            replay_semantics,
1047            bounds: symbolic.bounds.clone(),
1048            solver: symbolic.solver.clone(),
1049            assumptions: symbolic.assumptions.clone(),
1050            call_trace: symbolic.call_trace.clone(),
1051            storage: Vec::new(),
1052            invariant_failure: None,
1053            calls,
1054        }
1055    }
1056
1057    /// Attaches setup-storage assignments required for concrete replay.
1058    pub fn with_storage(mut self, storage: Vec<SymbolicStorageAssignment>) -> Self {
1059        self.storage = storage;
1060        self
1061    }
1062
1063    /// Attaches stateful invariant failure origin metadata.
1064    pub fn with_invariant_failure(
1065        mut self,
1066        invariant_failure: SymbolicInvariantArtifactFailure,
1067    ) -> Self {
1068        self.invariant_failure = Some(invariant_failure);
1069        self
1070    }
1071}
1072
1073/// Concrete replay semantics captured when a symbolic artifact is confirmed.
1074#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
1075#[serde(deny_unknown_fields)]
1076pub struct SymbolicCounterexampleReplaySemantics {
1077    /// Whether an invariant sequence replay treats any target-call revert as a failure.
1078    pub fail_on_revert: bool,
1079}
1080
1081/// Symbolic counterexample artifact shape.
1082#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1083#[serde(rename_all = "snake_case")]
1084pub enum SymbolicCounterexampleArtifactKind {
1085    /// A single stateless symbolic test call.
1086    SingleCall,
1087    /// A stateful sequence of calls.
1088    Sequence,
1089}
1090
1091/// Stateful invariant failure origin for a persisted symbolic sequence artifact.
1092#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1093#[serde(tag = "kind", rename_all = "snake_case")]
1094pub enum SymbolicInvariantArtifactFailure {
1095    /// An invariant predicate failed.
1096    Predicate {
1097        /// Invariant function name.
1098        name: String,
1099        /// Exact concrete failure site confirmed during replay.
1100        #[serde(default, skip_serializing_if = "Option::is_none")]
1101        site: Option<SymbolicInvariantFailureSite>,
1102    },
1103    /// A target/handler call asserted before an invariant predicate failed.
1104    Handler {
1105        /// Best-effort human-readable handler function name.
1106        #[serde(default, skip_serializing_if = "Option::is_none")]
1107        name: Option<String>,
1108        /// Address of the handler whose call asserted.
1109        reverter: Address,
1110        /// 4-byte selector of the failing handler call.
1111        selector: Selector,
1112        /// Stable edge fingerprint for the failing handler site.
1113        fingerprint: B256,
1114    },
1115}
1116
1117/// Concrete invariant failure site stored in symbolic replay artifacts.
1118#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1119#[serde(tag = "kind", rename_all = "snake_case")]
1120pub enum SymbolicInvariantFailureSite {
1121    /// Target/handler call failed before the invariant predicate.
1122    SequenceCall { target: Address, selector: Selector, fingerprint: B256 },
1123    /// Invariant predicate failed.
1124    Invariant { target: Address, selector: Selector, fingerprint: B256 },
1125    /// `afterInvariant` hook failed.
1126    AfterInvariant { target: Address, selector: Selector, fingerprint: B256 },
1127}
1128
1129impl From<CheckSequenceFailureSite> for SymbolicInvariantFailureSite {
1130    fn from(site: CheckSequenceFailureSite) -> Self {
1131        match site {
1132            CheckSequenceFailureSite::SequenceCall { target, selector, fingerprint } => {
1133                Self::SequenceCall { target, selector, fingerprint }
1134            }
1135            CheckSequenceFailureSite::Invariant { target, selector, fingerprint } => {
1136                Self::Invariant { target, selector, fingerprint }
1137            }
1138            CheckSequenceFailureSite::AfterInvariant { target, selector, fingerprint } => {
1139                Self::AfterInvariant { target, selector, fingerprint }
1140            }
1141        }
1142    }
1143}
1144
1145/// Test identity for a symbolic counterexample artifact.
1146#[derive(Clone, Debug, Serialize, Deserialize)]
1147#[serde(deny_unknown_fields)]
1148pub struct SymbolicCounterexampleTestIdentity {
1149    /// Contract identifier as reported by Forge.
1150    pub contract: String,
1151    /// Test function signature.
1152    pub test: String,
1153}
1154
1155/// One concrete call in a symbolic counterexample artifact.
1156#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1157#[serde(deny_unknown_fields)]
1158pub struct SymbolicCounterexampleCall {
1159    /// Amount to increase block timestamp before executing the call.
1160    pub warp: Option<U256>,
1161    /// Amount to increase block number before executing the call.
1162    pub roll: Option<U256>,
1163    /// Sender used for the call.
1164    pub sender: Address,
1165    /// Target address called.
1166    pub target: Address,
1167    /// ABI-encoded calldata for replay.
1168    pub calldata: Bytes,
1169    /// Ether value sent with the call, when any.
1170    pub value: Option<U256>,
1171    /// Human-readable contract identifier, when known.
1172    pub contract_name: Option<String>,
1173    /// ABI function name, when known.
1174    pub function_name: Option<String>,
1175    /// ABI function signature, when known.
1176    pub signature: Option<String>,
1177    /// Pretty-formatted ABI arguments, when decoded.
1178    pub args: Option<String>,
1179    /// Raw ABI arguments, when decoded.
1180    pub raw_args: Option<String>,
1181    /// Return data of each `svm.*` helper call, in call order, which replay answers these calls
1182    /// with.
1183    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1184    pub svm_returns: Vec<Bytes>,
1185}
1186
1187impl SymbolicCounterexampleCall {
1188    /// Creates an artifact call from Foundry's base counterexample shape.
1189    pub fn from_base_counterexample(
1190        counterexample: &BaseCounterExample,
1191        default_sender: Address,
1192        default_target: Address,
1193    ) -> Self {
1194        Self {
1195            warp: counterexample.warp,
1196            roll: counterexample.roll,
1197            sender: counterexample.sender.unwrap_or(default_sender),
1198            target: counterexample.addr.unwrap_or(default_target),
1199            calldata: counterexample.calldata.clone(),
1200            value: counterexample.value,
1201            contract_name: counterexample.contract_name.clone(),
1202            function_name: counterexample.func_name.clone(),
1203            signature: counterexample.signature.clone(),
1204            args: counterexample.args.clone(),
1205            raw_args: counterexample.raw_args.clone(),
1206            svm_returns: Vec::new(),
1207        }
1208    }
1209
1210    /// Creates Foundry's display counterexample shape from an artifact call.
1211    pub fn to_base_counterexample(&self) -> BaseCounterExample {
1212        BaseCounterExample {
1213            warp: self.warp,
1214            roll: self.roll,
1215            sender: Some(self.sender),
1216            addr: Some(self.target),
1217            calldata: self.calldata.clone(),
1218            value: self.value,
1219            contract_name: self.contract_name.clone(),
1220            func_name: self.function_name.clone(),
1221            signature: self.signature.clone(),
1222            args: self.args.clone(),
1223            raw_args: self.raw_args.clone(),
1224            traces: None,
1225            show_solidity: false,
1226            fuzz: Default::default(),
1227            fork_block_number: None,
1228        }
1229    }
1230
1231    /// Converts an artifact call into Foundry's invariant replay transaction shape.
1232    pub fn to_basic_tx_details(&self) -> BasicTxDetails {
1233        BasicTxDetails {
1234            warp: self.warp,
1235            roll: self.roll,
1236            sender: self.sender,
1237            call_details: CallDetails {
1238                target: self.target,
1239                calldata: self.calldata.clone(),
1240                value: self.value,
1241            },
1242        }
1243    }
1244}
1245
1246/// The result of an executed test.
1247#[derive(Clone, Debug, Default, Serialize, Deserialize)]
1248pub struct TestResult {
1249    /// The test status, indicating whether the test case succeeded, failed, or was marked as
1250    /// skipped. This means that the transaction executed properly, or the test was marked as
1251    /// skipped with vm.skip().
1252    pub status: TestStatus,
1253
1254    /// If there was a revert, this field will be populated.
1255    pub reason: Option<String>,
1256
1257    /// The active fork's block number after execution, if any.
1258    #[serde(default, skip_serializing_if = "Option::is_none")]
1259    pub fork_block_number: Option<u64>,
1260
1261    /// All broken invariant predicates in this campaign in source declaration order.
1262    ///
1263    /// For invariant tests, this is the single source of truth used by the renderer.
1264    /// `reason` and `counterexample` are not populated for invariant tests.
1265    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1266    pub invariant_failures: Vec<InvariantFailure>,
1267
1268    /// Per-predicate outcomes for invariant campaigns. This preserves individual
1269    /// `invariant_*` / `statefulFuzz*` pass/fail reporting when multiple predicates are checked
1270    /// by one contract-level campaign.
1271    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1272    pub invariant_predicate_results: Vec<InvariantPredicateResult>,
1273
1274    /// Directory where invariant failure counterexamples have been persisted (set when one or more
1275    /// secondary invariant failures were written, so users can locate persisted counterexamples).
1276    #[serde(default, skip_serializing_if = "Option::is_none")]
1277    pub invariant_failure_dir: Option<PathBuf>,
1278
1279    /// Total number of invariant predicates exercised in this campaign. When `Some(n)` the
1280    /// user-facing report renders a contract-level `<broken>/<n> invariants broken` summary so
1281    /// users get an at-a-glance health line without counting `[FAIL]` blocks. `None` for
1282    /// single-predicate campaigns.
1283    #[serde(default, skip_serializing_if = "Option::is_none")]
1284    pub invariant_count: Option<usize>,
1285
1286    /// Handler-side assertion bugs found during the campaign, deduped by
1287    /// `(reverter, selector)` site (Medusa/Echidna semantics). Rendered in a dedicated
1288    /// `Assertion Tests` section.
1289    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1290    pub invariant_handler_failures: Vec<InvariantFailure>,
1291
1292    /// Minimal reproduction test case for failing test
1293    pub counterexample: Option<CounterExample>,
1294
1295    /// Legacy durable replay artifact for the top-level counterexample, when one was written.
1296    ///
1297    /// Prefer [`Self::counterexample_artifacts`] for new consumers; this compatibility field is
1298    /// maintained by [`Self::add_counterexample_artifact`] for older JSON readers.
1299    #[serde(default, skip_serializing_if = "Option::is_none")]
1300    pub counterexample_artifact: Option<SymbolicArtifactRef>,
1301
1302    /// All durable replay artifacts produced for this test result, normalized for JSON consumers.
1303    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1304    pub counterexample_artifacts: Vec<SymbolicArtifactRef>,
1305
1306    /// Generated Solidity regression tests for this symbolic counterexample.
1307    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1308    pub symbolic_regressions: Vec<SymbolicRegressionRef>,
1309
1310    /// Any captured & parsed as strings logs along the test's execution which should
1311    /// be printed to the user.
1312    pub logs: Vec<Log>,
1313
1314    /// The decoded DSTest logging events and Hardhat's `console.log` from [logs](Self::logs).
1315    /// Used for json output.
1316    pub decoded_logs: Vec<String>,
1317
1318    /// What kind of test this was
1319    pub kind: TestKind,
1320
1321    /// Stable symbolic result object for `forge test --symbolic --json`.
1322    #[serde(default, skip_serializing_if = "Option::is_none")]
1323    pub symbolic: Option<SymbolicResult>,
1324
1325    /// Work performed by the live symbolic assistant; does not represent a proof result.
1326    #[serde(default, skip_serializing_if = "Option::is_none")]
1327    pub symbolic_live: Option<LiveInvariantStats>,
1328
1329    /// Traces
1330    pub traces: Traces,
1331
1332    /// Runtime bytecodes for contracts seen in debug traces.
1333    #[serde(skip)]
1334    pub debug_bytecodes: AddressHashMap<Bytes>,
1335
1336    /// Additional traces to use for gas report.
1337    ///
1338    /// These are cleared after the gas report is analyzed.
1339    #[serde(skip)]
1340    pub gas_report_traces: Vec<Vec<CallTraceArena>>,
1341
1342    /// Raw line coverage info
1343    #[serde(skip)]
1344    pub line_coverage: Option<HitMaps>,
1345
1346    /// Labeled addresses
1347    #[serde(rename = "labeled_addresses")] // Backwards compatibility.
1348    pub labels: AddressHashMap<String>,
1349
1350    #[serde(with = "foundry_common::serde_helpers::duration")]
1351    pub duration: Duration,
1352
1353    /// pc breakpoint char map
1354    pub breakpoints: Breakpoints,
1355
1356    /// Any captured gas snapshots along the test's execution which should be accumulated.
1357    pub gas_snapshots: BTreeMap<String, BTreeMap<String, String>>,
1358
1359    /// Deprecated cheatcodes (mapped to their replacements, if any) used in current test.
1360    #[serde(skip)]
1361    pub deprecated_cheatcodes: HashMap<&'static str, Option<&'static str>>,
1362}
1363
1364impl fmt::Display for TestResult {
1365    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1366        f.write_str(&self.render(false, None))
1367    }
1368}
1369
1370/// Appends a `[label] (original: N, shrunk: M)` header followed by one line per call.
1371fn write_sequence(s: &mut String, label: &str, original: usize, sequence: &[BaseCounterExample]) {
1372    writeln!(s, "\n\t[{label}] (original: {original}, shrunk: {})", sequence.len()).unwrap();
1373    for ex in sequence {
1374        writeln!(s, "{ex}").unwrap();
1375    }
1376}
1377
1378/// Appends `[FAIL: reason]{name_suffix}` plus the counterexample sequence, if any.
1379///
1380/// Returns `true` if a sequence (ending in a newline) was written.
1381fn write_failure(s: &mut String, failure: &InvariantFailure, name_suffix: &str) -> bool {
1382    write!(s, "[FAIL: {}]{name_suffix}", failure.reason()).unwrap();
1383    if let Some(CounterExample::Sequence(original, sequence)) = failure.counterexample() {
1384        write_sequence(s, "Sequence", *original, sequence);
1385        return true;
1386    }
1387    false
1388}
1389
1390/// All durable replay artifacts referenced by a counterexample: its own artifact plus the
1391/// before/after artifacts of its minimization, if any.
1392fn replay_artifacts<'a>(
1393    artifact: Option<&'a SymbolicArtifactRef>,
1394    minimization: Option<&'a SymbolicCounterexampleMinimization>,
1395) -> impl Iterator<Item = &'a SymbolicArtifactRef> {
1396    artifact.into_iter().chain(minimization.into_iter().flat_map(|m| [&m.original, &m.minimized]))
1397}
1398
1399impl TestResult {
1400    /// Returns `true` if this failed result can be meaningfully inspected with
1401    /// `forge test --debug --match-test`.
1402    const fn is_debuggable_failure(&self) -> bool {
1403        self.status.is_failure()
1404            && !self.kind.is_invariant()
1405            && !self.kind.is_symbolic()
1406            && self.symbolic.is_none()
1407    }
1408
1409    /// Adds a durable replay artifact to the normalized list and legacy top-level field.
1410    pub fn add_counterexample_artifact(&mut self, artifact: SymbolicArtifactRef) {
1411        if !self.counterexample_artifacts.contains(&artifact) {
1412            self.counterexample_artifacts.push(artifact.clone());
1413        }
1414        if self.counterexample_artifact.is_none() {
1415            self.counterexample_artifact = Some(artifact);
1416        }
1417    }
1418
1419    /// Renders the status block, either for the console (`user_facing`) or for JUnit output.
1420    fn render(&self, user_facing: bool, campaign_name: Option<&str>) -> String {
1421        let header = if user_facing {
1422            campaign_name.unwrap_or(INVARIANT_CAMPAIGN_FALLBACK_NAME)
1423        } else {
1424            "Predicates"
1425        };
1426        let mut s = String::new();
1427        match self.status {
1428            TestStatus::Success => {
1429                s.push_str("[PASS]");
1430                // For optimization mode, show the best example sequence in green.
1431                if let Some(CounterExample::Sequence(original, sequence)) = &self.counterexample {
1432                    write_sequence(&mut s, "Best sequence", *original, sequence);
1433                }
1434                self.write_predicates(&mut s, header, true);
1435                s.green().wrap().to_string()
1436            }
1437            TestStatus::Skipped => {
1438                s.push_str("[SKIP");
1439                if let Some(reason) = &self.reason {
1440                    write!(s, ": {reason}").unwrap();
1441                }
1442                s.push(']');
1443                self.write_predicates(&mut s, header, true);
1444                s.yellow().to_string()
1445            }
1446            TestStatus::Failure => {
1447                let is_invariant_failure = !self.invariant_failures.is_empty()
1448                    || !self.invariant_handler_failures.is_empty();
1449                if is_invariant_failure {
1450                    // Contract-level campaigns identify the broken predicate even when only one
1451                    // predicate failed. Preserve the compact legacy shape only for the anchor of a
1452                    // single-predicate run.
1453                    let named = self.invariant_count.is_some() || self.invariant_failures.len() > 1;
1454                    for (i, failure) in self.invariant_failures.iter().enumerate() {
1455                        if i > 0 {
1456                            s.push('\n');
1457                        }
1458                        let is_anchor =
1459                            matches!(failure, InvariantFailure::Predicate { is_anchor: true, .. });
1460                        let suffix = if named || !is_anchor {
1461                            format!(" {}", failure.name())
1462                        } else {
1463                            String::new()
1464                        };
1465                        write_failure(&mut s, failure, &suffix);
1466                    }
1467                } else {
1468                    // Non-invariant failure (unit / fuzz / DS-style): render from the legacy
1469                    // `reason` / `counterexample` fields.
1470                    s.push_str("[FAIL");
1471                    if let Some(reason) = &self.reason {
1472                        write!(s, ": {reason}").unwrap();
1473                    }
1474                    match &self.counterexample {
1475                        Some(CounterExample::Single(ex)) => {
1476                            write!(s, "; counterexample: {ex}]").unwrap();
1477                        }
1478                        Some(CounterExample::Sequence(original, sequence)) => {
1479                            s.push(']');
1480                            write_sequence(&mut s, "Sequence", *original, sequence);
1481                        }
1482                        None => s.push(']'),
1483                    }
1484                }
1485
1486                let broken = self.invariant_failures.len();
1487                let rollup = match self.invariant_count {
1488                    Some(total) if total > 1 && is_invariant_failure => {
1489                        writeln!(s, "\n{header}: {broken}/{total} invariants broken").unwrap();
1490                        true
1491                    }
1492                    _ => false,
1493                };
1494                self.write_predicates(&mut s, header, !user_facing || !rollup);
1495                if broken > 1
1496                    && let Some(dir) = &self.invariant_failure_dir
1497                {
1498                    writeln!(
1499                        s,
1500                        "{broken} invariant failure(s) persisted to {} — rerun to shrink",
1501                        dir.display()
1502                    )
1503                    .unwrap();
1504                }
1505
1506                if !self.invariant_handler_failures.is_empty() {
1507                    // Separate the section from anything rendered above it.
1508                    let preceded = rollup
1509                        || broken > 0
1510                        || (user_facing && self.invariant_predicate_results.len() > 1);
1511                    writeln!(
1512                        s,
1513                        "{}{}: {} assertion bug(s) found",
1514                        if preceded { "\n" } else { "" },
1515                        if user_facing { "Assertion Tests" } else { "Handler assertions" },
1516                        self.invariant_handler_failures.len()
1517                    )
1518                    .unwrap();
1519                    for failure in &self.invariant_handler_failures {
1520                        if !write_failure(&mut s, failure, &format!(" {}", failure.name())) {
1521                            s.push('\n');
1522                        }
1523                    }
1524                }
1525
1526                s.red().wrap().to_string()
1527            }
1528        }
1529    }
1530
1531    /// Appends the per-predicate summary for multi-predicate campaigns.
1532    fn write_predicates(&self, s: &mut String, header: &str, show_header: bool) {
1533        if self.invariant_predicate_results.len() <= 1 {
1534            return;
1535        }
1536        if show_header {
1537            write!(s, "\n{header}:\n").unwrap();
1538        }
1539        for predicate in &self.invariant_predicate_results {
1540            let name = &predicate.name;
1541            match (predicate.status, &predicate.reason) {
1542                (TestStatus::Success, _) => writeln!(s, "[PASS] {name}"),
1543                (TestStatus::Failure, reason) => {
1544                    writeln!(s, "[FAIL: {}] {name}", reason.as_deref().unwrap_or_default())
1545                }
1546                (TestStatus::Skipped, Some(reason)) => writeln!(s, "[SKIP: {reason}] {name}"),
1547                (TestStatus::Skipped, None) => writeln!(s, "[SKIP] {name}"),
1548            }
1549            .unwrap();
1550        }
1551    }
1552}
1553
1554macro_rules! extend {
1555    ($a:expr, $b:expr, $trace_kind:expr) => {
1556        if $b.fork_block_number.is_some() {
1557            $a.fork_block_number = $b.fork_block_number;
1558        }
1559        $a.logs.extend($b.logs);
1560        $a.labels.extend($b.labels);
1561        $a.traces.extend($b.traces.map(|traces| ($trace_kind, traces)));
1562        $a.debug_bytecodes.extend($b.debug_bytecodes);
1563        $a.merge_coverages($b.line_coverage);
1564    };
1565}
1566
1567/// Forge-side outcome of an invariant campaign, recorded into a [`TestResult`].
1568#[derive(Default)]
1569pub struct InvariantOutcome {
1570    /// Whether every checked invariant held.
1571    pub success: bool,
1572    /// Fork block number the campaign ran against, if any.
1573    pub fork_block_number: Option<u64>,
1574    /// Broken invariants, each with its shrunk call sequence.
1575    pub failures: Vec<InvariantFailure>,
1576    /// Handler assertion failures found while running the campaign.
1577    pub handler_failures: Vec<InvariantFailure>,
1578    /// Per-invariant pass/fail/skip rows.
1579    pub predicate_results: Vec<InvariantPredicateResult>,
1580    /// Directory the failing sequences were persisted to.
1581    pub failure_dir: Option<PathBuf>,
1582    /// Number of invariants checked, when the campaign ran more than one.
1583    pub invariant_count: Option<usize>,
1584    /// Best sequence found in optimization mode.
1585    pub counterexample: Option<CounterExample>,
1586    /// Traces collected for the gas report.
1587    pub gas_report_traces: Vec<Vec<CallTraceArena>>,
1588}
1589
1590/// Invariant kind for results that did not run a real campaign (setup failures, replays, skips).
1591pub(crate) fn invariant_kind(runs: usize, calls: usize, reverts: usize) -> TestKind {
1592    TestKind::Invariant {
1593        runs,
1594        calls,
1595        reverts,
1596        workers: 1,
1597        metrics: Default::default(),
1598        failed_corpus_replays: 0,
1599        optimization_best_value: None,
1600    }
1601}
1602
1603impl TestResult {
1604    /// Creates a new test result starting from test setup results.
1605    pub fn new(setup: &TestSetup) -> Self {
1606        Self {
1607            labels: setup.labels.clone(),
1608            logs: setup.logs.clone(),
1609            traces: setup.traces.clone(),
1610            debug_bytecodes: setup.debug_bytecodes.clone(),
1611            line_coverage: setup.coverage.clone(),
1612            fork_block_number: setup.fork_block_number,
1613            ..Default::default()
1614        }
1615    }
1616
1617    /// Creates a failed test result with given reason.
1618    pub fn fail(reason: String) -> Self {
1619        Self { status: TestStatus::Failure, reason: Some(reason), ..Default::default() }
1620    }
1621
1622    /// Creates a test setup result.
1623    pub fn setup_result(setup: TestSetup) -> Self {
1624        Self {
1625            status: if matches!(setup.outcome, SetupOutcome::Skipped(_)) {
1626                TestStatus::Skipped
1627            } else {
1628                TestStatus::Failure
1629            },
1630            reason: setup.outcome.reason().map(str::to_string),
1631            logs: setup.logs,
1632            traces: setup.traces,
1633            debug_bytecodes: setup.debug_bytecodes,
1634            line_coverage: setup.coverage,
1635            labels: setup.labels,
1636            fork_block_number: setup.fork_block_number,
1637            ..Default::default()
1638        }
1639    }
1640
1641    /// Returns the skipped result for single test (used in skipped fuzz test too).
1642    pub fn single_skip(&mut self, reason: SkipReason) {
1643        self.status = TestStatus::Skipped;
1644        self.reason = reason.0;
1645    }
1646
1647    /// Returns the failed result with reason for single test.
1648    pub fn single_fail(&mut self, reason: Option<String>) {
1649        self.status = TestStatus::Failure;
1650        self.reason = reason;
1651    }
1652
1653    /// Returns the result for single test. Merges execution results (logs, labeled addresses,
1654    /// traces and coverages) in initial setup results.
1655    pub fn single_result<FEN: FoundryEvmNetwork>(
1656        &mut self,
1657        success: bool,
1658        reason: Option<String>,
1659        raw_call_result: RawCallResult<FEN>,
1660    ) {
1661        self.kind = TestKind::Unit {
1662            gas: raw_call_result.gas_used.saturating_sub(raw_call_result.stipend),
1663        };
1664
1665        extend!(self, raw_call_result, TraceKind::Execution);
1666
1667        self.status = if success { TestStatus::Success } else { TestStatus::Failure };
1668        self.reason = reason;
1669        self.duration = Duration::default();
1670        self.gas_report_traces = Vec::new();
1671
1672        if let Some(cheatcodes) = raw_call_result.cheatcodes {
1673            self.breakpoints = cheatcodes.breakpoints;
1674            self.gas_snapshots = cheatcodes.gas_snapshots;
1675            self.deprecated_cheatcodes = cheatcodes.deprecated;
1676        }
1677    }
1678
1679    /// Returns the result for a fuzzed test. Merges fuzz execution results (logs, labeled
1680    /// addresses, traces and coverages) in initial setup results.
1681    pub fn fuzz_result(&mut self, mut result: FuzzTestResult) {
1682        let kind = TestKind::Fuzz {
1683            median_gas: result.median_gas(false),
1684            mean_gas: result.mean_gas(false),
1685            first_case: std::mem::take(&mut result.first_case),
1686            runs: result.gas_by_case.len(),
1687            failed_corpus_replays: result.failed_corpus_replays,
1688        };
1689        self.campaign_result(kind, result);
1690    }
1691
1692    /// Returns the result for a table test. Merges table test execution results (logs, labeled
1693    /// addresses, traces and coverages) in initial setup results.
1694    pub fn table_result(&mut self, result: FuzzTestResult) {
1695        let kind = TestKind::Table {
1696            median_gas: result.median_gas(false),
1697            mean_gas: result.mean_gas(false),
1698            runs: result.gas_by_case.len(),
1699        };
1700        self.campaign_result(kind, result);
1701    }
1702
1703    fn campaign_result(&mut self, kind: TestKind, result: FuzzTestResult) {
1704        self.kind = kind;
1705
1706        extend!(self, result, TraceKind::Execution);
1707
1708        self.status = if result.skipped {
1709            TestStatus::Skipped
1710        } else if result.success {
1711            TestStatus::Success
1712        } else {
1713            TestStatus::Failure
1714        };
1715        self.reason = result.reason;
1716        self.counterexample = result.counterexample;
1717        self.duration = Duration::default();
1718        self.gas_report_traces = result.gas_report_traces.into_iter().map(|t| vec![t]).collect();
1719        self.breakpoints = result.breakpoints.unwrap_or_default();
1720        self.deprecated_cheatcodes = result.deprecated_cheatcodes;
1721    }
1722
1723    /// Returns the fail result for fuzz test setup.
1724    pub fn fuzz_setup_fail(&mut self, e: Report) {
1725        self.kind = TestKind::Fuzz {
1726            first_case: Default::default(),
1727            runs: 0,
1728            mean_gas: 0,
1729            median_gas: 0,
1730            failed_corpus_replays: 0,
1731        };
1732        self.status = TestStatus::Failure;
1733        debug!(?e, "failed to set up fuzz testing environment");
1734        self.reason = Some(format!("failed to set up fuzz testing environment: {e}"));
1735    }
1736
1737    /// Returns the skipped result for invariant campaign with per-predicate outcomes.
1738    pub fn invariant_skip_with_predicates(
1739        &mut self,
1740        reason: SkipReason,
1741        invariant_predicate_results: Vec<InvariantPredicateResult>,
1742    ) {
1743        self.kind = invariant_kind(1, 1, 1);
1744        self.status = TestStatus::Skipped;
1745        let predicate_count = invariant_predicate_results.len();
1746        let is_campaign = predicate_count > 1;
1747        self.reason = if is_campaign { None } else { reason.0 };
1748        self.invariant_count = is_campaign.then_some(predicate_count);
1749        self.invariant_predicate_results = invariant_predicate_results;
1750    }
1751
1752    /// Returns the fail result for replayed invariant test.
1753    pub fn invariant_replay_fail(
1754        &mut self,
1755        outcome: CheckSequenceOutcome,
1756        invariant_name: &str,
1757        fallback_reason: Option<String>,
1758        call_sequence: Vec<BaseCounterExample>,
1759    ) {
1760        self.kind = invariant_kind(1, outcome.calls_count, outcome.reverts);
1761        self.status = TestStatus::Failure;
1762        self.reason = Some(outcome.reason.or(fallback_reason).unwrap_or_else(|| {
1763            let what = if outcome.replayed_entirely {
1764                "replay failure"
1765            } else {
1766                "persisted failure revert"
1767            };
1768            format!("{invariant_name} {what}")
1769        }));
1770        self.counterexample = Some(CounterExample::Sequence(call_sequence.len(), call_sequence));
1771    }
1772
1773    /// Returns the success result for a replayed invariant test.
1774    pub fn invariant_replay_success(&mut self, call_count: usize, reverts: usize) {
1775        self.kind = invariant_kind(1, call_count, reverts);
1776        self.status = TestStatus::Success;
1777        self.reason = None;
1778    }
1779
1780    /// Returns the fail result for invariant test setup.
1781    pub fn invariant_setup_fail(&mut self, e: Report) {
1782        self.kind = invariant_kind(0, 0, 0);
1783        self.status = TestStatus::Failure;
1784        self.reason = Some(format!("failed to set up invariant testing environment: {e}"));
1785    }
1786
1787    /// Returns the invariant test result.
1788    pub fn invariant_result(&mut self, kind: TestKind, outcome: InvariantOutcome) {
1789        // For optimization mode (Some value), always succeed. For check mode (None), use success.
1790        let optimizing =
1791            matches!(kind, TestKind::Invariant { optimization_best_value: Some(_), .. });
1792        self.kind = kind;
1793        self.status =
1794            if optimizing || outcome.success { TestStatus::Success } else { TestStatus::Failure };
1795        self.fork_block_number = outcome.fork_block_number;
1796        self.invariant_predicate_results = outcome.predicate_results;
1797        self.invariant_failure_dir = outcome.failure_dir;
1798        self.invariant_count = outcome.invariant_count;
1799        // `counterexample` is only used by the renderer for optimization mode (the "best
1800        // sequence" rendered on success). Invariant check-mode failures live entirely in
1801        // `invariant_failures`; `reason`/`counterexample` stay `None` for invariant tests.
1802        self.counterexample = outcome.counterexample;
1803        for artifact in outcome
1804            .failures
1805            .iter()
1806            .chain(&outcome.handler_failures)
1807            .flat_map(|failure| replay_artifacts(failure.artifact(), failure.minimization()))
1808        {
1809            self.add_counterexample_artifact(artifact.clone());
1810        }
1811        self.invariant_failures = outcome.failures;
1812        self.invariant_handler_failures = outcome.handler_failures;
1813        self.gas_report_traces = outcome.gas_report_traces;
1814    }
1815
1816    /// Returns the result for a symbolic test.
1817    pub fn symbolic_result(
1818        &mut self,
1819        status: TestStatus,
1820        reason: Option<String>,
1821        counterexample: Option<CounterExample>,
1822        symbolic: SymbolicResult,
1823    ) {
1824        self.kind = TestKind::Symbolic(symbolic.solver.stats);
1825        self.status = status;
1826        self.reason = reason;
1827        self.counterexample = counterexample;
1828        self.record_symbolic(symbolic);
1829        self.duration = Duration::default();
1830    }
1831
1832    /// Records symbolic execution metadata without changing the test status/kind.
1833    pub(crate) fn record_symbolic(&mut self, symbolic: SymbolicResult) {
1834        for artifact in replay_artifacts(symbolic.artifact.as_ref(), symbolic.minimization.as_ref())
1835        {
1836            self.add_counterexample_artifact(artifact.clone());
1837        }
1838        self.symbolic = Some(symbolic);
1839    }
1840
1841    /// Records a successful showmap replay result.
1842    pub fn replay_result(
1843        &mut self,
1844        corpus_entries: usize,
1845        showmap_files: usize,
1846        skipped_entries: usize,
1847        duration: Duration,
1848    ) {
1849        self.kind = TestKind::Replay { corpus_entries, showmap_files, skipped_entries };
1850        self.status = TestStatus::Success;
1851        self.duration = duration;
1852    }
1853
1854    /// Records a skipped showmap replay (e.g. unit test or no corpus available).
1855    pub fn replay_skip(&mut self, reason: impl Into<String>) {
1856        self.kind = TestKind::Replay { corpus_entries: 0, showmap_files: 0, skipped_entries: 0 };
1857        self.status = TestStatus::Skipped;
1858        self.reason = Some(reason.into());
1859        self.duration = Duration::default();
1860    }
1861
1862    /// Marks a campaign stopped early by fail-fast or Ctrl-C as skipped, so a partial run is not
1863    /// reported as passing.
1864    pub fn interrupt(&mut self) {
1865        let reason = Some("interrupted".to_string());
1866        self.status = TestStatus::Skipped;
1867        for predicate in &mut self.invariant_predicate_results {
1868            if predicate.status.is_success() {
1869                predicate.status = TestStatus::Skipped;
1870                predicate.reason.clone_from(&reason);
1871            }
1872        }
1873        // Multi-predicate campaigns carry reasons per predicate.
1874        if self.invariant_count.is_none() {
1875            self.reason = reason;
1876        }
1877    }
1878
1879    /// Formats the test result into a string (for printing), naming invariant campaigns after
1880    /// the suite's contract.
1881    pub(crate) fn short_result_with_suite(&self, name: &str, suite_name: &str) -> String {
1882        let campaign = (self.kind.is_invariant() && self.invariant_count.is_some())
1883            .then(|| invariant_campaign_display_name(get_contract_name(suite_name)));
1884        let name = campaign.as_deref().unwrap_or(name);
1885        let status = self.render(true, campaign.as_deref());
1886        let block = match self.fork_block_number {
1887            Some(block) if self.status.is_failure() => format!(" (block: {block})"),
1888            _ => String::new(),
1889        };
1890        format!("{status} {name}{block} {}", self.kind.report())
1891    }
1892
1893    /// The number of logical tests this result stands for: skipped predicates of a campaign are
1894    /// counted individually.
1895    fn logical_count(&self) -> usize {
1896        let skipped = self.skipped_predicate_count();
1897        if skipped == 0 {
1898            1
1899        } else if self.status.is_skipped() && skipped == self.invariant_predicate_results.len() {
1900            skipped
1901        } else {
1902            1 + skipped
1903        }
1904    }
1905
1906    fn skipped_count(&self) -> usize {
1907        let skipped = self.skipped_predicate_count();
1908        if skipped == 0 && self.status.is_skipped() { 1 } else { skipped }
1909    }
1910
1911    fn skipped_predicate_count(&self) -> usize {
1912        self.invariant_predicate_results.iter().filter(|p| p.status.is_skipped()).count()
1913    }
1914
1915    /// Merges the given raw call result into `self`.
1916    pub fn extend<FEN: FoundryEvmNetwork>(&mut self, call_result: RawCallResult<FEN>) {
1917        extend!(self, call_result, TraceKind::Execution);
1918    }
1919
1920    /// Merges the given pre-test setup result into `self`.
1921    pub(crate) fn extend_setup<FEN: FoundryEvmNetwork>(&mut self, call_result: RawCallResult<FEN>) {
1922        extend!(self, call_result, TraceKind::Setup);
1923    }
1924
1925    /// Merges the given coverage result into `self`.
1926    pub fn merge_coverages(&mut self, other_coverage: Option<HitMaps>) {
1927        HitMaps::merge_opt(&mut self.line_coverage, other_coverage);
1928    }
1929}
1930
1931/// Data report by a test.
1932#[derive(Clone, Debug, PartialEq, Eq)]
1933pub enum TestKindReport {
1934    Unit {
1935        gas: u64,
1936    },
1937    Fuzz {
1938        runs: usize,
1939        mean_gas: u64,
1940        median_gas: u64,
1941        failed_corpus_replays: usize,
1942    },
1943    Invariant {
1944        runs: usize,
1945        calls: usize,
1946        reverts: usize,
1947        failed_corpus_replays: usize,
1948        /// For optimization mode (int256 return): the best value achieved. None = check mode.
1949        optimization_best_value: Option<I256>,
1950    },
1951    Table {
1952        runs: usize,
1953        mean_gas: u64,
1954        median_gas: u64,
1955    },
1956    Symbolic(SymbolicStats),
1957    /// Showmap corpus replay (no campaign performed).
1958    Replay {
1959        corpus_entries: usize,
1960        showmap_files: usize,
1961        skipped_entries: usize,
1962    },
1963}
1964
1965impl fmt::Display for TestKindReport {
1966    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1967        match self {
1968            Self::Unit { gas } => write!(f, "(gas: {gas})"),
1969            Self::Fuzz { runs, mean_gas, median_gas, failed_corpus_replays } => {
1970                write!(f, "(runs: {runs}, μ: {mean_gas}, ~: {median_gas}")?;
1971                if *failed_corpus_replays != 0 {
1972                    write!(f, ", failed corpus replays: {failed_corpus_replays}")?;
1973                }
1974                f.write_str(")")
1975            }
1976            Self::Invariant {
1977                runs,
1978                calls,
1979                reverts,
1980                failed_corpus_replays,
1981                optimization_best_value,
1982            } => {
1983                if let Some(best_value) = optimization_best_value {
1984                    return write!(f, "(best: {best_value}, runs: {runs}, calls: {calls})");
1985                }
1986                write!(f, "(runs: {runs}, calls: {calls}, reverts: {reverts}")?;
1987                if *failed_corpus_replays != 0 {
1988                    write!(f, ", failed corpus replays: {failed_corpus_replays}")?;
1989                }
1990                f.write_str(")")
1991            }
1992            Self::Table { runs, mean_gas, median_gas } => {
1993                write!(f, "(runs: {runs}, μ: {mean_gas}, ~: {median_gas})")
1994            }
1995            Self::Symbolic(SymbolicStats {
1996                paths,
1997                solver_queries,
1998                smt_queries,
1999                sat_queries,
2000                model_queries,
2001                sat_cache_hits,
2002                model_cache_hits,
2003                heuristic_witnesses,
2004                solver_time_ms,
2005                ..
2006            }) => {
2007                write!(
2008                    f,
2009                    "(paths: {paths}, queries: {solver_queries}, smt: {smt_queries}, sat: {sat_queries} ({sat_cache_hits} cached), models: {model_queries} ({model_cache_hits} cached), hard-arith: {heuristic_witnesses}, solver: {solver_time_ms}ms)"
2010                )
2011            }
2012            Self::Replay { corpus_entries, showmap_files, skipped_entries } => {
2013                write!(f, "(replay: {corpus_entries} entries, {showmap_files} files")?;
2014                if *skipped_entries != 0 {
2015                    write!(f, ", {skipped_entries} skipped")?;
2016                }
2017                f.write_str(")")
2018            }
2019        }
2020    }
2021}
2022
2023impl TestKindReport {
2024    /// Returns the main gas value to compare against
2025    pub const fn gas(&self) -> u64 {
2026        match *self {
2027            Self::Unit { gas } => gas,
2028            // We use the median for comparisons
2029            Self::Fuzz { median_gas, .. } | Self::Table { median_gas, .. } => median_gas,
2030            // We return 0 since it's not applicable
2031            Self::Invariant { .. } | Self::Symbolic { .. } | Self::Replay { .. } => 0,
2032        }
2033    }
2034}
2035
2036/// Various types of tests
2037#[derive(Clone, Debug, Serialize, Deserialize)]
2038pub enum TestKind {
2039    /// A unit test.
2040    Unit { gas: u64 },
2041    /// A fuzz test.
2042    Fuzz {
2043        /// we keep this for the debugger
2044        first_case: FuzzCase,
2045        runs: usize,
2046        mean_gas: u64,
2047        median_gas: u64,
2048        failed_corpus_replays: usize,
2049    },
2050    /// An invariant test.
2051    Invariant {
2052        runs: usize,
2053        calls: usize,
2054        reverts: usize,
2055        /// Actual worker count used by this invariant campaign.
2056        #[serde(default = "default_invariant_workers")]
2057        workers: usize,
2058        metrics: Map<String, InvariantMetrics>,
2059        failed_corpus_replays: usize,
2060        /// For optimization mode (int256 return): the best value achieved. None = check mode.
2061        optimization_best_value: Option<I256>,
2062    },
2063    /// A table test.
2064    Table { runs: usize, mean_gas: u64, median_gas: u64 },
2065    /// A symbolic test.
2066    Symbolic(SymbolicStats),
2067    /// Showmap corpus replay (no campaign performed).
2068    Replay { corpus_entries: usize, showmap_files: usize, skipped_entries: usize },
2069}
2070
2071impl Default for TestKind {
2072    fn default() -> Self {
2073        Self::Unit { gas: 0 }
2074    }
2075}
2076
2077impl TestKind {
2078    /// Returns `true` if this is a fuzz test.
2079    pub const fn is_fuzz(&self) -> bool {
2080        matches!(self, Self::Fuzz { .. })
2081    }
2082
2083    /// Returns `true` if this is an invariant test.
2084    pub const fn is_invariant(&self) -> bool {
2085        matches!(self, Self::Invariant { .. })
2086    }
2087
2088    /// Returns `true` if this is a symbolic test.
2089    pub const fn is_symbolic(&self) -> bool {
2090        matches!(self, Self::Symbolic { .. })
2091    }
2092
2093    /// Actual invariant campaign worker count, if this is an invariant test.
2094    pub const fn invariant_workers(&self) -> Option<usize> {
2095        match self {
2096            Self::Invariant { workers, .. } => Some(*workers),
2097            _ => None,
2098        }
2099    }
2100
2101    /// The gas consumed by this test
2102    pub const fn report(&self) -> TestKindReport {
2103        match *self {
2104            Self::Unit { gas } => TestKindReport::Unit { gas },
2105            Self::Fuzz { runs, mean_gas, median_gas, failed_corpus_replays, .. } => {
2106                TestKindReport::Fuzz { runs, mean_gas, median_gas, failed_corpus_replays }
2107            }
2108            Self::Invariant {
2109                runs,
2110                calls,
2111                reverts,
2112                failed_corpus_replays,
2113                optimization_best_value,
2114                ..
2115            } => TestKindReport::Invariant {
2116                runs,
2117                calls,
2118                reverts,
2119                failed_corpus_replays,
2120                optimization_best_value,
2121            },
2122            Self::Table { runs, mean_gas, median_gas } => {
2123                TestKindReport::Table { runs, mean_gas, median_gas }
2124            }
2125            Self::Symbolic(stats) => TestKindReport::Symbolic(stats),
2126            Self::Replay { corpus_entries, showmap_files, skipped_entries } => {
2127                TestKindReport::Replay { corpus_entries, showmap_files, skipped_entries }
2128            }
2129        }
2130    }
2131}
2132
2133const fn default_invariant_workers() -> usize {
2134    1
2135}
2136
2137/// The result of a test setup.
2138///
2139/// Includes the deployment of the required libraries and the test contract itself, and the call to
2140/// the `setUp()` function.
2141#[derive(Clone, Debug, Default)]
2142pub struct TestSetup {
2143    /// The address at which the test contract was deployed.
2144    pub address: Address,
2145    /// Defined fuzz test fixtures.
2146    pub fuzz_fixtures: FuzzFixtures,
2147
2148    /// The logs emitted during setup.
2149    pub logs: Vec<Log>,
2150    /// Addresses labeled during setup.
2151    pub labels: AddressHashMap<String>,
2152    /// Call traces of the setup.
2153    pub traces: Traces,
2154    /// Runtime bytecodes for contracts seen in setup traces.
2155    pub debug_bytecodes: AddressHashMap<Bytes>,
2156    /// Coverage info during setup.
2157    pub coverage: Option<HitMaps>,
2158    /// Addresses of external libraries deployed during setup.
2159    pub deployed_libs: Vec<Address>,
2160    /// The active fork's block number after setup, if any.
2161    pub fork_block_number: Option<u64>,
2162    /// Cached setup-derived fuzz dictionary for stateless fuzz tests.
2163    pub(crate) fuzz_state: OnceLock<EvmFuzzState>,
2164    /// Storage keys observed during setup, including implicit zero slots of created accounts.
2165    pub(crate) fuzz_storage: SetupStorage,
2166
2167    /// How the setup ended.
2168    pub outcome: SetupOutcome,
2169}
2170
2171/// How a [`TestSetup`] ended.
2172#[derive(Clone, Debug, Default, PartialEq, Eq)]
2173pub enum SetupOutcome {
2174    /// Every step succeeded, so the suite's tests can run.
2175    #[default]
2176    Succeeded,
2177    /// The setup was skipped, which skips the entire test suite.
2178    Skipped(String),
2179    /// Deploying the test contract failed.
2180    DeploymentFailed(String),
2181    /// Any other step failed, such as deploying a library or calling `setUp()`.
2182    Failed(String),
2183}
2184
2185impl SetupOutcome {
2186    /// Whether the setup succeeded.
2187    pub const fn is_success(&self) -> bool {
2188        matches!(self, Self::Succeeded)
2189    }
2190
2191    /// The reason the setup was skipped or failed, if it was.
2192    pub fn reason(&self) -> Option<&str> {
2193        match self {
2194            Self::Succeeded => None,
2195            Self::Skipped(reason) | Self::DeploymentFailed(reason) | Self::Failed(reason) => {
2196                Some(reason)
2197            }
2198        }
2199    }
2200
2201    /// The function that the result of a skipped or failed setup is reported under.
2202    pub const fn function_name(&self) -> &'static str {
2203        match self {
2204            Self::DeploymentFailed(_) => "constructor()",
2205            Self::Succeeded | Self::Skipped(_) | Self::Failed(_) => "setUp()",
2206        }
2207    }
2208}
2209
2210impl TestSetup {
2211    pub fn failed(reason: String) -> Self {
2212        Self { outcome: SetupOutcome::Failed(reason), ..Default::default() }
2213    }
2214
2215    pub fn skipped(reason: String) -> Self {
2216        Self { outcome: SetupOutcome::Skipped(reason), ..Default::default() }
2217    }
2218
2219    pub fn extend<FEN: FoundryEvmNetwork>(
2220        &mut self,
2221        raw: RawCallResult<FEN>,
2222        trace_kind: TraceKind,
2223        fork: Option<U256>,
2224    ) {
2225        self.fuzz_storage.extend(fork, &raw);
2226        extend!(self, raw, trace_kind);
2227    }
2228
2229    pub fn merge_coverages(&mut self, other_coverage: Option<HitMaps>) {
2230        HitMaps::merge_opt(&mut self.coverage, other_coverage);
2231    }
2232}
2233
2234/// Setup storage observations, scoped to the fork on which they were made. Values are deliberately
2235/// not retained: the dictionary must use the accepted state at the start of each test.
2236#[derive(Clone, Debug, Default)]
2237pub(crate) struct SetupStorage {
2238    pub(crate) slots: BTreeMap<(Option<U256>, Address), BTreeSet<U256>>,
2239}
2240
2241impl SetupStorage {
2242    pub(crate) fn extend<FEN: FoundryEvmNetwork>(
2243        &mut self,
2244        fork: Option<U256>,
2245        raw: &RawCallResult<FEN>,
2246    ) {
2247        for change in raw.state_changeset.account_changes() {
2248            let slots = self.slots.entry((fork, change.address)).or_default();
2249            if change.created || change.current.is_none() {
2250                slots.clear();
2251            }
2252            if change.current.is_some() {
2253                slots.extend(change.storage.slots.keys().copied());
2254            }
2255        }
2256        for &(fork, address, slot) in &raw.suspended_storage {
2257            self.slots.entry((fork, address)).or_default().insert(slot);
2258        }
2259    }
2260}
2261
2262pub(crate) fn invariant_campaign_display_name(contract_name: &str) -> String {
2263    format!("{contract_name} invariants")
2264}
2265
2266const fn symbolic_result_schema_version() -> u32 {
2267    SYMBOLIC_RESULT_SCHEMA_VERSION
2268}
2269
2270#[cfg(test)]
2271mod tests {
2272    use super::*;
2273    use foundry_cli::utils::parse_json;
2274
2275    const SYMBOLIC_RESULT_SCHEMA: &str =
2276        include_str!("../../evm/symbolic/assets/symbolic-result.schema.json");
2277    const SYMBOLIC_COUNTEREXAMPLE_SCHEMA: &str =
2278        include_str!("../../evm/symbolic/assets/symbolic-counterexample.schema.json");
2279
2280    fn schema_defs(schema: &serde_json::Value) -> &serde_json::Map<String, serde_json::Value> {
2281        schema["$defs"].as_object().expect("schema $defs object")
2282    }
2283
2284    /// Collects every `$ref` target in `value`.
2285    fn collect_refs<'a>(value: &'a serde_json::Value, refs: &mut Vec<&'a str>) {
2286        match value {
2287            serde_json::Value::Object(map) => {
2288                refs.extend(map.get("$ref").and_then(serde_json::Value::as_str));
2289                for child in map.values() {
2290                    collect_refs(child, refs);
2291                }
2292            }
2293            serde_json::Value::Array(values) => {
2294                for child in values {
2295                    collect_refs(child, refs);
2296                }
2297            }
2298            _ => {}
2299        }
2300    }
2301
2302    #[test]
2303    fn symbolic_schemas_match_result_types() {
2304        let result_schema: serde_json::Value = parse_json(SYMBOLIC_RESULT_SCHEMA).unwrap();
2305        let counterexample_schema: serde_json::Value =
2306            parse_json(SYMBOLIC_COUNTEREXAMPLE_SCHEMA).unwrap();
2307        let result_defs = schema_defs(&result_schema);
2308        let counterexample_defs = schema_defs(&counterexample_schema);
2309
2310        // Every counterexample `$ref` must resolve offline, either locally or into the result
2311        // schema.
2312        let mut refs = Vec::new();
2313        collect_refs(&counterexample_schema, &mut refs);
2314        for reference in refs {
2315            let resolved = if let Some(name) = reference.strip_prefix(
2316                "https://foundry-rs.github.io/schemas/symbolic-result.v1.schema.json#/$defs/",
2317            ) {
2318                result_defs.contains_key(name)
2319            } else if let Some(name) = reference.strip_prefix("#/$defs/") {
2320                counterexample_defs.contains_key(name)
2321            } else {
2322                false
2323            };
2324            assert!(resolved, "unresolved schema ref {reference}");
2325        }
2326
2327        // The solver stats schema must list exactly the serialized `SymbolicStats` fields.
2328        let stats = serde_json::to_value(SymbolicStats::default()).unwrap();
2329        let mut expected = stats.as_object().unwrap().keys().collect::<Vec<_>>();
2330        let mut actual = result_defs["solver_stats"]["properties"]
2331            .as_object()
2332            .unwrap()
2333            .keys()
2334            .collect::<Vec<_>>();
2335        expected.sort();
2336        actual.sort();
2337        assert_eq!(actual, expected);
2338    }
2339
2340    fn outcome_with_results(test_results: Vec<TestResult>) -> TestOutcome {
2341        let test_results = test_results
2342            .into_iter()
2343            .enumerate()
2344            .map(|(idx, result)| (format!("test{idx}()"), result))
2345            .collect();
2346        let suite = SuiteResult::new(Duration::ZERO, test_results, Vec::new());
2347        TestOutcome::new(None, BTreeMap::from([("suite".to_string(), suite)]), false, None)
2348    }
2349
2350    fn failed_result(kind: TestKind) -> TestResult {
2351        TestResult { status: TestStatus::Failure, kind, ..Default::default() }
2352    }
2353
2354    fn failed_invariant(workers: usize) -> TestResult {
2355        let mut kind = invariant_kind(0, 0, 0);
2356        if let TestKind::Invariant { workers: w, .. } = &mut kind {
2357            *w = workers;
2358        }
2359        failed_result(kind)
2360    }
2361
2362    #[test]
2363    fn failed_tests_are_debuggable_only_for_concrete_failures() {
2364        let unit = failed_result(TestKind::Unit { gas: 0 });
2365        assert!(outcome_with_results(vec![unit.clone()]).failed_tests_are_debuggable());
2366        assert!(!outcome_with_results(vec![failed_invariant(1)]).failed_tests_are_debuggable());
2367        assert!(
2368            !outcome_with_results(vec![failed_result(
2369                TestKind::Symbolic(SymbolicStats::default())
2370            )])
2371            .failed_tests_are_debuggable()
2372        );
2373
2374        let mut symbolic_backed = unit;
2375        symbolic_backed.symbolic =
2376            Some(SymbolicResult::pass(&SymbolicConfig::default(), SymbolicStats::default()));
2377        assert!(!outcome_with_results(vec![symbolic_backed]).failed_tests_are_debuggable());
2378    }
2379
2380    #[test]
2381    fn invariant_workers_hint_requires_matching_parallel_worker_counts() {
2382        let hint = |workers: &[usize]| {
2383            outcome_with_results(workers.iter().map(|&w| failed_invariant(w)).collect())
2384                .invariant_workers_hint()
2385        };
2386        assert_eq!(hint(&[3, 3]), Some(3));
2387        assert_eq!(hint(&[2, 3]), None);
2388        assert_eq!(hint(&[1]), None);
2389    }
2390
2391    #[test]
2392    fn invariant_kind_deserializes_legacy_payload_without_workers() {
2393        let kind = serde_json::from_value::<TestKind>(serde_json::json!({
2394            "Invariant": {
2395                "runs": 4,
2396                "calls": 10,
2397                "reverts": 0,
2398                "metrics": {},
2399                "failed_corpus_replays": 0,
2400                "optimization_best_value": null
2401            }
2402        }))
2403        .unwrap();
2404
2405        assert_eq!(kind.invariant_workers(), Some(1));
2406    }
2407}