Skip to main content

forge/cmd/test/
filter.rs

1use alloy_json_abi::Function;
2use clap::Parser;
3use foundry_common::{
4    TestFilter, TestFunctionKind,
5    fs::{canonicalize_path, normalize_path},
6};
7use foundry_compilers::{FileFilter, ProjectPathsConfig};
8use foundry_config::{Config, filter::GlobMatcher};
9use serde::{Deserialize, Serialize};
10use std::{
11    fmt,
12    path::{Path, PathBuf},
13};
14
15/// A failed test persisted for `forge test --rerun`.
16#[derive(Clone, Debug, Deserialize, Serialize)]
17pub struct RerunFailure {
18    /// The test suite identifier (`path:contract_name`).
19    pub contract: String,
20    /// The test signature or invariant predicate name.
21    pub test: String,
22}
23
24/// Persisted `forge test --rerun` failures.
25#[derive(Clone, Debug, Deserialize, Serialize)]
26pub struct RerunFailures {
27    pub version: u8,
28    pub failures: Vec<RerunFailure>,
29}
30
31/// The filter to use during testing.
32///
33/// See also `FileFilter`.
34#[derive(Clone, Default, Parser)]
35#[command(next_help_heading = "Test filtering")]
36pub struct FilterArgs {
37    /// Only run test functions matching the specified regex pattern.
38    #[arg(long = "match-test", visible_alias = "mt", value_name = "REGEX")]
39    pub test_pattern: Option<regex::Regex>,
40
41    /// Only run test functions that do not match the specified regex pattern.
42    #[arg(long = "no-match-test", visible_alias = "nmt", value_name = "REGEX")]
43    pub test_pattern_inverse: Option<regex::Regex>,
44
45    /// Only run tests in contracts matching the specified regex pattern.
46    #[arg(long = "match-contract", visible_alias = "mc", value_name = "REGEX")]
47    pub contract_pattern: Option<regex::Regex>,
48
49    /// Only run tests in contracts that do not match the specified regex pattern.
50    #[arg(long = "no-match-contract", visible_alias = "nmc", value_name = "REGEX")]
51    pub contract_pattern_inverse: Option<regex::Regex>,
52
53    /// Only run tests in source files matching the specified glob pattern.
54    #[arg(long = "match-path", visible_alias = "mp", value_name = "GLOB")]
55    pub path_pattern: Option<GlobMatcher>,
56
57    /// Only run tests in source files that do not match the specified glob pattern.
58    #[arg(
59        id = "no-match-path",
60        long = "no-match-path",
61        visible_alias = "nmp",
62        value_name = "GLOB"
63    )]
64    pub path_pattern_inverse: Option<GlobMatcher>,
65
66    /// Only show coverage for files that do not match the specified regex pattern.
67    #[arg(long = "no-match-coverage", visible_alias = "nmco", value_name = "REGEX")]
68    pub coverage_pattern_inverse: Option<regex::Regex>,
69}
70
71impl FilterArgs {
72    /// Returns true if the filter is empty.
73    pub const fn is_empty(&self) -> bool {
74        self.test_pattern.is_none()
75            && self.test_pattern_inverse.is_none()
76            && self.contract_pattern.is_none()
77            && self.contract_pattern_inverse.is_none()
78            && self.path_pattern.is_none()
79            && self.path_pattern_inverse.is_none()
80    }
81
82    /// Merges the set filter globs with the config's values
83    pub fn merge_with_config(mut self, config: &Config) -> ProjectPathsAwareFilter {
84        self.test_pattern =
85            self.test_pattern.or_else(|| config.test_pattern.clone().map(Into::into));
86        self.test_pattern_inverse = self
87            .test_pattern_inverse
88            .or_else(|| config.test_pattern_inverse.clone().map(Into::into));
89        self.contract_pattern =
90            self.contract_pattern.or_else(|| config.contract_pattern.clone().map(Into::into));
91        self.contract_pattern_inverse = self
92            .contract_pattern_inverse
93            .or_else(|| config.contract_pattern_inverse.clone().map(Into::into));
94        self.path_pattern =
95            self.path_pattern.or_else(|| config.path_pattern.clone().map(Into::into));
96        self.path_pattern_inverse = self
97            .path_pattern_inverse
98            .or_else(|| config.path_pattern_inverse.clone().map(Into::into));
99        self.coverage_pattern_inverse = self
100            .coverage_pattern_inverse
101            .or_else(|| config.coverage_pattern_inverse.clone().map(Into::into));
102        ProjectPathsAwareFilter {
103            args_filter: self,
104            paths: config.project_paths(),
105            rerun_failures: None,
106            external_compiler_roots: config
107                .external_compilers
108                .iter()
109                .flat_map(|compiler| &compiler.roots)
110                // External artifacts use canonical source paths, including through symlink roots.
111                .map(|root| {
112                    let path = config.root.join(root);
113                    canonicalize_path(&path).unwrap_or_else(|_| normalize_path(&path))
114                })
115                .collect(),
116        }
117    }
118
119    /// Returns all patterns as `(flag, pattern)` pairs.
120    fn patterns(&self) -> [(&'static str, Option<&str>); 7] {
121        [
122            ("match-test", self.test_pattern.as_ref().map(|r| r.as_str())),
123            ("no-match-test", self.test_pattern_inverse.as_ref().map(|r| r.as_str())),
124            ("match-contract", self.contract_pattern.as_ref().map(|r| r.as_str())),
125            ("no-match-contract", self.contract_pattern_inverse.as_ref().map(|r| r.as_str())),
126            ("match-path", self.path_pattern.as_ref().map(|g| g.as_str())),
127            ("no-match-path", self.path_pattern_inverse.as_ref().map(|g| g.as_str())),
128            ("no-match-coverage", self.coverage_pattern_inverse.as_ref().map(|r| r.as_str())),
129        ]
130    }
131}
132
133impl fmt::Debug for FilterArgs {
134    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
135        let mut s = f.debug_struct("FilterArgs");
136        for (name, pattern) in self.patterns() {
137            s.field(name, &pattern);
138        }
139        s.finish_non_exhaustive()
140    }
141}
142
143impl FileFilter for FilterArgs {
144    /// Returns true if the file regex pattern match the `file`
145    ///
146    /// If no file regex is set this returns true by default
147    fn is_match(&self, file: &Path) -> bool {
148        self.matches_path(file)
149    }
150}
151
152impl TestFilter for FilterArgs {
153    fn matches_test(&self, test_signature: &str) -> bool {
154        self.test_pattern.as_ref().is_none_or(|re| re.is_match(test_signature))
155            && self.test_pattern_inverse.as_ref().is_none_or(|re| !re.is_match(test_signature))
156    }
157
158    fn matches_contract(&self, contract_name: &str) -> bool {
159        self.contract_pattern.as_ref().is_none_or(|re| re.is_match(contract_name))
160            && self.contract_pattern_inverse.as_ref().is_none_or(|re| !re.is_match(contract_name))
161    }
162
163    fn matches_path(&self, path: &Path) -> bool {
164        self.path_pattern.as_ref().is_none_or(|g| g.is_match(path))
165            && self.path_pattern_inverse.as_ref().is_none_or(|g| !g.is_match(path))
166    }
167}
168
169impl fmt::Display for FilterArgs {
170    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
171        for (name, pattern) in self.patterns() {
172            if let Some(pattern) = pattern {
173                writeln!(f, "\t{name}: `{pattern}`")?;
174            }
175        }
176        Ok(())
177    }
178}
179
180/// A filter that combines all command line arguments and the paths of the current projects
181#[derive(Clone, Debug)]
182pub struct ProjectPathsAwareFilter {
183    args_filter: FilterArgs,
184    paths: ProjectPathsConfig,
185    rerun_failures: Option<Vec<RerunFailure>>,
186    external_compiler_roots: Vec<PathBuf>,
187}
188
189impl ProjectPathsAwareFilter {
190    /// Returns true if the filter is empty.
191    pub const fn is_empty(&self) -> bool {
192        self.args_filter.is_empty()
193    }
194
195    /// Returns the CLI arguments.
196    pub const fn args(&self) -> &FilterArgs {
197        &self.args_filter
198    }
199
200    /// Returns the CLI arguments mutably.
201    pub const fn args_mut(&mut self) -> &mut FilterArgs {
202        &mut self.args_filter
203    }
204
205    /// Returns the project paths.
206    pub const fn paths(&self) -> &ProjectPathsConfig {
207        &self.paths
208    }
209
210    /// Sets exact contract/test pairs persisted by `forge test --rerun`.
211    pub fn set_rerun_failures(&mut self, failures: Vec<RerunFailure>) {
212        self.rerun_failures = Some(failures);
213    }
214
215    /// Returns exact contract/test pairs persisted by `forge test --rerun`.
216    pub fn rerun_failures(&self) -> Option<&[RerunFailure]> {
217        self.rerun_failures.as_deref()
218    }
219
220    fn matches_rerun_contract(&self, failure_contract: &str, contract_id: &str) -> bool {
221        if failure_contract == contract_id {
222            return true;
223        }
224        let (Some((failure_path, failure_name)), Some((contract_path, contract_name))) =
225            (failure_contract.rsplit_once(':'), contract_id.rsplit_once(':'))
226        else {
227            return false;
228        };
229        if failure_name != contract_name {
230            return false;
231        }
232
233        let normalize = |path: &str| {
234            let path = Path::new(path);
235            if let Ok(path) = path.strip_prefix(&self.paths.root) {
236                return path.to_path_buf();
237            }
238            if path.is_absolute()
239                && let Ok(root) = canonicalize_path(&self.paths.root)
240                && let Ok(path) = canonicalize_path(path)
241                && let Ok(path) = path.strip_prefix(root)
242            {
243                return path.to_path_buf();
244            }
245            path.to_path_buf()
246        };
247        normalize(failure_path) == normalize(contract_path)
248    }
249
250    /// Returns whether `path` matches the CLI path filters and lies inside the project root,
251    /// outside its libraries and `node_modules`, but in none of the roots that test discovery
252    /// runs.
253    pub fn is_outside_test_roots(&self, path: &Path) -> bool {
254        let relative_path = path.strip_prefix(&self.paths.root).unwrap_or(path);
255        let path = normalize_path(&self.paths.root.join(path));
256        self.args_filter.matches_path(relative_path)
257            && path.strip_prefix(&self.paths.root).is_ok_and(|project_path| {
258                !project_path.components().any(|component| component.as_os_str() == "node_modules")
259            })
260            && !self.paths.has_library_ancestor(&path)
261            && !self.is_in_test_roots(&path)
262    }
263
264    /// Returns whether the normalized absolute `path` is under a root that test discovery runs.
265    fn is_in_test_roots(&self, path: &Path) -> bool {
266        [&self.paths.sources, &self.paths.tests, &self.paths.scripts]
267            .into_iter()
268            .chain(&self.external_compiler_roots)
269            .any(|dir| path.starts_with(self.paths.root.join(dir)))
270    }
271}
272
273impl FileFilter for ProjectPathsAwareFilter {
274    /// Returns true if the file regex pattern match the `file`
275    ///
276    /// If no file regex is set this returns true by default
277    fn is_match(&self, mut file: &Path) -> bool {
278        file = file.strip_prefix(&self.paths.root).unwrap_or(file);
279        self.args_filter.is_match(file)
280    }
281}
282
283impl TestFilter for ProjectPathsAwareFilter {
284    fn matches_test(&self, test_signature: &str) -> bool {
285        self.args_filter.matches_test(test_signature)
286    }
287
288    fn matches_contract(&self, contract_name: &str) -> bool {
289        self.args_filter.matches_contract(contract_name)
290    }
291
292    fn matches_path(&self, path: &Path) -> bool {
293        let relative_path = path.strip_prefix(&self.paths.root).unwrap_or(path);
294        if !self.args_filter.matches_path(relative_path) {
295            return false;
296        }
297
298        // Imported dependencies are compiled too, but only project files may run as test suites.
299        // Normalize `..` without resolving links, which the compiler's walker preserves.
300        let path = normalize_path(&self.paths.root.join(path));
301        self.is_in_test_roots(&path) && !self.paths.has_library_ancestor(&path)
302    }
303
304    fn matches_test_function_kind_in_contract(
305        &self,
306        contract_id: &str,
307        func: &Function,
308        kind: TestFunctionKind,
309    ) -> bool {
310        let signature = func.signature();
311        if !kind.is_any_test() || !self.args_filter.matches_test(&signature) {
312            return false;
313        }
314        let Some(failures) = &self.rerun_failures else { return true };
315        let name = signature.split('(').next().unwrap_or(&signature);
316        failures.iter().any(|failure| {
317            self.matches_rerun_contract(&failure.contract, contract_id)
318                && (failure.test == signature || failure.test == name)
319        })
320    }
321}
322
323impl fmt::Display for ProjectPathsAwareFilter {
324    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
325        self.args_filter.fmt(f)
326    }
327}
328
329#[cfg(test)]
330mod tests {
331    use super::*;
332    use foundry_config::ExternalCompiler;
333
334    #[cfg(unix)]
335    use std::{fs, os::unix::fs::symlink};
336
337    #[test]
338    fn only_matches_configured_project_paths() {
339        let root = tempfile::tempdir().unwrap();
340        let external = tempfile::tempdir().unwrap();
341        let mut config = Config::with_root(root.path());
342        config.src = "contracts".into();
343        config.test = external.path().into();
344        config.script = "tasks".into();
345        config.libs = vec!["contracts/vendor".into(), "lib".into()];
346        config.external_compilers.push(ExternalCompiler {
347            id: "fixture".into(),
348            command: "adapter".into(),
349            args: Vec::new(),
350            roots: vec!["native".into(), "lib".into()],
351            settings: Default::default(),
352        });
353        let config = config.sanitized();
354        let filter = FilterArgs::default().merge_with_config(&config);
355
356        for (path, expected) in [
357            ("contracts/Source.sol", true),
358            ("tasks/Script.sol", true),
359            ("contracts/../tasks/Script.sol", true),
360            ("contracts/../node_modules/Dependency.sol", false),
361            ("contracts-other/Dependency.sol", false),
362            ("contracts/vendor/Dependency.sol", false),
363            ("node_modules/Dependency.sol", false),
364            ("Dependency.sol", false),
365            ("src/Source.sol", false),
366            ("test/Test.sol", false),
367            ("script/Script.sol", false),
368            ("native/Counter.fe", true),
369            ("native/Counter.sol", true),
370            ("native-other/Counter.fe", false),
371            ("native/../dependency/Counter.fe", false),
372            ("lib/Counter.fe", false),
373            ("contracts/../lib/Counter.fe", false),
374        ] {
375            assert_eq!(filter.matches_path(Path::new(path)), expected, "{path}");
376            assert_eq!(filter.matches_path(&config.root.join(path)), expected, "{path}");
377        }
378        assert!(filter.matches_path(&config.test.join("Test.sol")));
379    }
380
381    #[cfg(unix)]
382    #[test]
383    fn matches_external_artifacts_through_symlinked_roots() {
384        let root = tempfile::tempdir().unwrap();
385        let external = tempfile::tempdir().unwrap();
386        fs::write(external.path().join("Counter.fe"), "").unwrap();
387        symlink(external.path(), root.path().join("native")).unwrap();
388        let mut config = Config::with_root(root.path());
389        config.external_compilers.push(ExternalCompiler {
390            id: "fixture".into(),
391            command: "adapter".into(),
392            args: Vec::new(),
393            roots: vec!["native".into()],
394            settings: Default::default(),
395        });
396        let config = config.sanitized();
397        let filter = FilterArgs::default().merge_with_config(&config);
398        let source = canonicalize_path(root.path().join("native/Counter.fe")).unwrap();
399
400        assert!(filter.matches_path(&source));
401    }
402}