foundry-rs / foundry-rs/foundry
meta(debugger): tracking issue for debugger improvements
- Dominant language
- Rust
- Stars
- 10.6k
- Forks
- 2.6k
- Avg merge
- 16h 38m
- Merged PRs (30d)
- 511
Description
# Meta
Tracks debugger improvements and what counts as done for each broad area. Checked items should correspond to merged, user-facing debugger support. Unchecked items include current partial state plus the remaining scope.
**Decoding/display**
- [x] Guidance on how to debug failed tests in the CLI output
- Merged in #15347. Failing test summaries now point users at `forge test --debug --match-test `.
- [x] Visual clues that a precompile is being called
- Merged in #15379 and #15383. The debugger annotates precompile child calls, uses chain-aware precompile labels, and surfaces the clue in debugger context.
- [ ] Showing current values of variables (https://github.com/gakonst/foundry/issues/410)
- Current state: #15141 adds a Variables pane with scoped declarations, decoded function parameters, and completed internal return values where reliable; #15200 fixes internal variable matching; #15605 adds external return-value decoding at completed external call frames.
- Remaining scope: complete current local variable values / watch-like inspection, not just known declarations and reliably decoded params/returns.
- [x] Allow toggling of individual panes for flexible layout
- Merged in #15593, #15600, and #15788. Command mode can toggle source, variables, stack, opcodes/trace, and the shared memory/calldata/returndata/storage data pane.
**Bugs**
- [x] https://github.com/foundry-rs/foundry/issues/5435
- Fixed by forked contract/source identification work, including #15048 and #15185.
- [x] Previous-call navigation preserves the current opcode at the root boundary
- Merged in #15734. `c` is now a no-op when there is no previous call instead of jumping to the root call's final opcode.
- [x] Clamp pane scroll positions after navigation
- Merged in #15750. Shorter non-empty stack and buffer views remain visible after stepping or switching calls.
**Quality of life**
- [x] If the debugger is started with no arguments, display a list of contracts/tests that the user can interactively select
- Merged in #15727. The debugger interactively selects and runs an exact matching test, including overloaded signatures, while retaining the existing non-interactive error.
**Control flow**
- [x] Continue to program counters
- Merged in #15485 and #15933. `:continue ` advances through repeated program counter hits in the current contract, while `:pc ` performs a direct jump.
- [x] Breakpoints
- `vm.breakpoint` records debugger breakpoints, the TUI supports `'` jump shortcuts, and #15478 adds success/error status feedback.
- Merged in #15830. Repeated breakpoint jumps cycle through loop iterations and split call segments in trace order.
- [x] Search opcodes
- Merged in #15211. `/` searches opcodes and `n` / `N` repeat the search forward or backward.
- Merged in #15910. Searches cross every segment of the current logical call while excluding child calls.
- [x] Jump to source lines
- Merged in #15694. `:line ` / `:ln ` jumps to a line in the source file currently shown by the debugger.
**Capabilities**
- [ ] Debugging of constructors
- Done means users can open and navigate constructor/create execution in the debugger with useful opcode/source context.
- Current state: #15678 decodes constructor arguments for creation frames so constructor parameters can be shown from decoded call data.
- [ ] Debugging calls to external contracts (i.e. no local contract is deployed, but a fake call to a live contract is debugged)
- Done means users can debug a direct/forked external call even when no local test-deployed contract owns the target source/runtime.
- [ ] Storage view
- Current state: #15218 shows current `SLOAD`/`SSTORE` slot/value context in the Variables pane; #15708 adds transient `TLOAD`/`TSTORE` context and slot navigation; #15753 adds a persistent/transient explorer for slots accessed in the current logical call, with #15771 avoiding repeated scans while rendering it. Draft #16246 adds compiler-layout labels for persistent storage slots.
- Remaining scope: querying slots absent from the recorded trace and labeling mapping-derived slots once mapping hash preimages are available.
**UI**
- [x] https://github.com/foundry-rs/foundry/issues/8256
**Big ticket items**
- [ ] Have an actual interactive debugger
- Current state: the debugger records execution and replays a trace in the TUI.
- Remaining scope: runtime-backed stepping or controlled re-execution that can avoid replay memory limits and eventually support interactive state/value changes.
Contributor guide
Research direction
This is a broad tracking issue rather than a self-contained task, and it names no source files or tests. Start with one unchecked area and its linked issue, then run the relevant `forge test --debug` flow or debugger TUI entry point described there. Done is defined separately for each area, such as current variable values, constructor execution, external calls, storage queries, or runtime-backed stepping.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100