A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
fix(debugger): classify SetBreakpointsCommand and resync breakpoints on restart (#10120)
Myles Scolnickf0a0a4bac104
diff --git a/docs/guides/debugging.md b/docs/guides/debugging.mdindex 7baed9a37d..c14a615760 100644--- a/docs/guides/debugging.md+++ b/docs/guides/debugging.md@@ -44,6 +44,23 @@ def _():</video>Clicking on the cell link will also take you to the cell where the error occurred.+### Live debugger++!!! warning "Experimental Feature"+ The live debugger is currently experimental and under active development. Features and APIs may change.++Enable **Debugger** under experimental settings to turn on a live debugger for+the notebook editor:++- Click a line in the gutter to set a breakpoint on it. Click it again to+ remove it. Breakpoints are session-only; they're not saved to the notebook+ file.+- While a cell is running, the line it's currently executing is highlighted.+- When execution reaches a breakpoint, the cell drops into `pdb` just like+ `breakpoint()` does.++This setting requires a page refresh to take effect.+### Postmortem debuggingIf your code raises an exception, you can use postmortem debugging to inspectdiff --git a/frontend/src/core/codemirror/cells/__tests__/debugger-decorations.test.ts b/frontend/src/core/codemirror/cells/__tests__/debugger-decorations.test.tsnew file mode 100644index 0000000000..fb6646adbe--- /dev/null+++ b/frontend/src/core/codemirror/cells/__tests__/debugger-decorations.test.ts@@ -0,0 +1,185 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { python } from "@codemirror/lang-python";+import { EditorState } from "@codemirror/state";+import { EditorView } from "@codemirror/view";+import { afterEach, describe, expect, it, vi } from "vitest";+import { cellId } from "@/__tests__/branded";+import type { CellId } from "@/core/cells/ids";+import { createMockObservable } from "@/core/state/__mocks__/mocks";+import type { Observable } from "@/core/state/observable";+import {+ breakpointGutter,+ debuggerLineHighlighter,+} from "../debugger-decorations";++vi.mock("../debugger-state", () => ({+ toggleBreakpoint: vi.fn(),+}));++import { toggleBreakpoint } from "../debugger-state";++const CODE = `def my_function():+ x = 1+ y = 2+ return x + y++result = my_function()`;++function createLineHighlighterEditor(+ lineObservable: Observable<number | null>,+) {+ const state = EditorState.create({+ doc: CODE,+ extensions: [python(), debuggerLineHighlighter(lineObservable)],+ });+ return new EditorView({ state, parent: document.body });+}++function createBreakpointGutterEditor(+ cid: CellId,+ breakpointsObservable: Observable<ReadonlySet<number>>,+) {+ const state = EditorState.create({+ doc: CODE,+ extensions: [python(), breakpointGutter(cid, breakpointsObservable)],+ });+ return new EditorView({ state, parent: document.body });+}++/** Flush the microtask queue and apply the resulting state changes to `view`. */+async function flush(view: EditorView): Promise<void> {+ await Promise.resolve();+ view.dispatch({});+}++/**+ * Count rendered breakpoint markers, excluding the always-present hidden+ * spacer element (`initialSpacer`) that isn't an actual breakpoint.+ */+function visibleMarkerCount(view: EditorView): number {+ const gutterElement = view.dom.querySelector(".cm-breakpoint-gutter");+ if (!gutterElement) {+ return 0;+ }+ return gutterElement.querySelectorAll(+ '.cm-gutterElement:not([style*="visibility: hidden"]) .cm-breakpoint-marker',+ ).length;+}++describe("debugger-decorations", () => {+ let view: EditorView | null = null;++ afterEach(() => {+ if (view) {+ view.destroy();+ view = null;+ }+ document.body.innerHTML = "";+ vi.clearAllMocks();+ });++ describe("debuggerLineHighlighter", () => {+ it("renders no highlight when the observable starts null", () => {+ const lineObservable = createMockObservable<number | null>(null);+ view = createLineHighlighterEditor(lineObservable);++ expect(view.dom.querySelector(".cm-debugger-current-line")).toBeNull();+ });++ it("highlights the line reported by the observable", () => {+ const lineObservable = createMockObservable<number | null>(null);+ view = createLineHighlighterEditor(lineObservable);++ lineObservable.set(2);+ view.dispatch({});++ expect(+ view.dom.querySelector(".cm-debugger-current-line"),+ ).not.toBeNull();+ });++ it("clears the highlight when the line is set back to null", () => {+ const lineObservable = createMockObservable<number | null>(2);+ view = createLineHighlighterEditor(lineObservable);+ view.dispatch({});+ expect(+ view.dom.querySelector(".cm-debugger-current-line"),+ ).not.toBeNull();++ lineObservable.set(null);+ view.dispatch({});++ expect(view.dom.querySelector(".cm-debugger-current-line")).toBeNull();+ });++ it("does not throw for an out-of-range line", () => {+ const lineObservable = createMockObservable<number | null>(null);+ view = createLineHighlighterEditor(lineObservable);++ expect(() => {+ lineObservable.set(9999);+ view?.dispatch({});+ }).not.toThrow();+ expect(view.dom.querySelector(".cm-debugger-current-line")).toBeNull();+ });+ });++ describe("breakpointGutter", () => {+ it("renders no markers when there are no breakpoints", () => {+ const cid = cellId("cell1");+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(+ new Set(),+ );+ view = createBreakpointGutterEditor(cid, breakpointsObservable);++ expect(visibleMarkerCount(view)).toBe(0);+ });++ it("syncs pre-existing breakpoints on mount", async () => {+ const cid = cellId("cell1");+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(+ new Set([2]),+ );+ view = createBreakpointGutterEditor(cid, breakpointsObservable);+ await flush(view); // initial sync is deferred to a microtask++ expect(visibleMarkerCount(view)).toBe(1);+ });++ it("adds a marker when the observable reports a new breakpoint", () => {+ const cid = cellId("cell1");+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(+ new Set(),+ );+ view = createBreakpointGutterEditor(cid, breakpointsObservable);++ breakpointsObservable.set(new Set([1, 3]));+ view.dispatch({});++ expect(visibleMarkerCount(view)).toBe(2);+ });++ it("toggles a breakpoint when an existing marker is clicked", async () => {+ const cid = cellId("cell1");+ // A single breakpoint on line 1 renders exactly one non-spacer+ // gutter element, so the click lands unambiguously on that line.+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(+ new Set([1]),+ );+ view = createBreakpointGutterEditor(cid, breakpointsObservable);+ await flush(view);++ const gutterElement = view.dom.querySelector(".cm-breakpoint-gutter");+ const lineElement = gutterElement?.querySelector(+ '.cm-gutterElement:not([style*="visibility: hidden"])',+ );+ expect(lineElement).not.toBeNull();+ lineElement?.dispatchEvent(+ new MouseEvent("mousedown", { bubbles: true }),+ );++ expect(toggleBreakpoint).toHaveBeenCalledWith(cid, 1);+ });+ });+});diff --git a/frontend/src/core/codemirror/cells/__tests__/debugger-state.test.ts b/frontend/src/core/codemirror/cells/__tests__/debugger-state.test.tsnew file mode 100644index 0000000000..415a0c62cd--- /dev/null+++ b/frontend/src/core/codemirror/cells/__tests__/debugger-state.test.ts@@ -0,0 +1,139 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { beforeEach, describe, expect, it, vi } from "vitest";+import { MockRequestClient } from "@/__mocks__/requests";+import { cellId } from "@/__tests__/branded";+import { store } from "@/core/state/jotai";+import {+ breakpointsAtom,+ clearCellBreakpoints,+ createCellBreakpointsAtom,+ createDebuggerLineAtom,+ debuggerCurrentLineAtom,+ resyncBreakpoints,+ toggleBreakpoint,+} from "../debugger-state";++const mockRequestClient = MockRequestClient.create();+vi.mock("@/core/network/requests", () => ({+ getRequestClient: () => mockRequestClient,+}));++const cell1 = cellId("cell1");+const cell2 = cellId("cell2");++describe("debugger-state", () => {+ beforeEach(() => {+ store.set(breakpointsAtom, new Map());+ store.set(debuggerCurrentLineAtom, null);+ vi.clearAllMocks();+ });++ describe("toggleBreakpoint", () => {+ it("adds a breakpoint and syncs the full set to the kernel", () => {+ toggleBreakpoint(cell1, 3);++ expect(store.get(breakpointsAtom).get(cell1)).toEqual(new Set([3]));+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenCalledWith({+ breakpoints: { [cell1]: [3] },+ });+ });++ it("removes a breakpoint on second toggle and drops the cell once empty", () => {+ toggleBreakpoint(cell1, 3);+ toggleBreakpoint(cell1, 3);++ expect(store.get(breakpointsAtom).has(cell1)).toBe(false);+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenLastCalledWith({+ breakpoints: {},+ });+ });++ it("sends lines sorted ascending for a cell with multiple breakpoints", () => {+ toggleBreakpoint(cell1, 5);+ toggleBreakpoint(cell1, 2);++ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenLastCalledWith({+ breakpoints: { [cell1]: [2, 5] },+ });+ });++ it("keeps breakpoints for other cells independent", () => {+ toggleBreakpoint(cell1, 1);+ toggleBreakpoint(cell2, 2);++ expect(store.get(breakpointsAtom).get(cell1)).toEqual(new Set([1]));+ expect(store.get(breakpointsAtom).get(cell2)).toEqual(new Set([2]));+ });+ });++ describe("clearCellBreakpoints", () => {+ it("removes all breakpoints for a cell and syncs", () => {+ toggleBreakpoint(cell1, 1);+ toggleBreakpoint(cell1, 2);+ vi.clearAllMocks();++ clearCellBreakpoints(cell1);++ expect(store.get(breakpointsAtom).has(cell1)).toBe(false);+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenCalledWith({+ breakpoints: {},+ });+ });++ it("is a no-op when the cell has no breakpoints", () => {+ clearCellBreakpoints(cell1);++ expect(mockRequestClient.sendSetBreakpoints).not.toHaveBeenCalled();+ });+ });++ describe("resyncBreakpoints", () => {+ it("re-sends the current breakpoint set", () => {+ toggleBreakpoint(cell1, 4);+ vi.clearAllMocks();++ resyncBreakpoints();++ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenCalledWith({+ breakpoints: { [cell1]: [4] },+ });+ });++ it("does not send when there are no breakpoints", () => {+ resyncBreakpoints();++ expect(mockRequestClient.sendSetBreakpoints).not.toHaveBeenCalled();+ });+ });++ describe("createCellBreakpointsAtom", () => {+ it("returns the empty set for a cell with no breakpoints", () => {+ const atom = createCellBreakpointsAtom(cell1);+ expect(store.get(atom)).toEqual(new Set());+ });++ it("reflects breakpoints for its own cell only", () => {+ toggleBreakpoint(cell1, 7);+ const cell1Atom = createCellBreakpointsAtom(cell1);+ const cell2Atom = createCellBreakpointsAtom(cell2);++ expect(store.get(cell1Atom)).toEqual(new Set([7]));+ expect(store.get(cell2Atom)).toEqual(new Set());+ });+ });++ describe("createDebuggerLineAtom", () => {+ it("returns null when no line is set", () => {+ const atom = createDebuggerLineAtom(cell1);+ expect(store.get(atom)).toBeNull();+ });++ it("returns the line only for the matching cell", () => {+ store.set(debuggerCurrentLineAtom, { cellId: cell1, line: 10 });++ expect(store.get(createDebuggerLineAtom(cell1))).toBe(10);+ expect(store.get(createDebuggerLineAtom(cell2))).toBeNull();+ });+ });+});diff --git a/frontend/src/core/codemirror/cells/debugger-state.ts b/frontend/src/core/codemirror/cells/debugger-state.tsindex 9609c3b989..af18890ccd 100644--- a/frontend/src/core/codemirror/cells/debugger-state.ts+++ b/frontend/src/core/codemirror/cells/debugger-state.ts@@ -72,6 +72,14 @@ export function clearCellBreakpoints(cellId: CellId): void {sendBreakpoints(next);}+/** Re-push the current breakpoints to a freshly started kernel, whose `MarimoPdb` starts empty. */+export function resyncBreakpoints(): void {+ const current = store.get(breakpointsAtom);+ if (current.size > 0) {+ sendBreakpoints(current);+ }+}+/** Toggle a breakpoint at `(cellId, line)` and sync the full set to the kernel. */export function toggleBreakpoint(cellId: CellId, line: number): void {const prev = store.get(breakpointsAtom);diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsxindex ab62272406..f023013ee1 100644--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx@@ -32,7 +32,10 @@ import { cacheInfoAtom } from "../cache/requests";import { SCRATCH_CELL_ID } from "../cells/ids";import { useRunsActions } from "../cells/runs";import { focusAndScrollCellOutputIntoView } from "../cells/scrollCellIntoView";-import { debuggerCurrentLineAtom } from "../codemirror/cells/debugger-state";+import {+ debuggerCurrentLineAtom,+ resyncBreakpoints,+} from "../codemirror/cells/debugger-state";import type { CellData } from "../cells/types";import { capabilitiesAtom } from "../config/capabilities";import { useSetAppConfig } from "../config/config";@@ -223,6 +226,11 @@ export function useMarimoKernelConnection(opts: {existingCells,});setKioskMode(msg.data.kiosk);+ // A freshly started kernel has no breakpoints of its own; re-push+ // the client's set so they still apply, and clear the stale+ // highlighted line from the previous kernel instance.+ setDebuggerCurrentLine(null);+ resyncBreakpoints();return;}diff --git a/marimo/_session/capabilities.py b/marimo/_session/capabilities.pyindex 9d77f9c574..f9e08f2398 100644--- a/marimo/_session/capabilities.py+++ b/marimo/_session/capabilities.py@@ -67,6 +67,7 @@ _EDIT_COMMANDS: frozenset[type] = frozenset(commands.ExecuteScratchpadCommand,commands.ExecuteStaleCellsCommand,commands.DebugCellCommand,+ commands.SetBreakpointsCommand,commands.DeleteCellCommand,commands.SyncGraphCommand,commands.UpdateCellConfigCommand,diff --git a/tests/_runtime/test_request_router.py b/tests/_runtime/test_request_router.pyindex 359e2f7f26..c77c896194 100644--- a/tests/_runtime/test_request_router.py+++ b/tests/_runtime/test_request_router.py@@ -43,7 +43,7 @@ ALL_CALLBACKS: list[type] = [# Commands that are part of the CommandMessage dispatch surface but are# intentionally not handled by the kernel's RequestRouter. These are delivered# on the off-main-loop completion queue and processed by-# start_completion_worker: CodeCompletionCommand (autocomplete) and+# start_out_of_band_worker: CodeCompletionCommand (autocomplete) and# SetBreakpointsCommand (live-debugger breakpoints, so they apply mid-run).NOT_ROUTED: set[type] = {CodeCompletionCommand, SetBreakpointsCommand}