foundry_cheatcodes_spec/
lib.rs

Help
1//! Cheatcode specification for Foundry.
2
3#![cfg_attr(not(test), warn(unused_crate_dependencies))]
4#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
5
6use serde::{Deserialize, Serialize};
7use std::{borrow::Cow, fmt};
8
9mod cheatcode;
10pub use cheatcode::{Cheatcode, CheatcodeDef, Group, Safety, Status};
11
12mod function;
13pub use function::{Function, Mutability, Visibility};
14
15mod items;
16pub use items::{Enum, EnumVariant, Error, Event, Struct, StructField};
17
18mod vm;
19pub use vm::Vm;
20
21// The `cheatcodes.json` schema.
22/// Foundry cheatcodes. Learn more: <https://book.getfoundry.sh/cheatcodes/>
23#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
24#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
25#[serde(rename_all = "camelCase")]
26pub struct Cheatcodes<'a> {
27    /// Cheatcode errors.
28    #[serde(borrow)]
29    pub errors: Cow<'a, [Error<'a>]>,
30    /// Cheatcode events.
31    #[serde(borrow)]
32    pub events: Cow<'a, [Event<'a>]>,
33    /// Cheatcode enums.
34    #[serde(borrow)]
35    pub enums: Cow<'a, [Enum<'a>]>,
36    /// Cheatcode structs.
37    #[serde(borrow)]
38    pub structs: Cow<'a, [Struct<'a>]>,
39    /// All the cheatcodes.
40    #[serde(borrow)]
41    pub cheatcodes: Cow<'a, [Cheatcode<'a>]>,
42}
43
44impl fmt::Display for Cheatcodes<'_> {
45    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
46        for error in self.errors.iter() {
47            writeln!(f, "{error}")?;
48        }
49        for event in self.events.iter() {
50            writeln!(f, "{event}")?;
51        }
52        for enumm in self.enums.iter() {
53            writeln!(f, "{enumm}")?;
54        }
55        for strukt in self.structs.iter() {
56            writeln!(f, "{strukt}")?;
57        }
58        for cheatcode in self.cheatcodes.iter() {
59            writeln!(f, "{}", cheatcode.func)?;
60        }
61        Ok(())
62    }
63}
64
65impl Default for Cheatcodes<'static> {
66    fn default() -> Self {
67        Self::new()
68    }
69}
70
71impl Cheatcodes<'static> {
72    /// Returns the default cheatcodes.
73    pub fn new() -> Self {
74        Self {
75            // unfortunately technology has not yet advanced to the point where we can get all
76            // items of a certain type in a module, so we have to hardcode them here
77            structs: Cow::Owned(vec![
78                Vm::Log::STRUCT.clone(),
79                Vm::Rpc::STRUCT.clone(),
80                Vm::EthGetLogs::STRUCT.clone(),
81                Vm::DirEntry::STRUCT.clone(),
82                Vm::FsMetadata::STRUCT.clone(),
83                Vm::Wallet::STRUCT.clone(),
84                Vm::FfiResult::STRUCT.clone(),
85                Vm::ChainInfo::STRUCT.clone(),
86                Vm::Chain::STRUCT.clone(),
87                Vm::AccountAccess::STRUCT.clone(),
88                Vm::StorageAccess::STRUCT.clone(),
89                Vm::Gas::STRUCT.clone(),
90                Vm::DebugStep::STRUCT.clone(),
91                Vm::BroadcastTxSummary::STRUCT.clone(),
92                Vm::SignedDelegation::STRUCT.clone(),
93                Vm::PotentialRevert::STRUCT.clone(),
94                Vm::AccessListItem::STRUCT.clone(),
95            ]),
96            enums: Cow::Owned(vec![
97                Vm::CallerMode::ENUM.clone(),
98                Vm::AccountAccessKind::ENUM.clone(),
99                Vm::ForgeContext::ENUM.clone(),
100                Vm::BroadcastTxType::ENUM.clone(),
101            ]),
102            errors: Vm::VM_ERRORS.iter().copied().cloned().collect(),
103            events: Cow::Borrowed(&[]),
104            // events: Vm::VM_EVENTS.iter().copied().cloned().collect(),
105            cheatcodes: Vm::CHEATCODES.iter().copied().cloned().collect(),
106        }
107    }
108}
109
110#[cfg(test)]
111#[expect(clippy::disallowed_macros)]
112mod tests {
113    use super::*;
114    use std::{fs, path::Path};
115
116    const JSON_PATH: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../assets/cheatcodes.json");
117    #[cfg(feature = "schema")]
118    const SCHEMA_PATH: &str =
119        concat!(env!("CARGO_MANIFEST_DIR"), "/../assets/cheatcodes.schema.json");
120    const IFACE_PATH: &str =
121        concat!(env!("CARGO_MANIFEST_DIR"), "/../../../testdata/cheats/Vm.sol");
122
123    /// Generates the `cheatcodes.json` file contents.
124    fn json_cheatcodes() -> String {
125        serde_json::to_string_pretty(&Cheatcodes::new()).unwrap()
126    }
127
128    /// Generates the [cheatcodes](json_cheatcodes) JSON schema.
129    #[cfg(feature = "schema")]
130    fn json_schema() -> String {
131        serde_json::to_string_pretty(&schemars::schema_for!(Cheatcodes<'_>)).unwrap()
132    }
133
134    fn sol_iface() -> String {
135        let mut cheats = Cheatcodes::new();
136        cheats.errors = Default::default(); // Skip errors to allow <0.8.4.
137        let cheats = cheats.to_string().trim().replace('\n', "\n    ");
138        format!(
139            "\
140// Automatically generated from `foundry-cheatcodes` Vm definitions. Do not modify manually.
141// This interface is just for internal testing purposes. Use `forge-std` instead.
142
143// SPDX-License-Identifier: MIT OR Apache-2.0
144pragma solidity >=0.6.2 <0.9.0;
145pragma experimental ABIEncoderV2;
146
147interface Vm {{
148    {cheats}
149}}
150"
151        )
152    }
153
154    #[test]
155    fn spec_up_to_date() {
156        ensure_file_contents(Path::new(JSON_PATH), &json_cheatcodes());
157    }
158
159    #[test]
160    #[cfg(feature = "schema")]
161    fn schema_up_to_date() {
162        ensure_file_contents(Path::new(SCHEMA_PATH), &json_schema());
163    }
164
165    #[test]
166    fn iface_up_to_date() {
167        ensure_file_contents(Path::new(IFACE_PATH), &sol_iface());
168    }
169
170    /// Checks that the `file` has the specified `contents`. If that is not the
171    /// case, updates the file and then fails the test.
172    fn ensure_file_contents(file: &Path, contents: &str) {
173        if let Ok(old_contents) = fs::read_to_string(file) {
174            if normalize_newlines(&old_contents) == normalize_newlines(contents) {
175                // File is already up to date.
176                return
177            }
178        }
179
180        eprintln!("\n\x1b[31;1merror\x1b[0m: {} was not up-to-date, updating\n", file.display());
181        if std::env::var("CI").is_ok() {
182            eprintln!("    NOTE: run `cargo cheats` locally and commit the updated files\n");
183        }
184        if let Some(parent) = file.parent() {
185            let _ = fs::create_dir_all(parent);
186        }
187        fs::write(file, contents).unwrap();
188        panic!("some file was not up to date and has been updated, simply re-run the tests");
189    }
190
191    fn normalize_newlines(s: &str) -> String {
192        s.replace("\r\n", "\n")
193    }
194}
foundry_cheatcodes_spec/lib.rs

foundry_cheatcodes_spec/
lib.rs
