From 79954a8356a343f191196762fe67e76a3c19e5a5 Mon Sep 17 00:00:00 2001 From: Dariusz Doktorski Date: Tue, 28 Oct 2025 20:04:25 +0100 Subject: [PATCH 1/4] Add gas report docs --- CHANGELOG.md | 4 +++ docs/src/appendix/snforge/test.md | 3 ++ .../testing/gas-and-resource-estimation.md | 32 +++++++++++++++++++ 3 files changed, 39 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a30db20a22..80119905e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Forge +#### Added + +- `--gas-report` flag to display a table of L2 gas breakdown for each contract and selector + #### Changed - Gas values in fuzzing test output are now displayed as whole numbers without fractional parts 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..4a51b5891e 100644 --- a/docs/src/testing/gas-and-resource-estimation.md +++ b/docs/src/testing/gas-and-resource-estimation.md @@ -17,6 +17,38 @@ 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 that 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: From c6161298e3abe85e5bad0ea513930b3b28a74ad9 Mon Sep 17 00:00:00 2001 From: Dariusz Doktorski Date: Wed, 29 Oct 2025 15:01:51 +0100 Subject: [PATCH 2/4] Ignore gas report snippet in docs --- docs/src/testing/gas-and-resource-estimation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/testing/gas-and-resource-estimation.md b/docs/src/testing/gas-and-resource-estimation.md index 4a51b5891e..43c1555818 100644 --- a/docs/src/testing/gas-and-resource-estimation.md +++ b/docs/src/testing/gas-and-resource-estimation.md @@ -22,6 +22,7 @@ storage updates, events and l1 <> l2 messages. 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 ``` From 3374fbb9c9f79ca10fecd1d9f23eac5be4a8b925 Mon Sep 17 00:00:00 2001 From: Dariusz Doktorski Date: Tue, 4 Nov 2025 12:43:22 +0100 Subject: [PATCH 3/4] Use standard docs note style --- docs/src/testing/gas-and-resource-estimation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/testing/gas-and-resource-estimation.md b/docs/src/testing/gas-and-resource-estimation.md index 43c1555818..38c4acaaf8 100644 --- a/docs/src/testing/gas-and-resource-estimation.md +++ b/docs/src/testing/gas-and-resource-estimation.md @@ -48,7 +48,9 @@ Running 1 test(s) from tests/
-Note that gas report data calculation ignores state changes, the cost of declared classes, Starknet OS overhead, L1 handler payload length and calldata payload length. +> 📝 **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 From 4e4d201f1b6943627e55da054c7fdccc36402211 Mon Sep 17 00:00:00 2001 From: Dariusz Doktorski Date: Thu, 6 Nov 2025 13:00:50 +0100 Subject: [PATCH 4/4] Fix changelog --- CHANGELOG.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 80119905e4..93fe4cbdd4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,14 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [0.52.0] - 2025-11-05 - ### 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 + #### Changed - Gas values in fuzzing test output are now displayed as whole numbers without fractional parts