foundry-rs / foundry-rs/foundry

meta(debugger): tracking issue for debugger improvements

Open
#927 9 comments 2 reactions 0 assignees View on GitHub
A-debugger C-forge Cmd-forge-debug T-meta
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.