diff --git a/CHANGELOG.md b/CHANGELOG.md index a30db20a22..93fe4cbdd4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Forge + +#### Added + +- `--gas-report` flag to display a table of L2 gas breakdown for each contract and selector + ## [0.52.0] - 2025-11-05 ### Forge diff --git a/docs/src/appendix/snforge/test.md b/docs/src/appendix/snforge/test.md index eb97bcc2ef..f490f25c41 100644 --- a/docs/src/appendix/snforge/test.md +++ b/docs/src/appendix/snforge/test.md @@ -130,6 +130,9 @@ Set tracked resource for test execution. Impacts overall test gas cost. Valid va - `cairo-steps`: track cairo steps, uses vm `ExecutionResources` (steps, builtins, memory holes) to describe resources consumed by the test. To learn more about fee calculation formula (and the impact of tracking sierra gas on it) please consult [starknet docs](https://docs.starknet.io/learn/protocol/fees#overall-fee) +## `--gas-report` +Display a table of L2 gas breakdown for each contract and selector. + ## `-P`, `--profile` `` Specify the profile to use by name. diff --git a/docs/src/testing/gas-and-resource-estimation.md b/docs/src/testing/gas-and-resource-estimation.md index 780f7d1fc1..38c4acaaf8 100644 --- a/docs/src/testing/gas-and-resource-estimation.md +++ b/docs/src/testing/gas-and-resource-estimation.md @@ -17,6 +17,41 @@ When the test passes with no errors, estimated gas is displayed this way: This gas calculation is based on the collected Sierra gas or VM resources (that you can [display additionally on demand](#usage)), storage updates, events and l1 <> l2 messages. +#### Gas Report + +For individual tests, more detailed L2 gas usage can be displayed by passing the [`--gas-report`](../appendix/snforge/test.md#--gas-report) flag. +This will generate a table that shows gas statistics for each contract and function. + + +```shell +$ snforge test --gas-report +``` + +
+Output: + +```shell +Collected 1 test(s) from hello_starknet package +Running 1 test(s) from tests/ +[PASS] hello_starknet_integrationtest::test_contract::test_increase_balance (l1_gas: ~0, l1_data_gas: ~192, l2_gas: ~998280) +╭------------------------+-------+-------+-------+---------+---------╮ +| HelloStarknet Contract | | | | | | ++====================================================================+ +| Function Name | Min | Max | Avg | Std Dev | # Calls | +|------------------------+-------+-------+-------+---------+---------| +| get_balance | 13340 | 13340 | 13340 | 0 | 4 | +|------------------------+-------+-------+-------+---------+---------| +| increase_balance | 25540 | 61240 | 37440 | 16829 | 3 | +╰------------------------+-------+-------+-------+---------+---------╯ +``` + +
+
+ +> 📝 **Note** +> +> Gas report data calculation ignores state changes, the cost of declared classes, Starknet OS overhead, L1 handler payload length and calldata payload length. + ### Fuzzed Tests While using the fuzzing feature additional gas statistics will be displayed: