Skip to content

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.

24.7 KB
Raw Blame
# 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"