Parametrized tests docs

CHANGELOG.md

@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for `meta_tx_v0` syscall with cheatcode compatibility
 - `snforge` now supports [oracles](https://docs.swmansion.com/cairo-oracle/) with `--experimental-oracles` flag.
 - `--trace-components` flag to allow selecting which components of the trace to do display. Read more [here](https://foundry-rs.github.io/starknet-foundry/snforge-advanced-features/debugging.html#trace-components)
+- `#[test_case]` attribute for parameterized testing. Read more [here](https://foundry-rs.github.io/starknet-foundry/snforge-advanced-features/parametrized-testing.html)
 
 ### Changed
 

crates/forge/tests/data/test_case/tests/exit_first.cairo

@@ -2,7 +2,7 @@ use test_case::fib;
 
 #[test]
 #[test_case(0, 1, 3)]
-#[test_case(0, 1, 100000)]
+#[test_case(0, 1, 500000)]
 fn test_fib_with_threshold(a: felt252, b: felt252, n: felt252) {
     let threshold: u256 = 10;
     let res = fib(a, b, n);

docs/listings/parametrized_testing_advanced/Scarb.toml

@@ -0,0 +1,14 @@
+[package]
+name = "parametrized_testing_advanced"
+version = "0.1.0"
+edition = "2024_07"
+
+[dependencies]
+starknet = "2.12.0"
+assert_macros = "2.12.0"
+
+[dev-dependencies]
+snforge_std = { path = "../../../snforge_std" }
+
+[scripts]
+test = "snforge test"

docs/listings/parametrized_testing_advanced/src/lib.cairo

@@ -0,0 +1,5 @@
+#[starknet::contract]
+pub mod HelloStarknet {
+    #[storage]
+    struct Storage {}
+}

docs/listings/parametrized_testing_advanced/tests/example.cairo

@@ -0,0 +1,20 @@
+#[derive(Copy, Drop)]
+struct User {
+    pub name: felt252,
+    pub age: u8,
+}
+
+#[generate_trait]
+impl UserImpl of UserTrait {
+    fn is_adult(self: @User) -> bool {
+        return *self.age >= 18_u8;
+    }
+}
+
+#[test]
+#[test_case(User { name: 'Alice', age: 20 }, true)]
+#[test_case(User { name: 'Bob', age: 14 }, false)]
+#[test_case(User { name: 'Josh', age: 18 }, true)]
+fn test_is_adult(user: User, expected: bool) {
+    assert_eq!(user.is_adult(), expected);
+}

docs/listings/parametrized_testing_basic/Scarb.toml

@@ -0,0 +1,14 @@
+[package]
+name = "parametrized_testing_basic"
+version = "0.1.0"
+edition = "2024_07"
+
+[dependencies]
+starknet = "2.12.0"
+assert_macros = "2.12.0"
+
+[dev-dependencies]
+snforge_std = { path = "../../../snforge_std" }
+
+[scripts]
+test = "snforge test"

docs/listings/parametrized_testing_basic/src/lib.cairo

@@ -0,0 +1,5 @@
+#[starknet::contract]
+pub mod HelloStarknet {
+    #[storage]
+    struct Storage {}
+}

docs/listings/parametrized_testing_basic/tests/example.cairo

@@ -0,0 +1,10 @@
+fn sum(x: felt252, y: felt252) -> felt252 {
+    return x + y;
+}
+
+#[test]
+#[test_case(1, 2, 3)]
+#[test_case(3, 4, 7)]
+fn test_sum(x: felt252, y: felt252, expected: felt252) {
+    assert_eq!(sum(x, y), expected);
+}

docs/listings/parametrized_testing_fuzzer/Scarb.toml

@@ -0,0 +1,14 @@
+[package]
+name = "parametrized_testing_fuzzer"
+version = "0.1.0"
+edition = "2024_07"
+
+[dependencies]
+starknet = "2.12.0"
+assert_macros = "2.12.0"
+
+[dev-dependencies]
+snforge_std = { path = "../../../snforge_std" }
+
+[scripts]
+test = "snforge test"

docs/listings/parametrized_testing_fuzzer/src/lib.cairo

@@ -0,0 +1,5 @@
+#[starknet::contract]
+pub mod HelloStarknet {
+    #[storage]
+    struct Storage {}
+}

docs/listings/parametrized_testing_fuzzer/tests/example.cairo

@@ -0,0 +1,11 @@
+fn sum(x: felt252, y: felt252) -> felt252 {
+    return x + y;
+}
+
+#[test]
+#[test_case(1, 2)]
+#[test_case(3, 4)]
+#[fuzzer(runs: 10)]
+fn test_sum(x: felt252, y: felt252) {
+    assert_eq!(sum(x, y), x + y);
+}

docs/src/SUMMARY.md

@@ -39,6 +39,7 @@
 * [Profiling](snforge-advanced-features/profiling.md)
 * [Debugging](snforge-advanced-features/debugging.md)
 * [Oracles](snforge-advanced-features/oracles.md)
+* [Parametrized Tests](snforge-advanced-features/parametrized-testing.md)
 
 ---
 

docs/src/snforge-advanced-features/parametrized-testing.md

@@ -0,0 +1,133 @@
+# Parametrized Testing
+
+Sometimes, you want to run the same test logic with different inputs.
+Instead of duplicating code into separate test functions, you can use parameterized tests.
+
+Parameterized tests allow you to define multiple test cases for a single function by attaching the
+`#[test_case]` attribute.
+
+Each test case provides its own set of arguments, and `snforge` will automatically generate separate test instances for them.
+
+## Basic Example
+
+To turn a regular test into a parameterized one, add the `#[test_case(...)]` attribute above it.
+You can provide any valid Cairo expressions as arguments.
+
+Below is a simple example which checks addition of two numbers.
+
+```rust
+{{#include ../../listings/parametrized_testing_basic/tests/example.cairo}}
+```
+
+Now run:
+
+<!-- { "package_name": "parametrized_testing_basic" } -->
+```shell
+$ snforge test
+```
+
+<details>
+<summary>Output:</summary>
+
+```shell
+Collected 2 test(s) from parametrized_testing_basic package
+Running 0 test(s) from src/
+Running 2 test(s) from tests/
+[PASS] parametrized_testing_basic_integrationtest::example::test_sum_1_2_3 ([..])
+[PASS] parametrized_testing_basic_integrationtest::example::test_sum_3_4_7 ([..])
+Tests: 2 passed, 0 failed, 0 ignored, [..] filtered out
+```
+</details>
+<br>
+
+## Naming Test Cases
+
+Each parameterized test gets its own generated name. There are two ways to control it:
+
+ - **Unnamed test case** - the name is generated based on the function name and the arguments provided.
+
+    ```rust
+    #[test_case(1, 2, 3)]
+    fn test_sum(x: felt252, y: felt252, expected: felt252) {
+        assert_eq!(sum(x, y), expected);
+    }
+    ``` 
+    This will generate a test named `test_sum_1_2_3`.
+
+ - **Named test case** - you can provide a custom name for the test case using the `name` parameter.
+
+    ```rust
+    #[test_case(name: "one_plus_two", 1, 2, 3)]
+    fn test_sum(x: felt252, y: felt252, expected: felt252) {
+        assert_eq!(sum(x, y), expected);
+    }
+    ```
+    This will generate a test named `test_sum_one_plus_two`.
+
+> 📝 **Note**
+> For unnamed test cases, it's possible that two different input values of the same type can generate the same test case name.
+> In such cases we emit a diagnostic error.
+> To resolve it, simply provide an explicit `name` for the case.
+
+## Advanced Example
+
+Now let's look at an addvanced example which uses structs as parameters.
+
+```rust
+{{#include ../../listings/parametrized_testing_advanced/tests/example.cairo}}
+```
+
+Now run:
+
+<!-- { "package_name": "parametrized_testing_advanced" } -->
+```shell
+$ snforge test
+```
+
+<details>
+<summary>Output:</summary>
+
+```shell
+Collected 3 test(s) from parametrized_testing_advanced package
+Running 3 test(s) from tests/
+[PASS] parametrized_testing_advanced_integrationtest::example::test_is_adult_user_name_alice_age_20_true ([..])
+[PASS] parametrized_testing_advanced_integrationtest::example::test_is_adult_user_name_josh_age_18_true ([..])
+[PASS] parametrized_testing_advanced_integrationtest::example::test_is_adult_user_name_bob_age_14_false ([..])
+Running 0 test(s) from src/
+Tests: 3 passed, 0 failed, 0 ignored, [..] filtered out
+```
+</details>
+<br>
+
+## Combining With Fuzzer Attribute
+
+`#[test_case]` can be freely combined with the `#[fuzzer]` attribute.
+
+Below is an example in which we will fuzz the test but also run the specific defined cases.
+
+```rust
+{{#include ../../listings/parametrized_testing_fuzzer/tests/example.cairo}}
+```
+
+Now run:
+
+<!-- { "package_name": "parametrized_testing_fuzzer" } -->
+```shell
+$ snforge test
+```
+
+<details>
+<summary>Output:</summary>
+
+```shell
+Collected 3 test(s) from parametrized_testing_fuzzer package
+Running 3 test(s) from tests/
+[PASS] parametrized_testing_fuzzer_integrationtest::example::test_sum_1_2 ([..])
+[PASS] parametrized_testing_fuzzer_integrationtest::example::test_sum_3_4 ([..])
+[PASS] parametrized_testing_fuzzer_integrationtest::example::test_sum ([..])
+Running 0 test(s) from src/
+Tests: 3 passed, 0 failed, 0 ignored, 0 filtered out
+Fuzzer seed: [..]
+```
+</details>
+<br>

docs/src/testing/test-attributes.md

@@ -11,6 +11,7 @@ Currently, those attributes are supported:
 - `#[fork]`
 - `#[fuzzer]`
 - `#[disable_predeployed_contracts]`
+- `#[test_case]`
 
 > 📝 **Note**
 >
@@ -154,3 +155,33 @@ Disables predeployment of default contracts in the test case.
 Currently predeployed contracts are:
 - `STRK`
 - `ETH`
+
+### `#[test_case]`
+
+Generates multiple test cases from a single function by providing different sets of arguments.
+
+Read more about parametrized tests [here](../snforge-advanced-features/parametrized-testing.md).
+
+#### Usage
+
+You can define multiple test cases by specifying different sets of arguments using the `#[test_case]` attribute.
+
+```rust
+#[test]
+#[test_case(1, 2, 3)]
+#[test_case(3, 4, 7)]
+fn test_small_sum(a: felt252, b: felt252, expected: felt252) {
+    assert_eq!(a + b, expected);
+}
+```
+
+Test cases can also be named for better identification in the test reports.
+
+```rust
+#[test]
+#[test_case(name: "one_plus_two", 1, 2, 3)]
+#[test_case(name: "three_plus_four", 3, 4, 7)]
+fn test_small_sum(a: u32, b: u32, expected: u32) {
+    assert_eq!(a + b, expected);
+}
+```