Fix filtering and command docs (#649)

## Introduced changes

- Filtering now uses whole module tree path
- Fixed `snforge` command docs

## Checklist

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [x] Added relevant tests
- [x] Performed self-review of the code
- [x] Added changes to `CHANGELOG.md`

Author: piotmag769

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `deploy_at` cheatcode
 - printing failures summary at the end of an execution
+- filtering tests now uses an absolute module tree path — it is possible to filter tests by module names, etc.
 
 ### Fixed
 

crates/forge/src/lib.rs

@@ -156,7 +156,7 @@ fn collect_tests_from_tree(
     )?;
 
     let test_cases = if let Some(test_name_filter) = &runner_config.test_name_filter {
-        filter_tests_by_name(test_name_filter, runner_config.exact_match, tests_configs)?
+        filter_tests_by_name(test_name_filter, runner_config.exact_match, tests_configs)
     } else {
         tests_configs
     };
@@ -299,27 +299,18 @@ fn filter_tests_by_name(
     test_name_filter: &str,
     exact_match: bool,
     test_cases: Vec<TestCase>,
-) -> Result<Vec<TestCase>> {
+) -> Vec<TestCase> {
     let mut result = vec![];
     for test in test_cases {
         if exact_match {
             if test.name == test_name_filter {
                 result.push(test);
             }
-        } else if test_name_contains(test_name_filter, &test)? {
+        } else if test.name.contains(test_name_filter) {
             result.push(test);
         }
     }
-    Ok(result)
-}
-
-fn test_name_contains(test_name_filter: &str, test: &TestCase) -> Result<bool> {
-    let name = test
-        .name
-        .rsplit("::")
-        .next()
-        .context(format!("Failed to get test name from = {}", test.name))?;
-    Ok(name.contains(test_name_filter))
+    result
 }
 
 #[cfg(test)]
@@ -372,7 +363,7 @@ mod tests {
             },
         ];
 
-        let filtered = filter_tests_by_name("do", false, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("do", false, mocked_tests.clone());
         assert_eq!(
             filtered,
             vec![TestCase {
@@ -382,7 +373,7 @@ mod tests {
             },]
         );
 
-        let filtered = filter_tests_by_name("run", false, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("run", false, mocked_tests.clone());
         assert_eq!(
             filtered,
             vec![TestCase {
@@ -392,7 +383,7 @@ mod tests {
             },]
         );
 
-        let filtered = filter_tests_by_name("thing", false, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("thing", false, mocked_tests.clone());
         assert_eq!(
             filtered,
             vec![
@@ -414,10 +405,10 @@ mod tests {
             ]
         );
 
-        let filtered = filter_tests_by_name("nonexistent", false, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("nonexistent", false, mocked_tests.clone());
         assert_eq!(filtered, vec![]);
 
-        let filtered = filter_tests_by_name("", false, mocked_tests).unwrap();
+        let filtered = filter_tests_by_name("", false, mocked_tests);
         assert_eq!(
             filtered,
             vec![
@@ -441,7 +432,7 @@ mod tests {
     }
 
     #[test]
-    fn filtering_tests_only_uses_name() {
+    fn filtering_tests_uses_whole_path() {
         let mocked_tests: Vec<TestCase> = vec![
             TestCase {
                 name: "crate1::do_thing".to_string(),
@@ -460,8 +451,22 @@ mod tests {
             },
         ];
 
-        let filtered = filter_tests_by_name("crate", false, mocked_tests).unwrap();
-        assert_eq!(filtered, vec![]);
+        let filtered = filter_tests_by_name("crate2::", false, mocked_tests);
+        assert_eq!(
+            filtered,
+            vec![
+                TestCase {
+                    name: "crate2::run_other_thing".to_string(),
+                    available_gas: None,
+                    expected_result: ExpectedTestResult::Success,
+                },
+                TestCase {
+                    name: "outer::crate2::run_other_thing".to_string(),
+                    available_gas: None,
+                    expected_result: ExpectedTestResult::Success,
+                },
+            ]
+        );
     }
 
     #[test]
@@ -489,13 +494,13 @@ mod tests {
             },
         ];
 
-        let filtered = filter_tests_by_name("", true, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("", true, mocked_tests.clone());
         assert_eq!(filtered, vec![]);
 
-        let filtered = filter_tests_by_name("thing", true, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("thing", true, mocked_tests.clone());
         assert_eq!(filtered, vec![]);
 
-        let filtered = filter_tests_by_name("do_thing", true, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("do_thing", true, mocked_tests.clone());
         assert_eq!(
             filtered,
             vec![TestCase {
@@ -505,8 +510,7 @@ mod tests {
             },]
         );
 
-        let filtered =
-            filter_tests_by_name("crate1::do_thing", true, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("crate1::do_thing", true, mocked_tests.clone());
         assert_eq!(
             filtered,
             vec![TestCase {
@@ -516,12 +520,10 @@ mod tests {
             },]
         );
 
-        let filtered =
-            filter_tests_by_name("crate3::run_other_thing", true, mocked_tests.clone()).unwrap();
+        let filtered = filter_tests_by_name("crate3::run_other_thing", true, mocked_tests.clone());
         assert_eq!(filtered, vec![]);
 
-        let filtered =
-            filter_tests_by_name("outer::crate3::run_other_thing", true, mocked_tests).unwrap();
+        let filtered = filter_tests_by_name("outer::crate3::run_other_thing", true, mocked_tests);
         assert_eq!(
             filtered,
             vec![TestCase {
@@ -552,7 +554,7 @@ mod tests {
             },
         ];
 
-        let result = filter_tests_by_name("thing", false, mocked_tests).unwrap();
+        let result = filter_tests_by_name("thing", false, mocked_tests);
         assert_eq!(
             result,
             vec![

crates/forge/src/main.rs

@@ -25,15 +25,14 @@ static PREDEPLOYED_CONTRACTS: Dir = include_dir!("crates/cheatnet/predeployed-co
 #[command(version)]
 struct Args {
     /// Name used to filter tests
-    test_name: Option<String>,
+    test_filter: Option<String>,
     /// Use exact matches for `test_filter`
     #[arg(short, long)]
     exact: bool,
-    /// Create a new forge project with <name> in current directory
-    #[clap(long)]
+    /// Create a new directory and forge project named <NAME>
+    #[arg(long, value_name = "NAME")]
     init: Option<String>,
-
-    /// Stop test execution after first failed test
+    /// Stop test execution after the first failed test
     #[arg(short = 'x', long)]
     exit_first: bool,
 }
@@ -94,7 +93,7 @@ fn main_execution() -> Result<bool> {
         let target_name = target_name_for_package(&scarb_metadata, package)?;
         let corelib_path = corelib_for_package(&scarb_metadata, package)?;
         let runner_config = RunnerConfig::new(
-            args.test_name.clone(),
+            args.test_filter.clone(),
             args.exact,
             args.exit_first,
             &forge_config,

crates/forge/tests/e2e/running.rs

@@ -168,6 +168,31 @@ fn with_filter() {
         "#});
 }
 
+#[test]
+fn with_filter_matching_module() {
+    let temp = setup_package("simple_package");
+    let snapbox = runner();
+
+    snapbox
+        .current_dir(&temp)
+        .arg("ext_function_test::")
+        .assert()
+        .success()
+        .stdout_matches(indoc! {r#"
+        [..]Compiling[..]
+        [..]Finished[..]
+        Collected 2 test(s) and 5 test file(s)
+        Running 0 test(s) from simple_package package
+        Running 0 test(s) from tests/contract.cairo
+        Running 2 test(s) from tests/ext_function_test.cairo
+        [PASS] ext_function_test::test_my_test
+        [PASS] ext_function_test::test_simple
+        Running 0 test(s) from tests/test_simple.cairo
+        Running 0 test(s) from tests/without_prefix.cairo
+        Tests: 2 passed, 0 failed, 0 skipped
+        "#});
+}
+
 #[test]
 fn with_exact_filter() {
     let temp = setup_package("simple_package");

docs/src/appendix/forge.md

@@ -1,16 +1,28 @@
-# `snforge [test filter]`
+# `snforge`
 
 Run forge in the current directory
 
-## `[test filter]`
+## `[TEST_FILTER]`
 
-Passing a test filter will only run tests with a name containing this filter.
+Passing a test filter will only run tests with an [absolute module tree path](https://book.cairo-lang.org/ch06-03-paths-for-referring-to-an-item-in-the-module-tree.html?highlight=path#paths-for-referring-to-an-item-in-the-module-tree)
+containing this filter.
 
-## `--exact`
+## `-e`, `--exact`
 
 Will only run a test with a name exactly matching the test filter.
 Test filter must be a whole qualified test name e.g. `package_name::my_test` instead of just `my_test`.
 
-## `--exit-first`
+## `--init <NAME>`
+
+ Create a new directory and forge project named `<NAME>`.
+
+## `-x`, `--exit-first`
 
 Stop executing tests after the first failed test.
+
+## `-h`, `--help`
+Print help.
+
+## `-V`, `--version`
+
+Print version.

docs/src/testing/running-tests.md

@@ -15,7 +15,8 @@ Tests: 3 passed, 0 failed, 0 skipped
 ## Filtering Tests
 
 You can pass a filter string after the `snforge` command to filter tests.
-By default, any test name matching the filter will be run.
+By default, any test with an [absolute module tree path](https://book.cairo-lang.org/ch06-03-paths-for-referring-to-an-item-in-the-module-tree.html?highlight=path#paths-for-referring-to-an-item-in-the-module-tree)
+ matching the filter will be run.
 
 ```shell
 $ snforge calling