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.

19.9 KB
Raw Blame
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations

import dataclasses
from contextlib import contextmanager
from typing import TYPE_CHECKING

import pytest

if TYPE_CHECKING:
    from collections.abc import Generator

import re

from inline_snapshot import snapshot

from marimo._ast.cell import CellConfig
from marimo._code_mode._context import (
    AsyncCodeModeContext,
    NotebookCell as EnrichedCell,
    _CellsView,
)
from marimo._messaging.cell_output import CellChannel, CellOutput
from marimo._messaging.notebook.document import (
    NotebookCell,
    NotebookDocument,
    notebook_document_context,
)
from marimo._messaging.notebook.outputs import CellOutputs
from marimo._runtime.commands import ExecuteCellCommand
from marimo._runtime.runtime import Kernel
from marimo._types.ids import CellId_t


def cmd(cell_id: str, code: str) -> ExecuteCellCommand:
    return ExecuteCellCommand(cell_id=CellId_t(cell_id), code=code)


@contextmanager
def _ctx(k: Kernel) -> Generator[AsyncCodeModeContext, None, None]:
    """Build an AsyncCodeModeContext with a document snapshot from the kernel."""
    doc = NotebookDocument(
        [
            NotebookCell(id=cid, code=cell.code, name="", config=cell.config)
            for cid, cell in k.graph.cells.items()
        ]
    )
    with notebook_document_context(doc):
        yield AsyncCodeModeContext(k)


class TestCellsViewIndex:
    """Test integer indexing (positive and negative)."""

    async def test_positive_index(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
                cmd(cell_id="c", code="z = 3"),
            ]
        )
        with _ctx(k) as ctx:
            assert ctx.cells[0].id == "a"
            assert ctx.cells[1].id == "b"
            assert ctx.cells[2].id == "c"

    async def test_negative_index(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
                cmd(cell_id="c", code="z = 3"),
            ]
        )
        with _ctx(k) as ctx:
            assert ctx.cells[-1].id == "c"
            assert ctx.cells[-2].id == "b"
            assert ctx.cells[-3].id == "a"

    async def test_index_out_of_range(self, k: Kernel) -> None:
        await k.run([cmd(cell_id="a", code="x = 1")])
        with _ctx(k) as ctx:
            with pytest.raises(IndexError):
                ctx.cells[5]

            with pytest.raises(IndexError):
                ctx.cells[-5]


class TestCellsViewCellId:
    """Test lookup by cell ID string."""

    async def test_lookup_by_cell_id(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="abc", code="x = 1"),
                cmd(cell_id="def", code="y = 2"),
            ]
        )
        with _ctx(k) as ctx:
            cell = ctx.cells["def"]
            assert cell.id == "def"
            assert cell.code == "y = 2"

    async def test_lookup_by_cell_id_not_found(self, k: Kernel) -> None:
        await k.run([cmd(cell_id="abc", code="x = 1")])
        with _ctx(k) as ctx, pytest.raises(KeyError):
            ctx.cells["nonexistent"]


class TestCellsViewCellName:
    """Test lookup by cell name."""

    async def test_name_lookup_without_cell_manager(self, k: Kernel) -> None:
        await k.run([cmd(cell_id="a", code="x = 1")])
        with _ctx(k) as ctx:
            # No cell manager → name lookup fails
            with pytest.raises(KeyError):
                ctx.cells["my_cell"]


class TestCellsViewNameField:
    """Test that the name field is populated on NotebookCell."""

    async def test_name_is_empty_without_cell_manager(self, k: Kernel) -> None:
        await k.run([cmd(cell_id="a", code="x = 1")])
        with _ctx(k) as ctx:
            cell = ctx.cells[0]
            assert cell.name == ""


class TestCellsViewIteration:
    """Test iteration and len."""

    async def test_len(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
            ]
        )
        with _ctx(k) as ctx:
            assert len(ctx.cells) == 2

    async def test_iteration_yields_cells(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
            ]
        )
        with _ctx(k) as ctx:
            cells = list(ctx.cells)
            assert [c.id for c in cells] == ["a", "b"]
            assert [c.code for c in cells] == ["x = 1", "y = 2"]

    async def test_keys(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
            ]
        )
        with _ctx(k) as ctx:
            assert ctx.cells.keys() == ["a", "b"]

    async def test_values(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
            ]
        )
        with _ctx(k) as ctx:
            vals = ctx.cells.values()
            assert [v.id for v in vals] == ["a", "b"]
            assert [v.code for v in vals] == ["x = 1", "y = 2"]

    async def test_items(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
            ]
        )
        with _ctx(k) as ctx:
            items = ctx.cells.items()
            assert [(cid, cell.code) for cid, cell in items] == [
                ("a", "x = 1"),
                ("b", "y = 2"),
            ]

    async def test_contains(self, k: Kernel) -> None:
        await k.run(
            [
                cmd(cell_id="a", code="x = 1"),
                cmd(cell_id="b", code="y = 2"),
            ]
        )
        with _ctx(k) as ctx:
            assert "a" in ctx.cells
            assert "nonexistent" not in ctx.cells
            assert 0 in ctx.cells
            assert 5 not in ctx.cells


# ------------------------------------------------------------------
# Lightweight helper (no kernel needed)
# ------------------------------------------------------------------


def _cell(cell_id: str, code: str, name: str = "") -> NotebookCell:
    return NotebookCell(
        id=CellId_t(cell_id), code=code, name=name, config=CellConfig()
    )


def _view(cells: list[NotebookCell]) -> _CellsView:
    doc = NotebookDocument(cells)
    ctx = type(
        "_MockCtx",
        (),
        {"_document": doc, "_note_read": lambda *_args, **_kwargs: None},
    )()
    return _CellsView(ctx)


# ------------------------------------------------------------------
# __repr__
# ------------------------------------------------------------------


class TestCellsViewRepr:
    def test_repr_empty(self) -> None:
        v = _view([])
        assert repr(v) == snapshot("CellsView(0 cells):")

    def test_repr_single_cell(self) -> None:
        v = _view([_cell("a1", "x = 1")])
        assert repr(v) == snapshot("""\
CellsView(1 cell):
  [0] a1 [stale] | x = 1""")

    def test_repr_multiple_cells(self) -> None:
        v = _view([_cell("a", "x = 1"), _cell("b", "y = 2")])
        assert repr(v) == snapshot("""\
CellsView(2 cells):
  [0] a [stale] | x = 1
  [1] b [stale] | y = 2""")

    def test_repr_with_name(self) -> None:
        v = _view([_cell("a", "import marimo as mo", name="setup")])
        assert "(setup)" in repr(v)

    def test_repr_long_code_truncated(self) -> None:
        long_code = "x = " + "a" * 60
        v = _view([_cell("a", long_code)])
        r = repr(v)
        assert "..." in r
        assert long_code[:50] + "..." in r

    def test_repr_multiline_shows_first_line(self) -> None:
        v = _view([_cell("a", "line1\nline2\nline3")])
        r = repr(v)
        assert "line1" in r
        assert "line2" not in r

    def test_str_equals_repr(self) -> None:
        v = _view([_cell("a", "x = 1")])
        assert str(v) == repr(v)

    def test_repr_many_cells_truncated(self) -> None:
        cells = [_cell(f"c{i}", f"x{i} = {i}") for i in range(15)]
        v = _view(cells)
        r = repr(v)
        assert "CellsView(15 cells):" in r
        assert "[9]" in r
        assert "[14]" in r
        assert "... 4 more cells ..." in r
        assert "[11]" not in r


# ------------------------------------------------------------------
# NotebookCell.__repr__
# ------------------------------------------------------------------


class TestNotebookCellRepr:
    def test_repr_basic(self) -> None:
        c = _cell("a1", "x = 1")
        assert repr(c) == "NotebookCell(id='a1', code='x = 1')"

    def test_repr_with_name(self) -> None:
        c = _cell("a1", "import marimo as mo", name="setup")
        assert repr(c) == (
            "NotebookCell(id='a1', name='setup', code='import marimo as mo')"
        )

    def test_repr_long_code_truncated(self) -> None:
        long_code = "x = " + "a" * 100
        c = _cell("a1", long_code)
        r = repr(c)
        assert "..." in r
        assert long_code[:80] in r

    def test_repr_multiline_shows_first_line(self) -> None:
        c = _cell("a1", "line1\nline2\nline3")
        r = repr(c)
        assert "line1..." in r
        assert "line2" not in r

    def test_repr_empty_code(self) -> None:
        c = _cell("a1", "")
        assert repr(c) == "NotebookCell(id='a1', code='')"


# ------------------------------------------------------------------
# find()
# ------------------------------------------------------------------


class TestCellsViewFind:
    def test_find_match(self) -> None:
        v = _view([_cell("a", "import marimo"), _cell("b", "x = 1")])
        result = v.find("import")
        assert len(result) == 1
        assert result[0].id == "a"

    def test_find_no_match(self) -> None:
        v = _view([_cell("a", "x = 1")])
        assert v.find("pandas") == []

    def test_find_multiple_matches(self) -> None:
        v = _view(
            [
                _cell("a", "import os"),
                _cell("b", "x = 1"),
                _cell("c", "import sys"),
            ]
        )
        result = v.find("import")
        assert [c.id for c in result] == ["a", "c"]

    def test_find_case_sensitive(self) -> None:
        v = _view([_cell("a", "import os")])
        assert v.find("Import") == []


# ------------------------------------------------------------------
# grep()
# ------------------------------------------------------------------


class TestCellsViewGrep:
    def test_grep_literal(self) -> None:
        v = _view([_cell("a", "x = 1"), _cell("b", "y = 2")])
        result = v.grep("x = 1")
        assert len(result) == 1
        assert result[0].id == "a"

    def test_grep_regex(self) -> None:
        v = _view(
            [
                _cell("a", "x = 1"),
                _cell("b", "x=42"),
                _cell("c", "y = 2"),
            ]
        )
        result = v.grep(r"x\s*=\s*\d+")
        assert [c.id for c in result] == ["a", "b"]

    def test_grep_no_match(self) -> None:
        v = _view([_cell("a", "x = 1")])
        assert v.grep(r"zzz\d+") == []

    def test_grep_multiline_cell(self) -> None:
        v = _view([_cell("a", "line1\nline2_match\nline3")])
        result = v.grep("line2_match")
        assert len(result) == 1

    def test_grep_invalid_regex_raises(self) -> None:
        v = _view([_cell("a", "x = 1")])
        with pytest.raises(re.error):
            v.grep("[invalid")


# ------------------------------------------------------------------
# Error messages
# ------------------------------------------------------------------


# ------------------------------------------------------------------
# NotebookCell (enriched) status
# ------------------------------------------------------------------


@dataclasses.dataclass
class _MockImpl:
    """Minimal stand-in for CellImpl — satisfies `CellRuntimeState` protocol."""

    code: str = ""
    runtime_state: str | None = None
    run_result_status: str | None = None
    stale: bool = False
    exception: Exception | None = None


class TestEnrichedCellStatus:
    def test_no_impl_empty_returns_none(self) -> None:
        cell = _cell("a", "")
        enriched = EnrichedCell(cell, None)
        assert enriched.status is None

    def test_no_impl_with_code_returns_stale(self) -> None:
        cell = _cell("a", "x = 1")
        enriched = EnrichedCell(cell, None)
        assert enriched.status == "stale"

    def test_success_maps_to_idle(self) -> None:
        cell = _cell("a", "x = 1")
        impl = _MockImpl(code="x = 1", run_result_status="success")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "idle"

    def test_exception_status(self) -> None:
        err = ValueError("boom")
        cell = _cell("a", "x = 1")
        impl = _MockImpl(
            code="x = 1", run_result_status="exception", exception=err
        )
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "exception"
        assert len(enriched.errors) == 1
        assert enriched.errors[0].kind == "runtime"
        assert enriched.errors[0].exception is err

    def test_code_edited_becomes_stale(self) -> None:
        cell = _cell("a", "x = 2")
        impl = _MockImpl(code="x = 1", run_result_status="success")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "stale"

    def test_code_edited_after_error_becomes_stale(self) -> None:
        err = ZeroDivisionError()
        cell = _cell("a", "x = 1")
        impl = _MockImpl(
            code="1 / 0", run_result_status="exception", exception=err
        )
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "stale"
        # Error persists for inspection
        assert len(enriched.errors) == 1
        assert enriched.errors[0].exception is err

    def test_runtime_stale_flag(self) -> None:
        """Lazy mode: inputs changed but code is the same."""
        cell = _cell("a", "y = x + 1")
        impl = _MockImpl(
            code="y = x + 1", run_result_status="success", stale=True
        )
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "stale"

    def test_registered_but_never_run_is_stale(self) -> None:
        """Cell registered in graph with matching code but never executed."""
        cell = _cell("a", "x = 1")
        impl = _MockImpl(code="x = 1")  # run_result_status=None
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "stale"

    def test_registered_empty_never_run_is_none(self) -> None:
        """Empty cell registered in graph but never executed."""
        cell = _cell("a", "")
        impl = _MockImpl(code="")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status is None

    def test_queued_takes_priority(self) -> None:
        cell = _cell("a", "x = 1")
        impl = _MockImpl(code="x = 1", runtime_state="queued")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "queued"

    def test_running_takes_priority(self) -> None:
        cell = _cell("a", "x = 1")
        impl = _MockImpl(code="x = 1", runtime_state="running")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "running"

    def test_disabled_transitively_maps_to_disabled(self) -> None:
        cell = _cell("a", "x = 1")
        impl = _MockImpl(code="x = 1", runtime_state="disabled-transitively")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "disabled"

    def test_cancelled_status(self) -> None:
        cell = _cell("a", "x = 1")
        impl = _MockImpl(code="x = 1", run_result_status="cancelled")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "cancelled"

    def test_marimo_error_status(self) -> None:
        cell = _cell("a", "x = 1")
        impl = _MockImpl(code="x = 1", run_result_status="marimo-error")
        enriched = EnrichedCell(cell, impl)
        assert enriched.status == "marimo-error"

    def test_delegates_document_properties(self) -> None:
        cell = _cell("a1", "x = 1", name="my_cell")
        enriched = EnrichedCell(cell, None)
        assert enriched.id == "a1"
        assert enriched.code == "x = 1"
        assert enriched.name == "my_cell"
        assert enriched.config == CellConfig()

    def test_errors_empty_when_no_impl(self) -> None:
        cell = _cell("a", "x = 1")
        enriched = EnrichedCell(cell, None)
        assert enriched.errors == []


class TestEnrichedCellOutputs:
    """The frozen output snapshot is sliced per-cell in the properties."""

    def test_no_snapshot_returns_defaults(self) -> None:
        cell = _cell("a", "x = 1")
        enriched = EnrichedCell(cell, None)
        assert enriched.output is None
        assert enriched.console_outputs == []

    def test_populated_snapshot_returns_per_cell_slice(self) -> None:
        cell = _cell("a", "print('hi'); x = 1")
        out = CellOutput(
            channel=CellChannel.OUTPUT, mimetype="text/plain", data="1"
        )
        console = [CellOutput.stdout("hi\n"), CellOutput.stderr("warn\n")]
        snap = CellOutputs(
            output={CellId_t("a"): out},
            console_outputs={CellId_t("a"): console},
        )
        enriched = EnrichedCell(cell, None, outputs=snap)
        assert enriched.output is out
        assert enriched.console_outputs == console

    def test_cell_missing_from_snapshot_returns_defaults(self) -> None:
        """Cell created mid-batch isn't in the frozen snapshot."""
        cell = _cell("new", "y = 2")
        snap = CellOutputs(
            output={
                CellId_t("a"): CellOutput(
                    channel=CellChannel.OUTPUT,
                    mimetype="text/plain",
                    data="1",
                )
            },
            console_outputs={CellId_t("a"): [CellOutput.stdout("hi\n")]},
        )
        enriched = EnrichedCell(cell, None, outputs=snap)
        assert enriched.output is None
        assert enriched.console_outputs == []


class TestEnrichedCellRepr:
    def test_repr_no_impl_with_code(self) -> None:
        cell = _cell("a1", "x = 1")
        enriched = EnrichedCell(cell, None)
        assert repr(enriched) == snapshot(
            "NotebookCell(id='a1', status='stale', code='x = 1')"
        )

    def test_repr_no_impl_empty(self) -> None:
        cell = _cell("a1", "")
        enriched = EnrichedCell(cell, None)
        assert repr(enriched) == snapshot("NotebookCell(id='a1', code='')")

    def test_repr_with_status(self) -> None:
        cell = _cell("a1", "x = 1")
        impl = _MockImpl(code="x = 1", run_result_status="exception")
        enriched = EnrichedCell(cell, impl)
        assert repr(enriched) == snapshot(
            "NotebookCell(id='a1', status='exception', code='x = 1')"
        )

    def test_repr_with_name_and_status(self) -> None:
        cell = _cell("a1", "import os", name="setup")
        impl = _MockImpl(code="import os", run_result_status="success")
        enriched = EnrichedCell(cell, impl)
        assert repr(enriched) == snapshot(
            "NotebookCell(id='a1', name='setup', status='idle', code='import os')"
        )

    def test_repr_stale_from_code_edit(self) -> None:
        cell = _cell("a1", "x = 2")
        impl = _MockImpl(code="x = 1", run_result_status="success")
        enriched = EnrichedCell(cell, impl)
        assert repr(enriched) == snapshot(
            "NotebookCell(id='a1', status='stale', code='x = 2')"
        )


class TestCellsViewErrorMessages:
    def test_error_lists_available_ids(self) -> None:
        v = _view([_cell("abcd", "x = 1"), _cell("efgh", "y = 2")])
        with pytest.raises(KeyError, match="not found"):
            v["MzAK"]

    def test_error_mentions_stability(self) -> None:
        v = _view([_cell("abcd", "x = 1")])
        with pytest.raises(KeyError, match="stable across reorders"):
            v["gone"]

    def test_error_shows_available(self) -> None:
        v = _view([_cell("abcd", "x = 1")])
        with pytest.raises(KeyError, match="abcd"):
            v["missing"]