Add gas report docs (#3879)

Closes #3660

Author: ddoktorski

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

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` `<PROFILE>`
 Specify the profile to use by name.
 

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.
+
+<!-- { "ignored": true } -->
+```shell
+$ snforge test --gas-report
+```
+
+<details>
+<summary>Output:</summary>
+
+```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       |
+╰------------------------+-------+-------+-------+---------+---------╯
+```
+
+</details>
+<br>
+
+> 📝 **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: