Debugging
The IDE can run your Python under a debugger so you can pause on a line and inspect the call stack and variables. There are two debug modes, both launched from the debug toolbar.
| Mode | What it runs |
|---|---|
| Debug Run | Runs the current Python file directly under the debugger. Always available when a file is open. |
| Debug Test | Runs your strategy over historical bars (a backtest) under the debugger. Appears only when the active file is a strategy that implements the backtest callbacks. |
Debug Test opens the backtest configuration modal first, then runs. It supports a single backtest only — not optimization sweeps. For how the modes relate to normal execution, see Running code and Backtests.
Setting breakpoints
- Click the gutter to the left of the line numbers to toggle a breakpoint on that line; click it again to remove it.
- Breakpoints are per file and are collected from all your open tabs when a session starts.
- The gutter is only clickable when nothing is running — set your breakpoints before you start a run.
Starting a session
- The first time you start a debug session you'll see a one-time run disclaimer (you can skip it next time).
- Debug Run needs a file open. Debug Test appears when the file defines strategy callbacks the IDE recognizes (
on_init/on_bar/on_finish); it does not require an active broker trading account. B2 / QuantCraft data uses your QC sign-in where needed. - The backtest engine still requires a callable
on_tick(and the other required callbacks). Ifon_tickis missing, Debug Test can show in the toolbar but the run fails when the backtest starts. - Only one debug session runs at a time, and debugging is blocked while a normal Run or Backtest is in progress.
Controls
The toolbar shows controls based on the session state.
| Control | When | What it does |
|---|---|---|
| Stop | While running | Ends the debug session. |
| Continue | While paused | Resumes to the next breakpoint. |
| Step Over | While paused | Runs the current line, staying in the same function. |
| Step Into | While paused | Steps into the function call on the current line. |
| Step Out | While paused | Runs until the current function returns. |
| Step Bar | While paused (Debug Test only) | Advances the backtest by one candle. |
There is no Restart — to restart, stop and click Debug Run / Debug Test again.
What you see when paused
- The editor jumps to the paused file and highlights the paused line.
- A Debug sub-tab opens in the Output panel with two panes:
- Call Stack — the chain of frames, each showing a function name and
file:line. Click a frame to inspect its variables. - Variables — grouped by scope (Locals, Globals, Closure, and so on). Each variable shows its name, type, and value; objects and lists expand to reveal their contents.
- Call Stack — the chain of frames, each showing a function name and
- In Debug Test, a step-context banner shows your position in the backtest, e.g.
Bar 12 / 240 · AAPL · <time> · O … H … L … C …. - Program output streams into the Output panel as usual.
Limitations
- No watch panel or expression evaluator — only Call Stack and Variables.
- No Restart control (stop and relaunch).
- Debug Test is single-backtest only — it cannot debug an optimization run.
- Debug Test requires a strategy file with the backtest callbacks; a plain script gets Debug Run only.
- Toolbar visibility for Debug Test does not check for
on_tick; the engine does.
See also
- Backtests — running a backtest and the Run modal
- Strategy lifecycle — strategy callbacks and simulation order