Add docs for new flag (#3609)

commit-id:04335540

---

**Stack**:
- #3612
- #3609 ⬅


⚠️ *Part of a stack created by [spr](https://github.com/ejoffe/spr). Do
not merge manually using the UI - doing so may have unexpected results.*

Author: ksew1

CHANGELOG.md

@@ -19,6 +19,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - If using a Scarb version before `2.10.0` or not using `allow-prebuild-plugins`, the minimal required rust version to run `snforge` is now `1.87.0`
 
+#### Added
+
+- `--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)
+
 ### Cast
 
 #### Added

docs/src/appendix/snforge/test.md

@@ -8,6 +8,30 @@ Passing a test filter will only run tests with
 an [absolute module tree path](https://book.cairo-lang.org/ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html#paths-for-referring-to-an-item-in-the-module-tree)
 containing this filter.
 
+## `--trace-verbosity <TRACE_VERBOSITY>`
+
+Sets the level of detail shown in execution traces.
+
+Valid values:
+
+- `minimal`: Only test name, contract name, and selector
+- `standard`: Includes calldata and call result
+- `detailed`: Full trace, including nested calls, caller address, and panic reasons
+
+## `--trace-components <TRACE_COMPONENTS>...`
+
+Selects specific trace elements to include in the execution flow output.
+
+Available components:
+
+- `contract-name`
+- `entry-point-type`
+- `calldata`
+- `contract-address`
+- `caller-address`
+- `call-type`
+- `call-result`
+
 ## `-e`, `--exact`
 
 Will only run a test with a name exactly matching the test filter.

docs/src/snforge-advanced-features/debugging.md

@@ -14,17 +14,68 @@ of the issue. To aid in debugging, `snforge` offers following features:
 > Currently, the flow of execution trace is only available at the contract level. In future versions, it will also be
 > available at the function level.
 
-You can inspect the flow of execution for your tests using the `--trace-verbosity` flag when running the `snforge test`
-command. This is useful for understanding how contracts are interacting with each other during your tests, especially in
-complex nested scenarios.
+You can inspect the flow of execution for your tests using the `--trace-verbosity` or `--trace-components`  flags when
+running the `snforge test` command. This is useful for understanding how contracts are interacting with each other
+during your tests, especially in complex nested scenarios.
+
+### Trace Components
+
+The `--trace-components` flag allows you to specify which components of the trace you want to see. You can choose from:
+
+- `contract-name`: the name of the contract being called
+- `entry-point-type`: the type of the entry point being called (e.g., `External`, `L1Handler`, etc.)
+- `calldata`: the calldata of the call, transformed for display
+- `contract-address`: the address of the contract being called
+- `caller-address`: the address of the caller contract
+- `call-type`: the type of the call (e.g., `Call`, `Delegate`, etc.)
+- `call-result`: the result of the call, transformed for display
+
+Example usage:
+
+<!-- { "package_name": "debugging" } -->
+```shell
+$ snforge test --trace-components contract-name call-result call-type
+```
+<details>
+<summary>Output:</summary>
+
+```shell
+[test name] trace_info_integrationtest::test_trace::test_debugging_trace_success
+├─ [selector] execute_calls
+│  ├─ [contract name] SimpleContract
+│  ├─ [call type] Call
+│  ├─ [call result] success: array![RecursiveCall { contract_address: ContractAddress([..]), payload: array![RecursiveCall { contract_address: ContractAddress([..]), payload: array![] }, RecursiveCall { contract_address: ContractAddress([..]), payload: array![] }] }, RecursiveCall { contract_address: ContractAddress([..]), payload: array![] }]
+│  ├─ [selector] execute_calls
+│  │  ├─ [contract name] SimpleContract
+│  │  ├─ [call type] Call
+│  │  ├─ [call result] success: array![RecursiveCall { contract_address: ContractAddress([..]), payload: array![] }, RecursiveCall { contract_address: ContractAddress([..]), payload: array![] }]
+│  │  ├─ [selector] execute_calls
+│  │  │  ├─ [contract name] SimpleContract
+│  │  │  ├─ [call type] Call
+│  │  │  └─ [call result] success: array![]
+│  │  └─ [selector] execute_calls
+│  │     ├─ [contract name] SimpleContract
+│  │     ├─ [call type] Call
+│  │     └─ [call result] success: array![]
+│  └─ [selector] execute_calls
+│     ├─ [contract name] SimpleContract
+│     ├─ [call type] Call
+│     └─ [call result] success: array![]
+└─ [selector] fail
+   ├─ [contract name] SimpleContract
+   ├─ [call type] Call
+   └─ [call result] panic: (0x1, 0x2, 0x3, 0x4, 0x5)
+```
+</details>
+<br>
 
 ### Verbosity Levels
 
 The `--trace-verbosity` flag accepts the following values:
 
-- **minimal**: Shows test name, contract name, and selector.
-- **standard**: Includes test name, contract name, selector, calldata, and call result.
-- **detailed**: Displays the entire trace, including internal calls, caller addresses, and panic reasons.
+- `minimal`: shows test name, contract name, and selector
+- `standard`: includes test name, contract name, selector, calldata, and call result
+- `detailed`: displays the entire trace, including internal calls, caller addresses, and panic reasons
 
 Example usage: