Skip to content

Commit 5991e39

Browse files
ksew1ksew1
authored
Add trace docs (#3319)
commit-id:5de40c98
1 parent acf91f5 commit 5991e39

File tree

1 file changed

+95
-10
lines changed

1 file changed

+95
-10
lines changed

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

+95-10
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,93 @@
1-
# Backtrace
1+
# Debugging
22

3-
## Prerequisites
3+
When a contract call fails, the error message alone may not always provide enough information to identify the root cause
4+
of the issue. To aid in debugging, `snforge` offers following features:
5+
6+
- [trace](debugging.md#trace)
7+
- [backtrace](debugging.md#backtrace)
8+
9+
## Trace
10+
11+
### Usage
12+
13+
> 📝 Note
14+
> Currently, the flow of execution trace is only available at the contract level. In future versions, it will also be
15+
> available at the function level.
16+
17+
You can inspect the flow of execution for your tests using the `--trace-verbosity` flag when running the `snforge test`
18+
command. This is useful for understanding how contracts are interacting with each other during your tests, especially in
19+
complex nested scenarios.
20+
21+
### Verbosity Levels
22+
23+
The `--trace-verbosity` flag accepts the following values:
24+
25+
- **minimal**: Shows test name, contract name, and selector.
26+
- **standard**: Includes test name, contract name, selector, calldata, and call result.
27+
- **detailed**: Displays the entire trace, including internal calls, caller addresses, and panic reasons.
28+
29+
Example usage:
30+
31+
<!-- { "package_name": "debugging" } -->
32+
```shell
33+
$ snforge test --trace-verbosity standard
34+
```
35+
<details>
36+
<summary>Output:</summary>
37+
38+
```shell
39+
[test name] trace_info_integrationtest::test_trace::test_debugging_trace_success
40+
├─ [selector] execute_calls
41+
│ ├─ [contract name] SimpleContract
42+
│ ├─ [calldata] array![RecursiveCall { contract_address: ContractAddress(0x10a2fac439604ce4129fe7c205b711e8141e12e2e52e08f7f898fe7ac13f0a), payload: array![RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }, RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }] }, RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }]
43+
│ ├─ [call result] success: array![RecursiveCall { contract_address: ContractAddress(0x10a2fac439604ce4129fe7c205b711e8141e12e2e52e08f7f898fe7ac13f0a), payload: array![RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }, RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }] }, RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }]
44+
│ ├─ [selector] execute_calls
45+
│ │ ├─ [contract name] SimpleContract
46+
│ │ ├─ [calldata] array![RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }, RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }]
47+
│ │ ├─ [call result] success: array![RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }, RecursiveCall { contract_address: ContractAddress(0x28f58bf524dc0adcf7468c67d7ffdac1e5d885d347c6a498978f538984dbda), payload: array![] }]
48+
│ │ ├─ [selector] execute_calls
49+
│ │ │ ├─ [contract name] SimpleContract
50+
│ │ │ ├─ [calldata] array![]
51+
│ │ │ └─ [call result] success: array![]
52+
│ │ └─ [selector] execute_calls
53+
│ │ ├─ [contract name] SimpleContract
54+
│ │ ├─ [calldata] array![]
55+
│ │ └─ [call result] success: array![]
56+
│ └─ [selector] execute_calls
57+
│ ├─ [contract name] SimpleContract
58+
│ ├─ [calldata] array![]
59+
│ └─ [call result] success: array![]
60+
└─ [selector] fail
61+
├─ [contract name] SimpleContract
62+
├─ [calldata] array![0x1, 0x2, 0x3, 0x4, 0x5]
63+
└─ [call result] panic: (0x1, 0x2, 0x3, 0x4, 0x5)
64+
```
65+
</details>
66+
<br>
67+
68+
---
69+
70+
## Trace Output Explained
71+
72+
Here's what each tag in the trace represents:
73+
74+
| Tag | Description |
75+
|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
76+
| `[test name]` | The path to the test being executed, using the Cairo module structure. Indicates which test case produced this trace. |
77+
| `[selector]` | The name of the contract function being called. The structure shows nested calls when one function triggers another. |
78+
| `[contract name]` | The name of the contract where the selector (function) was invoked. Helps trace calls across contracts. |
79+
| `[entry point type]` | (In detailed view) Type of entry point used: External, Constructor, L1Handler. Useful to differentiate the context in which the call is executed. |
80+
| `[calldata]` | (In standard view and above) The arguments passed into the function call. |
81+
| `[storage address]` | (In detailed view) The storage address of the specific contract instance called. Helps identify which deployment is used if you're testing multiple. |
82+
| `[caller address]` | (In detailed view) The address of the account or contract that made this call. Important to identify who triggered the function. |
83+
| `[call type]` | (In detailed view) Call, Delegate. Describes how the function is being invoked. |
84+
| `[call result]` | (In standard view and above) The return value of the call, success or panic. |
85+
86+
87+
88+
## Backtrace
89+
90+
### Prerequisites
491
592
Backtrace feature relies on debug information provided by Scarb. To generate the necessary debug information, you need
693
to have:
@@ -9,14 +96,15 @@ to have:
996
2. `Scarb.toml` file with the following Cairo compiler configuration:
1097
1198
> 📝 **Note**
12-
>
13-
> If you are using `scarb nightly-2025-03-27` there is a way to improve backtrace for panic in contracts if you set `panic-backtrace` to true in Scarb.toml
99+
>
100+
> If you are using `scarb nightly-2025-03-27` or later there is a way to improve backtrace for panic in contracts if
101+
> you set `panic-backtrace = true`
14102
15103
```toml
16104
[profile.dev.cairo]
17105
unstable-add-statements-code-locations-debug-info = true
18106
unstable-add-statements-functions-debug-info = true
19-
panic-backtrace = true # only for scarb nightly-2025-03-27
107+
panic-backtrace = true # only for scarb nightly-2025-03-27 or later
20108
```
21109
22110
> 📝 **Note**
@@ -26,10 +114,7 @@ panic-backtrace = true # only for scarb nightly-2025-03-27
26114
> memory. It will also make the compilation artifacts larger. So it is only recommended to add these flags when you need
27115
> their functionality.
28116
29-
## Usage
30-
31-
When a contract call fails, the error message alone may not always provide enough information to identify the root cause
32-
of the issue. To aid in debugging, `snforge` offers a feature that can generate a backtrace of the execution.
117+
### Usage
33118
34119
If your contract fails and a backtrace can be generated, `snforge` will prompt you to run the operation again with the
35120
`SNFORGE_BACKTRACE=1` environment variable (if it’s not already configured). For example, you may see failure data like
@@ -52,7 +137,7 @@ note: run with `SNFORGE_BACKTRACE=1` environment variable to display a backtrace
52137
<br>
53138
54139
55-
To enable backtraces, simply set the `SNFORGE_BACKTRACE=1` environment variable and rerun the operation.
140+
To enable backtrace, simply set the `SNFORGE_BACKTRACE=1` environment variable and rerun the operation.
56141
57142
When enabled, the backtrace will display the call tree of the execution, including the specific line numbers in the
58143
contracts where the errors occurred. Here's an example of what you might see:

0 commit comments

Comments
 (0)