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
# Copyright 2026 Marimo. All rights reserved.
import traceback
from typing import Any
import pytest
from marimo._ast.cell import CellImpl
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.errors import MarimoSQLError
from marimo._messaging.notification import (
CellNotification,
InterruptedNotification,
)
from marimo._messaging.notification_utils import CellNotificationUtils
from marimo._runtime.capture import capture_stderr
from marimo._runtime.runner.cell_runner import Runner
from marimo._runtime.runner.hook_context import PostExecutionHookContext
from marimo._runtime.runner.hooks import (
NotebookCellHooks,
Priority,
create_default_hooks,
)
from marimo._runtime.runner.result import RunResult
from marimo._runtime.runtime import Kernel
from tests.conftest import ExecReqProvider, MockedKernel
async def test_cell_output(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
k = execution_kernel
# run the cell to populate the graph, globals
await k.run([er := exec_req.get("'hello'; 123")])
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
run_result = await runner.run(er.cell_id)
# last expression of cell is output
assert run_result.output == 123
assert k.debugger._last_traceback is None
async def test_debugger_lifecycle_gated_by_flag(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
from marimo._runtime.executor import DebuggerLifecycle
k = execution_kernel
await k.run([exec_req.get("1")])
def lifecycles(user_config: Any, debugger: Any) -> list[Any]:
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=debugger,
hooks=NotebookCellHooks(),
user_config=user_config,
)
return runner._evaluator.lifecycles
def with_flag(value: bool) -> Any:
experimental = {**k.user_config.get("experimental", {})}
experimental["debugger"] = value
return {**k.user_config, "experimental": experimental}
def has_debugger(items: list[Any]) -> bool:
return any(isinstance(item, DebuggerLifecycle) for item in items)
# On when the flag is set and a debugger is present.
assert has_debugger(lifecycles(with_flag(True), k.debugger))
# Off when the flag is unset.
assert not has_debugger(lifecycles(with_flag(False), k.debugger))
# Off when there is no debugger, even with the flag on.
assert not has_debugger(lifecycles(with_flag(True), None))
async def test_line_timing_lifecycle_gated_by_flag(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
from marimo._runtime.executor import DebuggerLifecycle
k = execution_kernel
await k.run([exec_req.get("1")])
def lifecycles(user_config: Any, debugger: Any) -> list[Any]:
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=debugger,
hooks=NotebookCellHooks(),
user_config=user_config,
)
return [
item
for item in runner._evaluator.lifecycles
if isinstance(item, DebuggerLifecycle)
]
def with_flags(**flags: bool) -> Any:
experimental = {**k.user_config.get("experimental", {}), **flags}
return {**k.user_config, "experimental": experimental}
# line_timing alone: one lifecycle, watching without a debugger — even
# when a debugger instance is available.
for debugger in (None, k.debugger):
items = lifecycles(
with_flags(debugger=False, line_timing=True), debugger
)
assert len(items) == 1
assert items[0]._watcher._debugger is None
# Both flags: exactly one lifecycle (a single settrace hook), holding the
# debugger.
items = lifecycles(with_flags(debugger=True, line_timing=True), k.debugger)
assert len(items) == 1
assert items[0]._watcher._debugger is k.debugger
# Both off: absent.
assert not lifecycles(
with_flags(debugger=False, line_timing=False), k.debugger
)
async def test_traceback_includes_lineno(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
k = execution_kernel
# Raise an exception and test that the runner generates a traceback that
# includes the line number where the exception was raised
#
# first run the cell to populate the graph
await k.run(
[
er := exec_req.get_with_id(
"1",
"""
x = 0
raise ValueError
""",
)
]
)
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
with capture_stderr() as buffer:
await runner.run(er.cell_id)
assert "line 3" in buffer.getvalue()
assert k.debugger._last_traceback == k.debugger._last_tracebacks["1"]
assert k.debugger._last_traceback is not None
assert "line 3" in "\n".join(
traceback.format_tb(k.debugger._last_traceback)
)
async def test_base_exception_caught(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
k = execution_kernel
# Raise an exception and test that the runner generates a traceback that
# includes the line number where the exception was raised
#
# Make sure BaseException is caught
#
# first run the cell to populate the graph
await k.run(
[
er := exec_req.get_with_id(
"1",
"""
x = 0
raise BaseException
""",
)
]
)
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
with capture_stderr() as buffer:
await runner.run(er.cell_id)
assert "line 3" in buffer.getvalue()
assert k.debugger._last_traceback == k.debugger._last_tracebacks["1"]
assert k.debugger._last_traceback is not None
assert "line 3" in "\n".join(
traceback.format_tb(k.debugger._last_traceback)
)
@pytest.mark.skipif(
not DependencyManager.sqlglot.has(), reason="SQLGlot not installed"
)
async def test_sql_parse_error_suppresses_python_traceback(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
k = execution_kernel
# first run the cell to populate the graph
await k.run(
[
er := exec_req.get_with_id(
"sql-1",
"""
from sqlglot.errors import ParseError
raise ParseError("malformed SQL")
""",
)
]
)
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
with capture_stderr() as buffer:
await runner.run(er.cell_id)
stderr = buffer.getvalue()
assert "Traceback (most recent call last):" not in stderr
assert isinstance(runner.exceptions[er.cell_id], MarimoSQLError)
async def test_ui_element_update_skips_overridden_cells(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
"""Test that UI element updates skip cells whose defs are overridden."""
from marimo._runtime.commands import UpdateUIElementCommand
k = execution_kernel
await k.run(
[
exec_req.get(
"""
from marimo import App
import marimo as mo
app = App()
@app.cell
def _():
import marimo as mo
# Use a counter to track how many times this cell runs
slider = mo.ui.slider(0, 10, value=5)
return (slider,)
@app.cell
def _(slider):
# This cell defines x based on the slider
x = slider.value
return (x,)
@app.cell
def _(x):
# This cell uses x
result = x * 2
return (result,)
"""
),
exec_req.get(
"""
# Embed with x overridden - the cell defining x should be skipped
# on UI element updates
embed_result = await app.embed(defs={"x": 100})
slider_element = embed_result.defs["slider"]
initial_result = embed_result.defs["result"]
"""
),
]
)
assert not k.errors
# With x=100 overridden, result should be 200
assert k.globals["initial_result"] == 200
# Now update the slider - the cell defining x should NOT run
# because x is overridden
slider_element = k.globals["slider_element"]
assert await k.set_ui_element_value(
UpdateUIElementCommand.from_ids_and_values([(slider_element._id, 8)]),
notify_frontend=False,
)
# After UI update, result should still be 200 because x is still overridden
embed_result = k.globals["embed_result"]
assert embed_result.defs["result"] == 200
# x should still be the overridden value, not slider.value
assert embed_result.defs["x"] == 100
async def test_converging_cell_stays_stopped_until_all_branches_trigger(
k: Kernel, exec_req: ExecReqProvider
) -> None:
await k.run(
[
exec_req.get("import marimo as mo"),
exec_req.get_with_id("a", "mo.stop(True); a = 'A'"),
exec_req.get("mo.stop(True); b = 'B'"),
exec_req.get_with_id("res", "result = a + b"),
]
)
assert "a" not in k.globals
assert "b" not in k.globals
await k.run([exec_req.get_with_id("a", "a = 'A'")])
assert "a" in k.globals
assert "b" not in k.globals
assert "result" not in k.globals
assert k.graph.cells["res"].run_result_status == "cancelled"
async def test_sibling_cells_of_stopped_ancestor_both_cancelled(
k: Kernel, exec_req: ExecReqProvider
) -> None:
await k.run(
[
exec_req.get("import marimo as mo"),
exec_req.get_with_id("stopper", "mo.stop(True); s = 1"),
exec_req.get_with_id("trigger", "t = 1"),
exec_req.get_with_id("s1", "x = s + t"),
exec_req.get_with_id("s2", "y = s + t"),
]
)
assert "x" not in k.globals
assert "y" not in k.globals
await k.run([exec_req.get_with_id("trigger", "t = 2")])
assert "x" not in k.globals
assert "y" not in k.globals
assert k.graph.cells["s1"].run_result_status == "cancelled"
assert k.graph.cells["s2"].run_result_status == "cancelled"
async def test_converging_runs_when_all_branches_trigger(
k: Kernel, exec_req: ExecReqProvider
) -> None:
await k.run(
[
exec_req.get("import marimo as mo"),
exec_req.get_with_id("a", "mo.stop(True); a = 'A'"),
exec_req.get_with_id("b", "mo.stop(True); b = 'B'"),
exec_req.get_with_id("res", "result = a + b"),
]
)
assert "a" not in k.globals
assert "b" not in k.globals
await k.run([exec_req.get_with_id("a", "a = 'A'")])
await k.run([exec_req.get_with_id("b", "b = 'B'")])
assert "a" in k.globals
assert "b" in k.globals
assert "result" in k.globals
assert k.graph.cells["res"].run_result_status == "success"
# --- Surface 3: registered plugin Executor runs via Runner ------------------
async def test_runner_dispatches_to_registered_plugin_executor(
execution_kernel: Kernel,
exec_req: ExecReqProvider,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""A factory registered against `marimo.cell.executor` is the one
the kernel `Runner` dispatches through."""
from typing import Any
from marimo._runtime.executor.evaluator import _EXECUTOR_REGISTRY
recorded: list[str] = []
sentinel_output = object()
class _SentinelExecutor:
name = "sentinel"
def execute_cell(self, cell: Any, glbls: dict[str, Any]) -> object:
del glbls
recorded.append(cell.cell_id)
return sentinel_output
async def execute_cell_async(
self, cell: Any, glbls: dict[str, Any]
) -> object:
del glbls
recorded.append(cell.cell_id)
return sentinel_output
def factory() -> _SentinelExecutor:
return _SentinelExecutor()
# Populate the kernel first (uses the real DefaultExecutor — the
# registry isn't patched yet).
k = execution_kernel
await k.run([er := exec_req.get("'hello'; 123")])
# Fully isolate the registry: replace both `_plugins` and
# `names` so installed third-party entry points can't shadow the
# sentinel. monkeypatch restores both on teardown.
monkeypatch.setattr(_EXECUTOR_REGISTRY, "_plugins", {"sentinel": factory})
monkeypatch.setattr(_EXECUTOR_REGISTRY, "names", lambda: ["sentinel"])
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
run_result = await runner.run(er.cell_id)
assert recorded == [er.cell_id]
assert run_result.output is sentinel_output
# --- Surface 4: Runner.interrupted flips on cancellation --------------------
async def test_runner_interrupted_flag_flips_on_sync_marimo_interrupt(
execution_kernel: Kernel, exec_req: ExecReqProvider
) -> None:
"""Sync cell body raising `MarimoInterrupt` (== `KeyboardInterrupt`)
surfaces as a bare `MarimoInterrupt` in the run result and flips
`runner.interrupted`."""
k = execution_kernel
await k.run([er := exec_req.get("raise KeyboardInterrupt")])
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
with capture_stderr():
await runner.run(er.cell_id)
assert runner.interrupted is True
async def test_runner_interrupted_flag_flips_on_async_cell_cancellation(
execution_kernel: Kernel,
exec_req: ExecReqProvider,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""An async cell cancelled mid-await flips `runner.interrupted`.
A bare `asyncio.CancelledError` arriving in `RunResult.exception` is
converted to `MarimoInterrupt` by the bare-`CancelledError` branch
of `_finalize_run_result`, which `run()` recognises to flip the
flag.
Simulates the evaluator output directly (a bare `CancelledError` in
the `RunResult`) so this test is independent of the executor's
coroutine compilation.
"""
import asyncio
from marimo._runtime.runner.result import RunResult
k = execution_kernel
await k.run([er := exec_req.get("123")])
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
async def fake_evaluate(cell, glbls): # type: ignore[no-untyped-def]
del cell, glbls
return RunResult(output=None, exception=asyncio.CancelledError())
monkeypatch.setattr(runner._evaluator, "evaluate", fake_evaluate)
with capture_stderr():
await runner.run(er.cell_id)
assert runner.interrupted is True
async def test_run_all_sends_one_interrupted_notification_after_idle(
mocked_kernel: MockedKernel, exec_req: ExecReqProvider
) -> None:
"""An interrupted run sends exactly one `InterruptedNotification`,
and it follows the cell's `idle` status. The runner sends it from
normal control flow, not from the signal handler."""
k = mocked_kernel.k
await k.run([er := exec_req.get("raise KeyboardInterrupt")])
mocked_kernel.stream.messages.clear()
runner = Runner(
roots={er.cell_id},
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=create_default_hooks(),
execution_context=k._install_execution_context,
)
with capture_stderr():
await runner.run_all()
operations = mocked_kernel.stream.parsed_operations
interrupted = [
i
for i, op in enumerate(operations)
if isinstance(op, InterruptedNotification)
]
idle = [
i
for i, op in enumerate(operations)
if isinstance(op, CellNotification)
and op.cell_id == er.cell_id
and op.status == "idle"
]
assert runner.interrupted
assert len(interrupted) == 1
assert idle
assert idle[-1] < interrupted[0]
@pytest.mark.parametrize("with_execution_context", [True, False])
@pytest.mark.parametrize("interrupt_count", [1, 2])
async def test_post_execution_interrupt_still_finalizes_cell(
mocked_kernel: MockedKernel,
exec_req: ExecReqProvider,
monkeypatch: pytest.MonkeyPatch,
with_execution_context: bool,
interrupt_count: int,
) -> None:
k = mocked_kernel.k
await k.run(
[
er := exec_req.get("x = 123; x"),
child := exec_req.get("y = x + 1"),
]
)
del k.globals["y"]
mocked_kernel.stream.messages.clear()
cell = k.graph.cells[er.cell_id]
events: list[str] = []
def interrupt(
cell: CellImpl, ctx: PostExecutionHookContext, result: RunResult
) -> None:
del ctx
if cell.cell_id != er.cell_id:
return
assert cell.runtime_state == "running"
assert (result.output, result.exception) == (123, None)
events.append("interrupt")
raise KeyboardInterrupt
def flush_console() -> None:
assert cell.runtime_state == "running"
events.append("flush")
monkeypatch.setattr(k.stream, "flush_console", flush_console)
hooks = create_default_hooks()
for _ in range(interrupt_count):
hooks.add_post_execution(interrupt, Priority.EARLY)
runner = Runner(
roots={er.cell_id},
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=hooks,
execution_context=(
k._install_execution_context if with_execution_context else None
),
)
await runner.run_all()
assert (cell.runtime_state, cell.run_result_status) == ("idle", "success")
assert events == ["interrupt"] * interrupt_count + ["flush"]
assert [
op.status
for op in mocked_kernel.stream.cell_notifications
if op.cell_id == er.cell_id and op.status is not None
] == ["queued", "running", "idle"]
assert runner.interrupted
assert "y" not in k.globals
assert k.graph.cells[child.cell_id].runtime_state == "idle"
@pytest.mark.parametrize("with_execution_context", [True, False])
@pytest.mark.parametrize("interrupted_cleanup", ["flush", "idle"])
async def test_interrupt_during_finalization_still_broadcasts_idle(
mocked_kernel: MockedKernel,
exec_req: ExecReqProvider,
monkeypatch: pytest.MonkeyPatch,
with_execution_context: bool,
interrupted_cleanup: str,
) -> None:
k = mocked_kernel.k
await k.run([er := exec_req.get("123")])
mocked_kernel.stream.messages.clear()
cell = k.graph.cells[er.cell_id]
interruptions = 0
events: list[str] = []
broadcast_status = CellNotificationUtils.broadcast_status
def maybe_interrupt(cleanup: str) -> None:
nonlocal interruptions
if cleanup == interrupted_cleanup and interruptions < 2:
interruptions += 1
raise KeyboardInterrupt
def flush_console() -> None:
maybe_interrupt("flush")
events.append("flush")
def broadcast_status_with_interrupt(*args: Any, **kwargs: Any) -> None:
if kwargs.get("status") == "idle":
# The local state is already idle; the frontend still needs
# the notification even when that state hasn't changed.
assert cell.runtime_state == "idle"
maybe_interrupt("idle")
events.append("idle")
broadcast_status(*args, **kwargs)
monkeypatch.setattr(k.stream, "flush_console", flush_console)
monkeypatch.setattr(
CellNotificationUtils,
"broadcast_status",
broadcast_status_with_interrupt,
)
runner = Runner(
roots={er.cell_id},
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=create_default_hooks(),
execution_context=(
k._install_execution_context if with_execution_context else None
),
)
await runner.run_all()
assert interruptions == 2
assert events[-2:] == ["flush", "idle"]
assert (cell.runtime_state, cell.run_result_status) == ("idle", "success")
assert [
op.status
for op in mocked_kernel.stream.cell_notifications
if op.cell_id == er.cell_id and op.status is not None
] == ["queued", "running", "idle"]
assert runner.interrupted
async def test_post_execution_error_still_finalizes_cell(
mocked_kernel: MockedKernel,
exec_req: ExecReqProvider,
) -> None:
k = mocked_kernel.k
await k.run([er := exec_req.get("123")])
mocked_kernel.stream.messages.clear()
def fail(
cell: CellImpl, ctx: PostExecutionHookContext, result: RunResult
) -> None:
del cell, ctx, result
raise ValueError("post-execution failed")
hooks = create_default_hooks()
hooks.add_post_execution(fail)
runner = Runner(
roots={er.cell_id},
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=hooks,
execution_context=k._install_execution_context,
)
with pytest.raises(ValueError, match="post-execution failed"):
await runner.run_all()
assert k.graph.cells[er.cell_id].runtime_state == "idle"
assert [
op.status
for op in mocked_kernel.stream.cell_notifications
if op.cell_id == er.cell_id and op.status is not None
] == ["queued", "running", "idle"]
async def test_run_all_swallows_sigint_raise_and_fires_on_finish(
execution_kernel: Kernel,
exec_req: ExecReqProvider,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""SIGINT delivered while `run_all` is in the prescan (or between
cells) raises `MarimoInterrupt` (== `KeyboardInterrupt`). `run_all`
must catch it so on_finish_hooks still fire and the
`KeyboardInterrupt` doesn't unwind past the kernel control loop.
"""
k = execution_kernel
await k.run([er := exec_req.get("123")])
del er
on_finish_calls: list[Any] = []
class _Hooks(NotebookCellHooks):
on_finish_hooks = (lambda ctx: on_finish_calls.append(ctx),)
runner = Runner(
roots=set(k.graph.cells.keys()),
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=_Hooks(),
)
# Simulate the sync-path SIGINT handler: cancel the queue and raise.
def _raise_via_prescan(_cell_id: Any) -> Any:
runner._scheduler.cancel_all()
raise KeyboardInterrupt
monkeypatch.setattr(
runner, "_find_first_blocked_missing_ref", _raise_via_prescan
)
# Must not raise; on_finish_hooks must still fire.
await runner.run_all()
assert runner.interrupted is True
assert len(on_finish_calls) == 1
assert on_finish_calls[0].interrupted is True
# Codex P2 regression: cells_to_run must still be visible to
# on_finish_hooks. SIGINT mid-prescan must not leave the queue
# drained.
assert list(on_finish_calls[0].cells_to_run), (
"on_finish_hooks must see the cells that were still queued "
"when SIGINT fired"
)
async def test_traceback_keeps_source_captured_before_await(
execution_kernel: Kernel,
exec_req: ExecReqProvider,
monkeypatch: pytest.MonkeyPatch,
) -> None:
from unittest.mock import Mock
from marimo._ast.compiler import compile_cell
from marimo._runtime.exceptions import MarimoRuntimeException
k = execution_kernel
request = exec_req.get("original_source = 1")
await k.run([request])
runner = Runner(
roots={request.cell_id},
graph=k.graph,
glbls=k.globals,
debugger=k.debugger,
hooks=NotebookCellHooks(),
)
async def replace_cell(_cell: CellImpl) -> RunResult:
k.graph.cells[request.cell_id] = compile_cell(
"replacement_source = 2", cell_id=request.cell_id
)
exception = MarimoRuntimeException()
exception.__cause__ = ValueError("bad")
return RunResult(output=None, exception=exception)
writer = Mock()
monkeypatch.setattr(runner, "evaluate_interruptible", replace_cell)
monkeypatch.setattr(
"marimo._runtime.runner.cell_runner.write_traceback", writer
)
await runner.run(request.cell_id)
assert writer.call_args.kwargs["code"] == "original_source = 1"