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.
"""The editor's session lifecycle on the host event stream."""
from __future__ import annotations
import asyncio
from typing import TYPE_CHECKING, Any
import msgspec
import pytest
from dirty_equals import IsStr
from starlette.websockets import WebSocketDisconnect
from marimo._messaging.cell_output import CellChannel, CellOutput
from marimo._messaging.notification import (
AlertNotification,
CellNotification,
StartupProgressNotification,
)
from marimo._messaging.serde import serialize_kernel_message
from marimo._server.host import HOST_API_PATH
from marimo._server.host.bridge import SessionBridge
from marimo._server.host.context import HostContext
from marimo._session.managers.ipc import KernelStartupError
from marimo._types.ids import CellId_t, ConsumerId, SessionId
from tests._server.api.endpoints.ws_helpers import headers
from tests._server.host.drive import socket_snapshot
from tests._server.mocks import get_session_manager
if TYPE_CHECKING:
from collections.abc import Iterator
from pathlib import Path
from starlette.testclient import TestClient, WebSocketTestSession
def first_cell_id(client: TestClient, session_id: str) -> CellId_t:
"""The first cell of the session's document, as the host stream has it."""
session = get_session_manager(client).get_session(SessionId(session_id))
assert session is not None
return session.document.cell_ids[0]
@pytest.fixture
def editor_host(client: TestClient) -> Iterator[SessionBridge]:
bridge = SessionBridge(get_session_manager(client))
client.app.state.host_context = HostContext( # type: ignore[union-attr]
bridge=bridge, token="host-token", port=1234
)
with client:
assert client.portal is not None
client.portal.call(bridge.open)
try:
yield bridge
finally:
client.portal.call(bridge.close)
def socket_url(bridge: SessionBridge, session_id: str = "s1") -> str:
(notebook_id,) = bridge.host.notebooks
return f"{HOST_API_PATH}/notebooks/{notebook_id}/events/ws?session_id={session_id}&access_token=fake-token"
def receive_notification(
websocket: WebSocketTestSession, op: str
) -> dict[str, Any]:
while True:
event = websocket.receive_json()
assert "op" not in event
if event["event"] == "marimo" and event["data"]["marimo"]["op"] == op:
return event["data"]["marimo"]
@pytest.mark.parametrize("types", [None, "marimo", "marimo,run"])
def test_editor_starts_and_runs_through_the_host_socket(
client: TestClient, editor_host: SessionBridge, types: str | None
) -> None:
url = socket_url(editor_host)
if types is not None:
url += f"&types={types}"
with client.websocket_connect(url) as websocket:
messages = []
while True:
event = websocket.receive_json()
messages.append(event)
if (
event["event"] == "marimo"
and event["data"]["marimo"]["op"] == "kernel-ready"
):
ready = event["data"]["marimo"]
break
assert ready["resumed"] is False
assert ready["consumer_capabilities"]["edit"] is True
boundary = next(
i for i, event in enumerate(messages) if event["event"] == "ready"
)
assert all("id" not in event for event in messages[:boundary])
assert messages[boundary]["data"] == {}
if types is None:
names = [event["event"] for event in messages[:boundary]]
assert names[0] == "notebook"
assert names.index("cell") < names.index("document")
cell_id = first_cell_id(client, "s1")
response = client.post(
"/api/kernel/run",
headers=headers("s1"),
json={"cellIds": [cell_id], "codes": ["print('host socket')"]},
)
assert response.status_code == 200, response.text
while True:
event = websocket.receive_json()
messages.append(event)
if (
event["event"] == "marimo"
and event["data"]["marimo"]["op"] == "completed-run"
):
break
received_types = {event["event"] for event in messages}
if types is None:
assert "run" in received_types
else:
assert received_types == {*types.split(","), "ready"}
consoles = [
event["data"]["marimo"]["console"]
for event in messages
if event["event"] == "marimo"
and event["data"]["marimo"]["op"] == "cell-op"
and event["data"]["marimo"]["console"]
]
assert sum("host socket" in str(output) for output in consoles) == 1
def test_editor_receives_native_attachment_snapshots_and_changes(
client: TestClient, editor_host: SessionBridge
) -> None:
assert client.portal is not None
(notebook_id,) = editor_host.host.notebooks
notebook = client.portal.call(editor_host.host.notebook, notebook_id)
agent = client.portal.call(
lambda: notebook.attach(kind="agent", name="Test Agent")
)
url = f"{socket_url(editor_host)}&types=attachment"
with client.websocket_connect(url) as socket:
snapshot = socket_snapshot(socket)
assert [event["event"] for event in snapshot] == [
"attachment",
"attachment",
"ready",
]
assert snapshot[0]["data"]["attachment"] == msgspec.to_builtins(agent)
client.portal.call(notebook.detach, agent.id)
removed = socket.receive_json()
assert removed == {
"event": "attachment.removed",
"id": IsStr,
"data": {"id": agent.id, "time": IsStr},
}
replacement = client.portal.call(
lambda: notebook.attach(kind="agent", name="Replacement")
)
attached = socket.receive_json()
assert attached["event"] == "attachment"
assert attached["data"]["attachment"] == msgspec.to_builtins(
replacement
)
client.portal.call(notebook.detach, replacement.id)
with client.websocket_connect(url) as socket:
snapshot = socket_snapshot(socket)
assert [event["event"] for event in snapshot] == [
"attachment",
"ready",
]
assert snapshot[0]["data"]["attachment"]["kind"] == "client"
def test_reconnect_keeps_state_and_refresh_replays_it(
client: TestClient, editor_host: SessionBridge
) -> None:
url = f"{socket_url(editor_host)}&types=marimo"
with client.websocket_connect(url) as websocket:
receive_notification(websocket, "kernel-ready")
cell_id = first_cell_id(client, "s1")
response = client.post(
"/api/kernel/run",
headers=headers("s1"),
json={"cellIds": [cell_id], "codes": ["print('retained output')"]},
)
assert response.status_code == 200, response.text
receive_notification(websocket, "completed-run")
with client.websocket_connect(url) as websocket:
socket_snapshot(websocket)
while True:
event = websocket.receive_json()
assert event["event"] == "marimo"
notification = event["data"]["marimo"]
assert notification["op"] not in ("kernel-ready", "cell-op")
if notification["op"] == "reconnected":
break
assert (
receive_notification(websocket, "alert")["title"] == "Reconnected"
)
cell = receive_notification(websocket, "cell-op")
assert cell["cell_id"] == cell_id
assert "retained output" in str(cell["console"])
with client.websocket_connect(
f"{socket_url(editor_host, 's2')}&types=marimo"
) as websocket:
ready = receive_notification(websocket, "kernel-ready")
assert ready["resumed"] is True
assert ready["kiosk"] is False
cell = receive_notification(websocket, "cell-op")
assert cell["cell_id"] == cell_id
assert "retained output" in str(cell["console"])
@pytest.mark.parametrize("replay", ["snapshot", "cursor", "reset"])
def test_reconnect_recovers_offline_notifications(
client: TestClient, editor_host: SessionBridge, replay: str
) -> None:
url = f"{socket_url(editor_host)}&types=marimo"
with client.websocket_connect(url) as socket:
cursor = socket_snapshot(socket)[-1]["id"]
receive_notification(socket, "kernel-ready")
session = get_session_manager(client).get_session(SessionId("s1"))
assert session is not None
assert client.portal is not None
update = CellNotification(
cell_id=session.document.cell_ids[0],
status="idle",
output=CellOutput(
channel=CellChannel.OUTPUT,
mimetype="text/plain",
data="offline output",
timestamp=1.0,
),
console=[
CellOutput(
channel=CellChannel.STDOUT,
mimetype="text/plain",
data="offline console",
timestamp=1.0,
)
],
timestamp=1.0,
)
client.portal.call(session.notify, update, None)
client.portal.call(
session.notify,
AlertNotification(title="excluded", description=""),
ConsumerId("s1"),
)
if replay == "cursor":
url += f"&cursor={cursor}"
elif replay == "reset":
# A bare integer is a cursor from a host before this one.
url += "&cursor=999999999"
with client.websocket_connect(url) as socket:
opening = socket_snapshot(socket)
assert [event["event"] for event in opening] == (
["reset", "ready"] if replay == "reset" else ["ready"]
)
receive_notification(socket, "reconnected")
client.portal.call(
session.notify,
AlertNotification(title="marker", description=""),
None,
)
notifications = []
while True:
event = socket.receive_json()
notification = event["data"]["marimo"]
if (
notification["op"] == "alert"
and notification["title"] == "marker"
):
break
notifications.append(notification)
assert [n for n in notifications if n["op"] == "cell-op"] == [
msgspec.json.decode(serialize_kernel_message(update))
]
assert not any(n["op"] == "kernel-ready" for n in notifications)
assert not any(
n["op"] == "alert" and n["title"] == "excluded"
for n in notifications
)
@pytest.mark.parametrize("run_id", ["", "wanted"])
def test_run_filter_is_rejected_before_starting_an_editor_session(
client: TestClient, editor_host: SessionBridge, run_id: str
) -> None:
with pytest.raises(WebSocketDisconnect) as exc:
with client.websocket_connect(
f"{socket_url(editor_host)}&run_id={run_id}"
):
pytest.fail("Editor run filter was accepted")
assert (exc.value.code, exc.value.reason) == (
1008,
"Editor sessions do not support run_id filtering",
)
assert not get_session_manager(client).sessions
def test_second_tab_gets_private_startup_and_excluded_messages_do_not_echo(
client: TestClient, editor_host: SessionBridge
) -> None:
with client.websocket_connect(socket_url(editor_host)) as first:
receive_notification(first, "kernel-ready")
with client.websocket_connect(socket_url(editor_host, "s2")) as second:
ready = receive_notification(second, "kernel-ready")
assert ready["kiosk"] is True
assert ready["consumer_capabilities"]["edit"] is False
session = get_session_manager(client).get_session(SessionId("s1"))
assert session is not None
first.portal.call(
session.notify,
AlertNotification(title="other client", description=""),
ConsumerId("s1"),
)
first.portal.call(
session.notify,
AlertNotification(title="marker", description=""),
None,
)
while True:
event = first.receive_json()
if event["event"] != "marimo":
continue
notification = event["data"]["marimo"]
assert notification["op"] != "kernel-ready"
if notification["op"] == "alert":
assert notification["title"] == "marker"
break
assert (
receive_notification(second, "alert")["title"]
== "other client"
)
assert receive_notification(second, "alert")["title"] == "marker"
def test_session_cannot_bind_to_another_notebook(
client: TestClient, editor_host: SessionBridge, tmp_path: Path
) -> None:
other = tmp_path / "other.py"
other.write_text("import marimo\napp = marimo.App()\n")
with pytest.raises(WebSocketDisconnect) as exc:
with client.websocket_connect(
f"{socket_url(editor_host)}&file={other}"
):
pytest.fail("Mismatched notebook was accepted")
assert exc.value.code == 1008
assert not get_session_manager(client).sessions
def test_startup_failure_is_sent_before_the_close(
client: TestClient,
editor_host: SessionBridge,
monkeypatch: pytest.MonkeyPatch,
) -> None:
async def fail(**kwargs: Any) -> None:
del kwargs
raise KernelStartupError("kernel could not start")
monkeypatch.setattr(get_session_manager(client), "create_session", fail)
with client.websocket_connect(socket_url(editor_host)) as websocket:
assert (
receive_notification(websocket, "kernel-startup-error")["error"]
== "kernel could not start"
)
with pytest.raises(WebSocketDisconnect) as exc:
websocket.receive_json()
assert (exc.value.code, exc.value.reason) == (
1011,
"MARIMO_KERNEL_STARTUP_ERROR",
)
def test_disconnect_during_startup_cancels_the_connection(
client: TestClient,
editor_host: SessionBridge,
monkeypatch: pytest.MonkeyPatch,
) -> None:
cancelled = asyncio.Event()
async def wait_for_startup(**kwargs: Any) -> None:
kwargs["session_consumer"].notify(
serialize_kernel_message(
StartupProgressNotification(
phase="starting-kernel",
logs="Starting",
log_mode="replace",
)
)
)
try:
await asyncio.Event().wait()
finally:
cancelled.set()
monkeypatch.setattr(
get_session_manager(client), "create_session", wait_for_startup
)
with client.websocket_connect(socket_url(editor_host)) as websocket:
assert (
receive_notification(websocket, "startup-progress")["logs"]
== "Starting"
)
assert client.portal is not None
client.portal.call(asyncio.wait_for, cancelled.wait(), 5)
assert not get_session_manager(client).sessions
def test_invalid_event_types_are_rejected_before_starting_a_session(
client: TestClient, editor_host: SessionBridge
) -> None:
with pytest.raises(WebSocketDisconnect) as exc:
with client.websocket_connect(
f"{socket_url(editor_host)}&types=unknown"
):
pytest.fail("Invalid event types were accepted")
assert (exc.value.code, exc.value.reason) == (1008, "Invalid event types")
assert not get_session_manager(client).sessions
@pytest.mark.parametrize("session_route", [False, True])
def test_editor_resumes_host_events_without_replaying_private_notifications(
client: TestClient, editor_host: SessionBridge, session_route: bool
) -> None:
endpoint = (
"/ws?session_id=s1&access_token=fake-token"
if session_route
else socket_url(editor_host)
)
url = f"{endpoint}&types=marimo,custom"
with client.websocket_connect(url) as socket:
cursor = socket_snapshot(socket)[-1]["id"]
receive_notification(socket, "kernel-ready")
session = get_session_manager(client).get_session(SessionId("s1"))
assert session is not None
socket.portal.call(
session.notify,
AlertNotification(title="excluded", description=""),
ConsumerId("s1"),
)
socket.portal.call(
session.notify,
AlertNotification(title="marker", description=""),
None,
)
assert receive_notification(socket, "alert")["title"] == "marker"
assert client.portal is not None
(notebook_id,) = editor_host.host.notebooks
notebook = client.portal.call(editor_host.host.notebook, notebook_id)
client.portal.call(notebook.emit, "test.missed", {"text": "replayed"})
with client.websocket_connect(f"{url}&cursor={cursor}") as socket:
opening = socket_snapshot(socket)
assert [event["event"] for event in opening] == ["custom", "ready"]
assert opening[0]["data"]["custom"] == {
"type": "test.missed",
"data": {"text": "replayed"},
}
receive_notification(socket, "reconnected")
assert receive_notification(socket, "alert")["title"] == "Reconnected"
def test_an_empty_cursor_is_rejected_before_starting_a_session(
client: TestClient, editor_host: SessionBridge
) -> None:
with pytest.raises(WebSocketDisconnect) as exc:
with client.websocket_connect(f"{socket_url(editor_host)}&cursor="):
pytest.fail("Invalid cursor was accepted")
assert (exc.value.code, exc.value.reason) == (1008, "Invalid event cursor")
assert not get_session_manager(client).sessions
def test_untitled_editor_bootstraps_and_reconnects_with_host_events(
client: TestClient,
) -> None:
from marimo._server.workspace import EmptyWorkspace
manager = get_session_manager(client)
manager.workspace = EmptyWorkspace()
bridge = SessionBridge(manager)
client.app.state.host_context = HostContext(
bridge=bridge, token="host-token", port=1234
)
url = "/ws?session_id=new&access_token=fake-token"
with client:
assert client.portal is not None
client.portal.call(bridge.open)
try:
with client.websocket_connect(url) as ws:
snapshot = socket_snapshot(ws)
receive_notification(ws, "kernel-ready")
notebook_id = next(
e["data"]["notebook"]["id"]
for e in snapshot
if e["event"] == "notebook"
)
response = client.post(
"/api/kernel/run",
headers=headers("new"),
json={
"cellIds": [first_cell_id(client, "new")],
"codes": ["x = 42"],
},
)
assert response.status_code == 200
receive_notification(ws, "completed-run")
with client.websocket_connect(url) as ws:
snapshot = socket_snapshot(ws)
receive_notification(ws, "reconnected")
assert (
next(
e["data"]["notebook"]["id"]
for e in snapshot
if e["event"] == "notebook"
)
== notebook_id
)
finally:
client.portal.call(bridge.close)