Parametrized tests docs (#3697)

franciszekjob · web-flow · commit f754adc464b5 · 2025-09-29T15:25:52.000Z
Towards #1431 **Stack**: - #3697 ⬅ - #3669 - #3671 - #3670 ## Introduced changes Add docs ## Checklist  - [ ] Linked relevant issue - [x] Updated relevant documentation - [ ] Added relevant tests - [x] Performed self-review of the code - [x] Added changes to `CHANGELOG.md`
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Forge
 
+#### Added
+
+- `#[test_case]` attribute for parameterized testing. Read more [here](https://foundry-rs.github.io/starknet-foundry/snforge-advanced-features/parametrized-testing.html)
+
 #### Changed
 
 - Minimal supported `Scarb` version is now `2.10.0` (updated from `2.9.1`)
@@ -26,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Added
 
-`sncast declare-from` command to declare a contract by fetching it from a different Starknet instance
+- `sncast declare-from` command to declare a contract by fetching it from a different Starknet instance
 
 ## [0.49.0] - 2025-09-03
 
diff --git a/crates/forge/tests/data/test_case/tests/exit_first.cairo b/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);
diff --git a/docs/listings/parametrized_testing_advanced/Scarb.toml b/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"
diff --git a/docs/listings/parametrized_testing_advanced/src/lib.cairo b/docs/listings/parametrized_testing_advanced/src/lib.cairo
@@ -0,0 +1,5 @@
+#[starknet::contract]
+pub mod HelloStarknet {
+    #[storage]
+    struct Storage {}
+}
diff --git a/docs/listings/parametrized_testing_advanced/tests/example.cairo b/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);
+}
diff --git a/docs/listings/parametrized_testing_basic/Scarb.toml b/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"
diff --git a/docs/listings/parametrized_testing_basic/src/lib.cairo b/docs/listings/parametrized_testing_basic/src/lib.cairo
@@ -0,0 +1,5 @@
+#[starknet::contract]
+pub mod HelloStarknet {
+    #[storage]
+    struct Storage {}
+}
diff --git a/docs/listings/parametrized_testing_basic/tests/example.cairo b/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);
+}
diff --git a/docs/listings/parametrized_testing_fuzzer/Scarb.toml b/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"
diff --git a/docs/listings/parametrized_testing_fuzzer/src/lib.cairo b/docs/listings/parametrized_testing_fuzzer/src/lib.cairo
@@ -0,0 +1,5 @@
+#[starknet::contract]
+pub mod HelloStarknet {
+    #[storage]
+    struct Storage {}
+}
diff --git a/docs/listings/parametrized_testing_fuzzer/tests/example.cairo b/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);
+}
diff --git a/docs/src/SUMMARY.md b/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)
 
 ---
 
diff --git a/docs/src/snforge-advanced-features/parametrized-testing.md b/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>
diff --git a/docs/src/testing/test-attributes.md b/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);
+}
+```
