1use 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#[derive(Clone, Debug)]
48pub struct TestOutcome {
49 pub results: BTreeMap<String, SuiteResult>,
53 pub(crate) json_file_results: Option<BTreeMap<String, SuiteResult>>,
56 pub allow_failure: bool,
58 pub last_run_decoder: Option<CallTraceDecoder>,
64 pub gas_report: Option<GasReport>,
66 pub known_contracts: Option<ContractsByArtifact>,
68 pub fuzz_seed: Option<U256>,
70}
71
72impl TestOutcome {
73 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 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 pub fn successes(&self) -> impl Iterator<Item = (&String, &TestResult)> {
98 self.tests().filter(|(_, t)| t.status.is_success())
99 }
100
101 pub fn skips(&self) -> impl Iterator<Item = (&String, &TestResult)> {
103 self.tests().filter(|(_, t)| t.status.is_skipped())
104 }
105
106 pub fn failures(&self) -> impl Iterator<Item = (&String, &TestResult)> {
108 self.tests().filter(|(_, t)| t.status.is_failure())
109 }
110
111 pub fn tests(&self) -> impl Iterator<Item = (&String, &TestResult)> {
113 self.results.values().flat_map(|suite| suite.tests())
114 }
115
116 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 pub fn passed(&self) -> usize {
129 self.results.values().map(SuiteResult::passed).sum()
130 }
131
132 pub fn skipped(&self) -> usize {
134 self.results.values().map(SuiteResult::skipped).sum()
135 }
136
137 pub fn failed(&self) -> usize {
139 self.results.values().map(SuiteResult::failed).sum()
140 }
141
142 pub fn has_fuzz_failures(&self) -> bool {
144 self.failures().any(|(_, t)| t.kind.is_fuzz() || t.kind.is_invariant())
145 }
146
147 fn failed_tests_are_debuggable(&self) -> bool {
149 self.failures().all(|(_, result)| result.is_debuggable_failure())
150 }
151
152 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 pub fn total_time(&self) -> Duration {
163 self.results.values().map(|suite| suite.duration).sum()
164 }
165
166 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 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 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 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#[derive(Clone, Debug, Serialize)]
255pub struct SuiteResult {
256 #[serde(with = "foundry_common::serde_helpers::duration")]
258 pub duration: Duration,
259 pub test_results: BTreeMap<String, TestResult>,
261 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 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 pub fn successes(&self) -> impl Iterator<Item = (&String, &TestResult)> {
294 self.tests().filter(|(_, t)| t.status.is_success())
295 }
296
297 pub fn skips(&self) -> impl Iterator<Item = (&String, &TestResult)> {
299 self.tests().filter(|(_, t)| t.status.is_skipped())
300 }
301
302 pub fn failures(&self) -> impl Iterator<Item = (&String, &TestResult)> {
304 self.tests().filter(|(_, t)| t.status.is_failure())
305 }
306
307 pub fn passed(&self) -> usize {
309 self.test_results.values().filter(|t| t.status.is_success()).count()
310 }
311
312 pub fn skipped(&self) -> usize {
314 self.test_results.values().map(TestResult::skipped_count).sum()
315 }
316
317 pub fn failed(&self) -> usize {
319 self.test_results.values().filter(|t| t.status.is_failure()).count()
320 }
321
322 pub fn tests(&self) -> impl Iterator<Item = (&String, &TestResult)> {
324 self.test_results.iter()
325 }
326
327 pub fn is_empty(&self) -> bool {
329 self.test_results.is_empty()
330 }
331
332 pub fn len(&self) -> usize {
334 self.test_results.values().map(TestResult::logical_count).sum()
335 }
336
337 pub fn total_time(&self) -> Duration {
341 self.test_results.values().map(|result| result.duration).sum()
342 }
343
344 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#[derive(Clone, Debug)]
363pub struct SuiteTestResult {
364 pub artifact_id: String,
367 pub signature: String,
369 pub result: TestResult,
371}
372
373impl SuiteTestResult {
374 pub const fn gas_used(&self) -> u64 {
376 self.result.kind.report().gas()
377 }
378
379 pub fn contract_name(&self) -> &str {
381 get_contract_name(&self.artifact_id)
382 }
383}
384
385#[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 #[inline]
397 pub const fn is_success(self) -> bool {
398 matches!(self, Self::Success)
399 }
400
401 #[inline]
403 pub const fn is_failure(self) -> bool {
404 matches!(self, Self::Failure)
405 }
406
407 #[inline]
409 pub const fn is_skipped(self) -> bool {
410 matches!(self, Self::Skipped)
411 }
412}
413
414#[derive(Clone, Debug, Serialize, Deserialize)]
417#[serde(tag = "kind", rename_all = "snake_case")]
418pub enum InvariantFailure {
419 Predicate {
421 name: String,
423 reason: String,
425 #[serde(default, skip_serializing_if = "Option::is_none")]
427 counterexample: Option<CounterExample>,
428 #[serde(default, skip_serializing_if = "Option::is_none")]
430 artifact: Option<SymbolicArtifactRef>,
431 #[serde(default, skip_serializing_if = "Option::is_none")]
433 minimization: Option<SymbolicCounterexampleMinimization>,
434 persisted_path: PathBuf,
436 #[serde(default)]
440 is_anchor: bool,
441 },
442 Handler {
444 name: String,
447 reverter: Address,
449 selector: Selector,
451 reason: String,
453 #[serde(default, skip_serializing_if = "Option::is_none")]
455 counterexample: Option<CounterExample>,
456 #[serde(default, skip_serializing_if = "Option::is_none")]
458 artifact: Option<SymbolicArtifactRef>,
459 },
460}
461
462impl InvariantFailure {
463 pub fn reason(&self) -> &str {
465 match self {
466 Self::Predicate { reason, .. } | Self::Handler { reason, .. } => reason,
467 }
468 }
469
470 pub fn name(&self) -> &str {
472 match self {
473 Self::Predicate { name, .. } | Self::Handler { name, .. } => name,
474 }
475 }
476
477 pub fn predicate_name(&self) -> Option<&str> {
479 match self {
480 Self::Predicate { name, .. } => Some(name),
481 Self::Handler { .. } => None,
482 }
483 }
484
485 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 pub const fn artifact(&self) -> Option<&SymbolicArtifactRef> {
496 match self {
497 Self::Predicate { artifact, .. } | Self::Handler { artifact, .. } => artifact.as_ref(),
498 }
499 }
500
501 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#[derive(Clone, Debug, Serialize, Deserialize)]
512pub struct InvariantPredicateResult {
513 pub name: String,
515 pub status: TestStatus,
517 #[serde(default, skip_serializing_if = "Option::is_none")]
519 pub reason: Option<String>,
520}
521
522#[derive(Clone, Debug, Serialize, Deserialize)]
524pub struct SymbolicResult {
525 #[serde(default = "symbolic_result_schema_version")]
527 pub schema_version: u32,
528 pub status: SymbolicResultStatus,
530 pub incomplete: Option<SymbolicIncomplete>,
532 pub bounds: SymbolicBounds,
534 pub solver: SymbolicSolverMetadata,
536 pub assumptions: Vec<SymbolicAssumption>,
538 pub call_trace: SymbolicCallTrace,
540 pub replay: SymbolicReplayMetadata,
542 pub counterexample: Option<SymbolicCounterexample>,
544 #[serde(default, skip_serializing_if = "Option::is_none")]
546 pub corpus_seeds: Option<SymbolicCorpusSeedMetadata>,
547 #[serde(default, skip_serializing_if = "Option::is_none")]
549 pub artifact: Option<SymbolicArtifactRef>,
550 #[serde(default, skip_serializing_if = "Option::is_none")]
552 pub minimization: Option<SymbolicCounterexampleMinimization>,
553}
554
555impl SymbolicResult {
556 pub fn pass(config: &SymbolicConfig, stats: SymbolicStats) -> Self {
558 Self::base(config, stats)
559 }
560
561 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 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 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 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 pub fn with_corpus_seeds(mut self, corpus_seeds: SymbolicCorpusSeedMetadata) -> Self {
633 self.corpus_seeds = Some(corpus_seeds);
634 self
635 }
636
637 pub fn with_artifact(mut self, artifact: SymbolicArtifactRef) -> Self {
639 self.artifact = Some(artifact);
640 self
641 }
642
643 pub fn with_minimization(mut self, minimization: SymbolicCounterexampleMinimization) -> Self {
645 self.minimization = Some(minimization);
646 self
647 }
648}
649
650#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
652pub struct SymbolicCorpusSeedMetadata {
653 pub corpus_dir: Option<PathBuf>,
655 pub limit: usize,
657 pub loaded: usize,
659 pub skipped: usize,
661 pub used: Vec<SymbolicCorpusSeedRef>,
663}
664
665#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
667pub struct SymbolicCorpusSeedRef {
668 pub path: PathBuf,
670 pub calldata: Bytes,
672}
673
674#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
676pub struct SymbolicArtifactRef {
677 pub schema: String,
679 pub path: PathBuf,
681}
682
683impl SymbolicArtifactRef {
684 pub fn new(path: impl Into<PathBuf>) -> Self {
686 Self { schema: SYMBOLIC_COUNTEREXAMPLE_ARTIFACT_SCHEMA.to_string(), path: path.into() }
687 }
688}
689
690#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
692pub struct SymbolicRegressionRef {
693 pub artifact: PathBuf,
695 pub path: PathBuf,
697}
698
699#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
701#[serde(deny_unknown_fields)]
702pub struct SymbolicCounterexampleMinimization {
703 pub original: SymbolicArtifactRef,
705 pub minimized: SymbolicArtifactRef,
707 pub attempts: usize,
709 pub accepted: usize,
711 pub original_calldata_bytes: usize,
713 pub minimized_calldata_bytes: usize,
715 #[serde(default, skip_serializing_if = "Option::is_none")]
717 pub original_sequence_len: Option<usize>,
718 #[serde(default, skip_serializing_if = "Option::is_none")]
720 pub minimized_sequence_len: Option<usize>,
721}
722
723impl SymbolicCounterexampleMinimization {
724 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 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
759#[serde(rename_all = "snake_case")]
760pub enum SymbolicResultStatus {
761 Pass,
763 FailCounterexample,
765 Incomplete,
767}
768
769#[derive(Clone, Debug, Serialize, Deserialize)]
771pub struct SymbolicIncomplete {
772 pub kind: String,
774 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#[derive(Clone, Debug, Serialize, Deserialize)]
792pub struct SymbolicBounds {
793 pub timeout_seconds: Option<u32>,
795 pub loop_bound: Option<u32>,
797 pub max_depth: u32,
799 pub max_paths: u32,
801 pub invariant_depth: u32,
803 pub exploration_order: SymbolicExplorationOrder,
805 pub max_solver_queries: u32,
807 pub default_dynamic_length: u32,
809 pub max_dynamic_length: u32,
811 pub array_lengths: Vec<u32>,
813 pub dynamic_lengths: BTreeMap<String, Vec<u32>>,
815 pub default_array_lengths: Vec<u32>,
817 pub default_bytes_lengths: Vec<u32>,
819 pub max_calldata_bytes: u32,
821 pub symbolic_call_targets: bool,
823 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#[derive(Clone, Debug, Serialize, Deserialize)]
852pub struct SymbolicSolverMetadata {
853 pub name: String,
855 pub command: Option<String>,
857 pub portfolio: Vec<String>,
859 pub stats: SymbolicStats,
861}
862
863#[derive(Clone, Debug, Serialize, Deserialize)]
865pub struct SymbolicAssumption {
866 pub kind: String,
868 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#[derive(Clone, Debug, Serialize, Deserialize)]
889pub struct SymbolicCallTrace {
890 pub available: bool,
892 pub source: Option<String>,
894 pub format: Option<String>,
896}
897
898impl SymbolicCallTrace {
899 pub const fn none() -> Self {
901 Self { available: false, source: None, format: None }
902 }
903
904 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
916#[serde(rename_all = "snake_case")]
917pub enum SymbolicReplayStatus {
918 NotRequired,
920 Confirmed,
922 Mismatch,
924 Error,
926 Skipped,
928}
929
930#[derive(Clone, Debug, Serialize, Deserialize)]
932#[serde(deny_unknown_fields)]
933pub struct SymbolicReplayMetadata {
934 pub required: bool,
936 pub status: SymbolicReplayStatus,
938 pub reason: Option<String>,
940}
941
942impl SymbolicReplayMetadata {
943 pub const fn not_required() -> Self {
945 Self { required: false, status: SymbolicReplayStatus::NotRequired, reason: None }
946 }
947
948 pub const fn confirmed() -> Self {
950 Self { required: true, status: SymbolicReplayStatus::Confirmed, reason: None }
951 }
952
953 pub fn mismatch(reason: impl Into<String>) -> Self {
955 Self { required: true, status: SymbolicReplayStatus::Mismatch, reason: Some(reason.into()) }
956 }
957
958 pub fn error(reason: impl Into<String>) -> Self {
960 Self { required: true, status: SymbolicReplayStatus::Error, reason: Some(reason.into()) }
961 }
962
963 pub fn skipped(reason: impl Into<String>) -> Self {
965 Self { required: true, status: SymbolicReplayStatus::Skipped, reason: Some(reason.into()) }
966 }
967}
968
969#[derive(Clone, Debug, Serialize, Deserialize)]
971pub struct SymbolicCounterexample {
972 pub calldata: Bytes,
974 pub args: Option<String>,
976 pub raw_args: Option<String>,
978 pub value: Option<U256>,
980 #[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#[derive(Clone, Debug, Serialize, Deserialize)]
999#[serde(deny_unknown_fields)]
1000pub struct SymbolicCounterexampleArtifact {
1001 pub schema_version: u32,
1003 pub schema: String,
1005 pub kind: SymbolicCounterexampleArtifactKind,
1007 pub test: SymbolicCounterexampleTestIdentity,
1009 pub replay: SymbolicReplayMetadata,
1011 pub replay_semantics: SymbolicCounterexampleReplaySemantics,
1013 pub bounds: SymbolicBounds,
1015 pub solver: SymbolicSolverMetadata,
1017 pub assumptions: Vec<SymbolicAssumption>,
1019 pub call_trace: SymbolicCallTrace,
1021 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1023 pub storage: Vec<SymbolicStorageAssignment>,
1024 #[serde(default, skip_serializing_if = "Option::is_none")]
1026 pub invariant_failure: Option<SymbolicInvariantArtifactFailure>,
1027 pub calls: Vec<SymbolicCounterexampleCall>,
1029}
1030
1031impl SymbolicCounterexampleArtifact {
1032 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 pub fn with_storage(mut self, storage: Vec<SymbolicStorageAssignment>) -> Self {
1059 self.storage = storage;
1060 self
1061 }
1062
1063 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#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
1075#[serde(deny_unknown_fields)]
1076pub struct SymbolicCounterexampleReplaySemantics {
1077 pub fail_on_revert: bool,
1079}
1080
1081#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1083#[serde(rename_all = "snake_case")]
1084pub enum SymbolicCounterexampleArtifactKind {
1085 SingleCall,
1087 Sequence,
1089}
1090
1091#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1093#[serde(tag = "kind", rename_all = "snake_case")]
1094pub enum SymbolicInvariantArtifactFailure {
1095 Predicate {
1097 name: String,
1099 #[serde(default, skip_serializing_if = "Option::is_none")]
1101 site: Option<SymbolicInvariantFailureSite>,
1102 },
1103 Handler {
1105 #[serde(default, skip_serializing_if = "Option::is_none")]
1107 name: Option<String>,
1108 reverter: Address,
1110 selector: Selector,
1112 fingerprint: B256,
1114 },
1115}
1116
1117#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1119#[serde(tag = "kind", rename_all = "snake_case")]
1120pub enum SymbolicInvariantFailureSite {
1121 SequenceCall { target: Address, selector: Selector, fingerprint: B256 },
1123 Invariant { target: Address, selector: Selector, fingerprint: B256 },
1125 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#[derive(Clone, Debug, Serialize, Deserialize)]
1147#[serde(deny_unknown_fields)]
1148pub struct SymbolicCounterexampleTestIdentity {
1149 pub contract: String,
1151 pub test: String,
1153}
1154
1155#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1157#[serde(deny_unknown_fields)]
1158pub struct SymbolicCounterexampleCall {
1159 pub warp: Option<U256>,
1161 pub roll: Option<U256>,
1163 pub sender: Address,
1165 pub target: Address,
1167 pub calldata: Bytes,
1169 pub value: Option<U256>,
1171 pub contract_name: Option<String>,
1173 pub function_name: Option<String>,
1175 pub signature: Option<String>,
1177 pub args: Option<String>,
1179 pub raw_args: Option<String>,
1181 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1184 pub svm_returns: Vec<Bytes>,
1185}
1186
1187impl SymbolicCounterexampleCall {
1188 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 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 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#[derive(Clone, Debug, Default, Serialize, Deserialize)]
1248pub struct TestResult {
1249 pub status: TestStatus,
1253
1254 pub reason: Option<String>,
1256
1257 #[serde(default, skip_serializing_if = "Option::is_none")]
1259 pub fork_block_number: Option<u64>,
1260
1261 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1266 pub invariant_failures: Vec<InvariantFailure>,
1267
1268 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1272 pub invariant_predicate_results: Vec<InvariantPredicateResult>,
1273
1274 #[serde(default, skip_serializing_if = "Option::is_none")]
1277 pub invariant_failure_dir: Option<PathBuf>,
1278
1279 #[serde(default, skip_serializing_if = "Option::is_none")]
1284 pub invariant_count: Option<usize>,
1285
1286 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1290 pub invariant_handler_failures: Vec<InvariantFailure>,
1291
1292 pub counterexample: Option<CounterExample>,
1294
1295 #[serde(default, skip_serializing_if = "Option::is_none")]
1300 pub counterexample_artifact: Option<SymbolicArtifactRef>,
1301
1302 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1304 pub counterexample_artifacts: Vec<SymbolicArtifactRef>,
1305
1306 #[serde(default, skip_serializing_if = "Vec::is_empty")]
1308 pub symbolic_regressions: Vec<SymbolicRegressionRef>,
1309
1310 pub logs: Vec<Log>,
1313
1314 pub decoded_logs: Vec<String>,
1317
1318 pub kind: TestKind,
1320
1321 #[serde(default, skip_serializing_if = "Option::is_none")]
1323 pub symbolic: Option<SymbolicResult>,
1324
1325 #[serde(default, skip_serializing_if = "Option::is_none")]
1327 pub symbolic_live: Option<LiveInvariantStats>,
1328
1329 pub traces: Traces,
1331
1332 #[serde(skip)]
1334 pub debug_bytecodes: AddressHashMap<Bytes>,
1335
1336 #[serde(skip)]
1340 pub gas_report_traces: Vec<Vec<CallTraceArena>>,
1341
1342 #[serde(skip)]
1344 pub line_coverage: Option<HitMaps>,
1345
1346 #[serde(rename = "labeled_addresses")] pub labels: AddressHashMap<String>,
1349
1350 #[serde(with = "foundry_common::serde_helpers::duration")]
1351 pub duration: Duration,
1352
1353 pub breakpoints: Breakpoints,
1355
1356 pub gas_snapshots: BTreeMap<String, BTreeMap<String, String>>,
1358
1359 #[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
1370fn 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
1378fn 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
1390fn 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 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 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 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 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 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 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 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 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#[derive(Default)]
1569pub struct InvariantOutcome {
1570 pub success: bool,
1572 pub fork_block_number: Option<u64>,
1574 pub failures: Vec<InvariantFailure>,
1576 pub handler_failures: Vec<InvariantFailure>,
1578 pub predicate_results: Vec<InvariantPredicateResult>,
1580 pub failure_dir: Option<PathBuf>,
1582 pub invariant_count: Option<usize>,
1584 pub counterexample: Option<CounterExample>,
1586 pub gas_report_traces: Vec<Vec<CallTraceArena>>,
1588}
1589
1590pub(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 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 pub fn fail(reason: String) -> Self {
1619 Self { status: TestStatus::Failure, reason: Some(reason), ..Default::default() }
1620 }
1621
1622 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 pub fn single_skip(&mut self, reason: SkipReason) {
1643 self.status = TestStatus::Skipped;
1644 self.reason = reason.0;
1645 }
1646
1647 pub fn single_fail(&mut self, reason: Option<String>) {
1649 self.status = TestStatus::Failure;
1650 self.reason = reason;
1651 }
1652
1653 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 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 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 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 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 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 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 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 pub fn invariant_result(&mut self, kind: TestKind, outcome: InvariantOutcome) {
1789 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 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 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 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 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 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 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 if self.invariant_count.is_none() {
1875 self.reason = reason;
1876 }
1877 }
1878
1879 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 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 pub fn extend<FEN: FoundryEvmNetwork>(&mut self, call_result: RawCallResult<FEN>) {
1917 extend!(self, call_result, TraceKind::Execution);
1918 }
1919
1920 pub(crate) fn extend_setup<FEN: FoundryEvmNetwork>(&mut self, call_result: RawCallResult<FEN>) {
1922 extend!(self, call_result, TraceKind::Setup);
1923 }
1924
1925 pub fn merge_coverages(&mut self, other_coverage: Option<HitMaps>) {
1927 HitMaps::merge_opt(&mut self.line_coverage, other_coverage);
1928 }
1929}
1930
1931#[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 optimization_best_value: Option<I256>,
1950 },
1951 Table {
1952 runs: usize,
1953 mean_gas: u64,
1954 median_gas: u64,
1955 },
1956 Symbolic(SymbolicStats),
1957 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 pub const fn gas(&self) -> u64 {
2026 match *self {
2027 Self::Unit { gas } => gas,
2028 Self::Fuzz { median_gas, .. } | Self::Table { median_gas, .. } => median_gas,
2030 Self::Invariant { .. } | Self::Symbolic { .. } | Self::Replay { .. } => 0,
2032 }
2033 }
2034}
2035
2036#[derive(Clone, Debug, Serialize, Deserialize)]
2038pub enum TestKind {
2039 Unit { gas: u64 },
2041 Fuzz {
2043 first_case: FuzzCase,
2045 runs: usize,
2046 mean_gas: u64,
2047 median_gas: u64,
2048 failed_corpus_replays: usize,
2049 },
2050 Invariant {
2052 runs: usize,
2053 calls: usize,
2054 reverts: usize,
2055 #[serde(default = "default_invariant_workers")]
2057 workers: usize,
2058 metrics: Map<String, InvariantMetrics>,
2059 failed_corpus_replays: usize,
2060 optimization_best_value: Option<I256>,
2062 },
2063 Table { runs: usize, mean_gas: u64, median_gas: u64 },
2065 Symbolic(SymbolicStats),
2067 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 pub const fn is_fuzz(&self) -> bool {
2080 matches!(self, Self::Fuzz { .. })
2081 }
2082
2083 pub const fn is_invariant(&self) -> bool {
2085 matches!(self, Self::Invariant { .. })
2086 }
2087
2088 pub const fn is_symbolic(&self) -> bool {
2090 matches!(self, Self::Symbolic { .. })
2091 }
2092
2093 pub const fn invariant_workers(&self) -> Option<usize> {
2095 match self {
2096 Self::Invariant { workers, .. } => Some(*workers),
2097 _ => None,
2098 }
2099 }
2100
2101 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#[derive(Clone, Debug, Default)]
2142pub struct TestSetup {
2143 pub address: Address,
2145 pub fuzz_fixtures: FuzzFixtures,
2147
2148 pub logs: Vec<Log>,
2150 pub labels: AddressHashMap<String>,
2152 pub traces: Traces,
2154 pub debug_bytecodes: AddressHashMap<Bytes>,
2156 pub coverage: Option<HitMaps>,
2158 pub deployed_libs: Vec<Address>,
2160 pub fork_block_number: Option<u64>,
2162 pub(crate) fuzz_state: OnceLock<EvmFuzzState>,
2164 pub(crate) fuzz_storage: SetupStorage,
2166
2167 pub outcome: SetupOutcome,
2169}
2170
2171#[derive(Clone, Debug, Default, PartialEq, Eq)]
2173pub enum SetupOutcome {
2174 #[default]
2176 Succeeded,
2177 Skipped(String),
2179 DeploymentFailed(String),
2181 Failed(String),
2183}
2184
2185impl SetupOutcome {
2186 pub const fn is_success(&self) -> bool {
2188 matches!(self, Self::Succeeded)
2189 }
2190
2191 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 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#[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 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 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 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}