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
from __future__ import annotations
import sys
import threading
from unittest.mock import MagicMock, patch
import pytest
from marimo._plugins.ui._impl.anywidget.init import CommLifecycleItem
from marimo._plugins.ui._impl.comm import (
MarimoComm,
MarimoCommManager,
)
from marimo._runtime.commands import (
ModelCommand,
ModelCustomMessage,
ModelUpdateMessage,
)
from marimo._types.ids import WidgetModelId
@pytest.fixture
def comm_manager():
return MarimoCommManager()
@pytest.fixture
def comm(comm_manager: MarimoCommManager) -> MarimoComm:
comm_id = WidgetModelId("test-comm")
with patch("marimo._plugins.ui._impl.comm.broadcast_notification"):
c = MarimoComm(
comm_id=comm_id,
comm_manager=comm_manager,
target_name="test_target",
)
yield c # type: ignore[misc]
# Ensure the comm is closed so __del__ doesn't fire broadcast_notification
# during garbage collection in a later test's patch scope.
with patch("marimo._plugins.ui._impl.comm.broadcast_notification"):
c._closed = True
def test_comm_manager_register_unregister(
comm_manager: MarimoCommManager, comm: MarimoComm
):
# comm is already registered during __init__
comm_id = comm.comm_id
assert comm_id in comm_manager.comms
assert comm_manager.comms[comm_id] == comm
# Test unregistration
unregistered_comm = comm_manager.unregister_comm(comm)
assert unregistered_comm == comm
assert comm_id not in comm_manager.comms
def test_comm_manager_receive_unknown_message(
comm_manager: MarimoCommManager,
):
with patch("marimo._plugins.ui._impl.comm.LOGGER") as mock_logger:
command = ModelCommand(
model_id=WidgetModelId("unknown"),
message=ModelUpdateMessage(state={}, buffer_paths=[]),
buffers=[],
)
comm_manager.receive_comm_message(command)
mock_logger.debug.assert_called_once()
def test_comm_initialization(comm: MarimoComm):
assert comm.comm_id == WidgetModelId("test-comm")
assert comm.target_name == "test_target"
assert comm.kernel == "marimo"
assert not comm._closed
assert comm._msg_callback is None
assert comm._close_callback is None
def test_comm_open(comm: MarimoComm):
with patch.object(comm, "_broadcast") as mock_broadcast:
comm.open(data={"test": "data"})
mock_broadcast.assert_called_once_with(
{"test": "data"}, [], esm_spec=None
)
assert not comm._closed
def test_comm_send(comm: MarimoComm):
with patch.object(comm, "_broadcast") as mock_broadcast:
comm.send(data={"test": "data"})
mock_broadcast.assert_called_once_with(
{"test": "data"}, [], esm_spec=None
)
def test_comm_close(comm: MarimoComm):
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm.close(data={"test": "data"})
mock_broadcast.assert_called_once()
assert comm._closed
def test_comm_close_already_closed(comm: MarimoComm):
comm._closed = True
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm.close()
mock_broadcast.assert_not_called()
def test_comm_on_msg(comm: MarimoComm):
callback = MagicMock()
comm.on_msg(callback)
assert comm._msg_callback == callback
def test_comm_on_close(comm: MarimoComm):
callback = MagicMock()
comm.on_close(callback)
assert comm._close_callback == callback
def test_comm_handle_msg(comm: MarimoComm):
callback = MagicMock()
comm.on_msg(callback)
msg = {"test": "message"}
comm.handle_msg(msg)
callback.assert_called_once_with(msg)
def test_comm_handle_msg_no_callback(comm: MarimoComm):
with patch("marimo._plugins.ui._impl.comm.LOGGER") as mock_logger:
msg = {"test": "message"}
comm.handle_msg(msg)
mock_logger.warning.assert_called_once()
def test_comm_handle_close(comm: MarimoComm):
callback = MagicMock()
comm.on_close(callback)
msg = {"test": "message"}
comm.handle_close(msg)
callback.assert_called_once_with(msg)
def test_comm_handle_close_no_callback(comm: MarimoComm):
with patch("marimo._plugins.ui._impl.comm.LOGGER") as mock_logger:
msg = {"test": "message"}
comm.handle_close(msg)
mock_logger.debug.assert_called()
def test_comm_broadcast(comm: MarimoComm):
"""Test that _broadcast sends a ModelLifecycleNotification."""
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm._broadcast({"method": "update", "state": {"key": "value"}}, [])
mock_broadcast.assert_called_once()
notification = mock_broadcast.call_args[0][0]
assert notification.model_id == comm.comm_id
def test_comm_drops_echo_update(comm: MarimoComm):
"""echo_update (ipywidgets' ack of a client write) is never broadcast."""
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm._broadcast(
{"method": "echo_update", "state": {"key": "value"}},
[],
)
mock_broadcast.assert_not_called()
def test_client_update_is_not_echoed_back(
comm_manager: MarimoCommManager, comm: MarimoComm
):
"""A client write must not bounce back as a live update.
Simulates ipywidgets' `Widget.set_state`, which acks a client
update with `echo_update` before observers send genuine updates.
Guarantees an echo is sent, unlike the real-stack test in
test_anywidget.py, where echoing is up to ipywidgets.
"""
def fake_set_state(msg: dict) -> None:
state = msg["content"]["data"]["state"]
# ipywidgets acks the client's own values first...
comm.send({"method": "echo_update", "state": state})
# ...then an observer reacts with a kernel-driven change.
comm.send({"method": "update", "state": {"chart": "<new svg>"}})
comm.on_msg(fake_set_state)
command = ModelCommand(
model_id=comm.comm_id,
message=ModelUpdateMessage(state={"slider": 5}, buffer_paths=[]),
buffers=[],
)
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm_manager.receive_comm_message(command)
# Exactly one broadcast: the observer's update. The echo of
# {"slider": 5} is dropped.
mock_broadcast.assert_called_once()
notification = mock_broadcast.call_args[0][0]
assert notification.message.state == {"chart": "<new svg>"}
def test_comm_manager_receive_update_message(
comm_manager: MarimoCommManager, comm: MarimoComm
):
"""Test receiving an update message through the comm manager."""
callback = MagicMock()
comm.on_msg(callback)
comm.ui_element_id = "test-element"
command = ModelCommand(
model_id=comm.comm_id,
message=ModelUpdateMessage(
state={"key": "value"},
buffer_paths=[],
),
buffers=[],
)
result = comm_manager.receive_comm_message(command)
assert result == ("test-element", {"key": "value"})
callback.assert_called_once()
def test_comm_manager_receive_custom_message(
comm_manager: MarimoCommManager, comm: MarimoComm
):
"""Test receiving a custom message through the comm manager."""
callback = MagicMock()
comm.on_msg(callback)
command = ModelCommand(
model_id=comm.comm_id,
message=ModelCustomMessage(
content={"custom": "data"},
),
buffers=[],
)
result = comm_manager.receive_comm_message(command)
assert result == (None, None)
callback.assert_called_once()
def test_comm_lifecycle_item_dispose_closes_comm(
comm_manager: MarimoCommManager, comm: MarimoComm
):
"""CommLifecycleItem.dispose() should close the comm."""
item = CommLifecycleItem(comm)
assert not comm._closed
assert comm.comm_id in comm_manager.comms
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
result = item.dispose(context=MagicMock(), deletion=False)
assert result is True
assert comm._closed
assert comm.comm_id not in comm_manager.comms
mock_broadcast.assert_called_once()
class _CustomBytes:
"""Simulates obstore.Bytes — implements buffer protocol but not a
subclass of bytes/memoryview/bytearray."""
def __init__(self, data: bytes):
self._data = data
def __buffer__(self, flags: int = 0) -> memoryview:
return memoryview(self._data)
class TestBroadcastBufferTypes:
"""Broadcast through the comm with various buffer types and verify the
notification carries the right data after a serialize/deserialize
roundtrip."""
PAYLOAD = b"RIFF\x00\x01binary\xff\xfe"
def _roundtrip_buffer(self, comm, buf):
"""Broadcast a buffer through the comm and return the deserialized
notification."""
from marimo._messaging.notification import ModelLifecycleNotification
from marimo._messaging.serde import (
deserialize_kernel_message,
serialize_kernel_message,
)
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm._broadcast(
{"method": "update", "state": {}, "buffer_paths": []},
[buf],
)
notification = mock_broadcast.call_args[0][0]
assert isinstance(notification, ModelLifecycleNotification)
# Full roundtrip through JSON serialization
raw = serialize_kernel_message(notification)
return deserialize_kernel_message(raw)
def test_bytes_buffer(self, comm):
result = self._roundtrip_buffer(comm, self.PAYLOAD)
assert result.message.buffers == [self.PAYLOAD]
def test_memoryview_buffer(self, comm):
result = self._roundtrip_buffer(comm, memoryview(self.PAYLOAD))
assert result.message.buffers == [self.PAYLOAD]
def test_bytearray_buffer(self, comm):
result = self._roundtrip_buffer(comm, bytearray(self.PAYLOAD))
assert result.message.buffers == [self.PAYLOAD]
@pytest.mark.skipif(
sys.version_info < (3, 12),
reason="__buffer__ dunder requires Python 3.12+",
)
def test_custom_buffer_protocol(self, comm):
"""Custom buffer-protocol objects (like obstore.Bytes) survive the
roundtrip."""
result = self._roundtrip_buffer(comm, _CustomBytes(self.PAYLOAD))
assert result.message.buffers == [self.PAYLOAD]
def test_unsupported_type_raises(self):
from marimo._plugins.ui._impl.comm import _ensure_bytes
with pytest.raises(TypeError):
_ensure_bytes("not bytes")
class TestEsmSpecMinting:
"""`_open` mints the ESM spec — the only channel widget code takes
to the frontend."""
ESM = "export default { render({ model, el }) {} }"
def _open_comm(self, comm_manager, state):
"""Open a comm with `state` and return (comm, broadcast message)."""
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm = MarimoComm(
comm_id=WidgetModelId("esm-test"),
comm_manager=comm_manager,
target_name="jupyter.widget",
data={"state": state, "buffer_paths": [], "method": "open"},
)
notification = mock_broadcast.call_args[0][0]
# Prevent __del__ from broadcasting outside the patch scope.
comm._closed = True
return comm, notification.message
def test_inline_esm_is_minted_and_stripped(self, comm_manager):
from marimo._utils.code import hash_code
state = {"_esm": self.ESM, "count": 1}
comm, message = self._open_comm(comm_manager, state)
assert message.esm_spec is not None
# Without a runtime context, virtual files degrade to data URLs
# (see VirtualFile.create_and_register); in a live kernel this
# is a ./@file/ URL instead. Either way it is importable.
assert message.esm_spec.url.startswith("data:")
assert message.esm_spec.hash == hash_code(self.ESM)
# Code must not travel in state; everything else must.
assert "_esm" not in message.state
assert message.state["count"] == 1
# The comm keeps the spec for repr formatters.
assert comm.esm_spec == message.esm_spec
def test_url_form_esm_passes_through(self, comm_manager):
from marimo._utils.code import hash_code
url = "https://esm.sh/[email protected]"
_, message = self._open_comm(comm_manager, {"_esm": url})
assert message.esm_spec is not None
assert message.esm_spec.url == url
assert message.esm_spec.hash == hash_code(url)
def test_url_form_esm_normalizes_scheme(self, comm_manager):
url = "HTTPS://esm.sh/[email protected]"
_, message = self._open_comm(comm_manager, {"_esm": url})
assert message.esm_spec is not None
assert message.esm_spec.url == "https://esm.sh/[email protected]"
def test_virtual_file_url_esm_passes_through(self, comm_manager):
from marimo._utils.code import hash_code
url = "./@file/64-bundle.js"
_, message = self._open_comm(comm_manager, {"_esm": url})
assert message.esm_spec is not None
assert message.esm_spec.url == url
assert message.esm_spec.hash == hash_code(url)
def test_url_like_inline_esm_is_minted(self, comm_manager):
esm = "data: {\n const value = 1;\n}\nexport default {};"
_, message = self._open_comm(comm_manager, {"_esm": esm})
assert message.esm_spec is not None
assert message.esm_spec.url.startswith(
"data:application/javascript;base64,"
)
assert message.esm_spec.url != esm
def test_no_esm_means_no_spec(self, comm_manager):
comm, message = self._open_comm(comm_manager, {"value": 5})
assert message.esm_spec is None
assert comm.esm_spec is None
assert message.state == {"value": 5}
def test_empty_esm_means_no_spec(self, comm_manager):
_, message = self._open_comm(comm_manager, {"_esm": ""})
assert message.esm_spec is None
def test_caller_state_is_not_mutated(self, comm_manager):
# ipywidgets may still own the state dict it hands to open();
# stripping must happen on a copy.
state = {"_esm": self.ESM, "count": 1}
self._open_comm(comm_manager, state)
assert state["_esm"] == self.ESM
def test_spec_survives_serde_roundtrip(self, comm_manager):
from marimo._messaging.serde import (
deserialize_kernel_message,
serialize_kernel_message,
)
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm = MarimoComm(
comm_id=WidgetModelId("esm-roundtrip"),
comm_manager=comm_manager,
target_name="jupyter.widget",
data={
"state": {"_esm": self.ESM},
"buffer_paths": [],
"method": "open",
},
)
notification = mock_broadcast.call_args[0][0]
comm._closed = True
result = deserialize_kernel_message(
serialize_kernel_message(notification)
)
assert result.message.esm_spec == notification.message.esm_spec
class TestAnywidgetWireReferences:
ESM = "export default { render() {} }"
def test_model_open_preserves_serialized_widget_refs(
self, comm_manager: MarimoCommManager
) -> None:
from marimo._messaging.serde import (
deserialize_kernel_message,
serialize_kernel_message,
)
child = "anywidget:child-open"
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm = MarimoComm(
comm_id=WidgetModelId("parent-open"),
comm_manager=comm_manager,
target_name="jupyter.widget",
data={
"state": {
"_esm": self.ESM,
"child": child,
"layout": {"items": [child, {"nested": child}]},
},
"buffer_paths": [],
"method": "open",
},
)
notification = mock_broadcast.call_args[0][0]
comm._closed = True
expected_state = {
"child": "anywidget:child-open",
"layout": {
"items": [
"anywidget:child-open",
{"nested": "anywidget:child-open"},
]
},
}
assert notification.message.state == expected_state
roundtripped = deserialize_kernel_message(
serialize_kernel_message(notification)
)
assert roundtripped.message.state == expected_state
def test_model_update_preserves_serialized_widget_ref(
self, comm_manager: MarimoCommManager
) -> None:
replacement = "anywidget:child-update"
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
comm = MarimoComm(
comm_id=WidgetModelId("parent-update"),
comm_manager=comm_manager,
target_name="jupyter.widget",
data={
"state": {"_esm": self.ESM},
"buffer_paths": [],
"method": "open",
},
)
mock_broadcast.reset_mock()
comm.send(
data={
"state": {"child": replacement},
"buffer_paths": [],
"method": "update",
}
)
notification = mock_broadcast.call_args[0][0]
comm._closed = True
assert notification.message.state == {
"child": "anywidget:child-update"
}
def test_comm_lifecycle_item_dispose_idempotent(comm: MarimoComm):
"""Calling dispose twice should not error (comm.close is idempotent)."""
item = CommLifecycleItem(comm)
with patch("marimo._plugins.ui._impl.comm.broadcast_notification"):
item.dispose(context=MagicMock(), deletion=False)
# Second dispose — comm is already closed, should be a no-op
result = item.dispose(context=MagicMock(), deletion=True)
assert result is True
assert comm._closed
class TestEsmHotReload:
"""`send` intercepts `_esm` in updates: a code change on a live
model becomes a fresh spec in edit sessions and is dropped
everywhere else."""
ESM_V2 = "export default { render({ model, el }) { /* v2 */ } }"
def _send_update(self, comm_manager, mode):
with patch(
"marimo._plugins.ui._impl.comm.broadcast_notification"
) as mock_broadcast:
with patch(
"marimo._runtime.context.utils.get_mode", return_value=mode
):
comm = MarimoComm(
comm_id=WidgetModelId("hmr-test"),
comm_manager=comm_manager,
target_name="jupyter.widget",
data={
"state": {"_esm": "export default {}"},
"buffer_paths": [],
"method": "open",
},
)
comm.send(
data={
"state": {"_esm": self.ESM_V2, "count": 1},
"buffer_paths": [],
"method": "update",
}
)
update = mock_broadcast.call_args[0][0].message
comm._closed = True
return comm, update
def test_edit_mode_mints_new_spec(self, comm_manager):
from marimo._utils.code import hash_code
comm, update = self._send_update(comm_manager, "edit")
assert "_esm" not in update.state
assert update.state["count"] == 1
assert update.esm_spec is not None
assert update.esm_spec.hash == hash_code(self.ESM_V2)
# The comm's spec follows the live code so late repr formatters
# and replay see the current generation.
assert comm.esm_spec == update.esm_spec
def test_run_mode_drops_code_entirely(self, comm_manager):
from marimo._utils.code import hash_code
comm, update = self._send_update(comm_manager, "run")
assert "_esm" not in update.state
assert update.state["count"] == 1
# Viewers' widget code is immutable for the model's lifetime.
assert update.esm_spec is None
assert comm.esm_spec is not None
assert comm.esm_spec.hash == hash_code("export default {}")
def test_plain_thread_send_uses_creation_session(
self, executing_kernel, comm_manager
):
"""A library-owned watcher thread keeps the comm's mode and stream."""
from marimo._messaging.notification import (
ModelLifecycleNotification,
ModelUpdate,
)
from marimo._utils.code import hash_code
comm = MarimoComm(
comm_id=WidgetModelId("thread-hmr-test"),
comm_manager=comm_manager,
target_name="jupyter.widget",
data={
"state": {"_esm": "export default {}", "_css": ""},
"buffer_paths": [],
"method": "open",
},
)
stream = executing_kernel.stream
stream.messages.clear()
errors: list[BaseException] = []
def send_update() -> None:
try:
comm.send(
data={
"state": {
"_esm": self.ESM_V2,
"_css": "button { color: hotpink; }",
},
"buffer_paths": [],
"method": "update",
}
)
except BaseException as exc:
errors.append(exc)
watcher = threading.Thread(target=send_update)
watcher.start()
watcher.join(timeout=1)
assert not watcher.is_alive()
assert not errors
assert len(stream.operations) == 1
notification = stream.operations[0]
assert isinstance(notification, ModelLifecycleNotification)
assert isinstance(notification.message, ModelUpdate)
assert notification.message.state == {
"_css": "button { color: hotpink; }"
}
assert notification.message.esm_spec is not None
assert notification.message.esm_spec.hash == hash_code(self.ESM_V2)
# The callback thread intentionally does not inherit the mutable
# runtime context; inline HMR modules therefore use the supported
# data-URL transport instead of touching the virtual-file registry.
assert notification.message.esm_spec.url.startswith("data:")
comm.close()
class TestClientUpdateStrip:
"""Clients may write widget state, never widget code or style."""
def test_strips_esm_and_css_from_client_updates(
self, comm_manager, comm: MarimoComm
):
received: list[dict] = []
comm.on_msg(received.append)
comm.ui_element_id = "el-1"
command = ModelCommand(
model_id=comm.comm_id,
message=ModelUpdateMessage(
state={
"_esm": "alert('pwned')",
"_css": "body { display: none }",
"count": 2,
},
buffer_paths=[],
),
buffers=[],
)
ui_element_id, state = comm_manager.receive_comm_message(command)
assert ui_element_id == "el-1"
assert state == {"count": 2}
# The comm callback (ipywidgets set_state) never sees them
# either — otherwise the kernel would echo them back to peers.
payload_state = received[0]["content"]["data"]["state"]
assert "_esm" not in payload_state
assert "_css" not in payload_state
assert payload_state["count"] == 2