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.
from __future__ import annotations
import asyncio
import json
import os
import sys
import threading
from functools import partial
from typing import TYPE_CHECKING, Any
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from marimo._environments import backends
from marimo._environments.environment import Environment, ProcessPlan
from marimo._environments.sandbox import BackendAdapter
from marimo._messaging.notification import (
AlertNotification,
StartupProgressNotification,
)
from marimo._messaging.serde import serialize_kernel_message
from marimo._server.api.endpoints.ws.ws_connection_validator import (
ConnectionParams,
)
from marimo._server.host.session import SessionEventStream
from marimo._server.sse import format_close_event, format_sse_event
from marimo._session.managers.ipc import KernelStartupError
from marimo._session.model import ConnectionState, SessionMode
from marimo._types.ids import SessionId
from tests._server.api.endpoints.ws_helpers import (
QUERY_PARAMS_CASES,
assert_kernel_ready_response,
create_response,
)
from tests._server.mocks import get_session_manager
if TYPE_CHECKING:
from pathlib import Path
from typing import Self
from starlette.applications import Starlette
from starlette.testclient import TestClient
SSE_QUERY = "session_id=123&access_token=fake-token"
OTHER_SSE_QUERY = "session_id=456&access_token=fake-token"
class SSETestConnection:
"""Drives a `GET /sse` request against the raw ASGI app.
The TestClient buffers entire response bodies, which never works for an
unbounded SSE stream; this speaks ASGI directly so tests can read
events incrementally and disconnect at any time.
"""
def __init__(
self,
app: Starlette,
query: str,
headers: dict[str, str] | None = None,
) -> None:
self._app = app
self._scope = {
"type": "http",
"asgi": {"version": "3.0"},
"http_version": "1.1",
"method": "GET",
"scheme": "http",
"path": "/sse",
"raw_path": b"/sse",
"query_string": query.encode(),
"root_path": "",
# ASGI header names must be lowercase bytes
"headers": [
(b"host", b"testserver"),
*(
(k.lower().encode(), v.encode())
for k, v in (headers or {}).items()
),
],
"client": ("testclient", 50000),
"server": ("testserver", 80),
}
self._receive_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
self._events: asyncio.Queue[dict[str, str]] = asyncio.Queue()
self._buffer = ""
self._task: asyncio.Task[None] | None = None
self.status: int | None = None
self.headers: dict[str, str] = {}
async def __aenter__(self) -> Self:
self._task = asyncio.create_task(
self._app(self._scope, self._receive, self._send)
)
return self
async def __aexit__(self, *args: object) -> None:
self.disconnect()
assert self._task is not None
await asyncio.wait_for(self._task, timeout=10)
def disconnect(self) -> None:
self._receive_queue.put_nowait({"type": "http.disconnect"})
async def next_event(self, timeout: float = 10) -> dict[str, str]:
"""The next SSE record: {"event": ..., "data": ...} or a comment."""
return await asyncio.wait_for(self._events.get(), timeout)
async def next_notification(self) -> dict[str, str]:
"""Skip host model events when asserting session lifecycle notifications."""
while True:
record = await self.next_event()
if record["event"] in ("close", "comment"):
return record
if record["event"] == "marimo":
notification = json.loads(record["data"])["marimo"]
return {
"event": "message",
"data": json.dumps(
{"op": notification["op"], "data": notification}
),
}
def has_pending_events(self) -> bool:
return not self._events.empty()
def stream_ended(self) -> bool:
assert self._task is not None
return self._task.done()
async def _receive(self) -> dict[str, Any]:
return await self._receive_queue.get()
async def _send(self, message: dict[str, Any]) -> None:
if message["type"] == "http.response.start":
self.status = message["status"]
self.headers = {
k.decode(): v.decode() for k, v in message.get("headers", [])
}
elif message["type"] == "http.response.body":
self._buffer += message.get("body", b"").decode()
while "\n\n" in self._buffer:
record, self._buffer = self._buffer.split("\n\n", 1)
self._events.put_nowait(_parse_record(record))
def _parse_record(record: str) -> dict[str, str]:
event = "message"
event_id = None
data_lines: list[str] = []
comments: list[str] = []
for line in record.split("\n"):
if line.startswith(":"):
comments.append(line[1:].strip())
elif line.startswith("id:"):
event_id = line[len("id:") :].strip()
elif line.startswith("event:"):
event = line[len("event:") :].strip()
elif line.startswith("data:"):
data_lines.append(line[len("data:") :].removeprefix(" "))
if comments and not data_lines:
return {"event": "comment", "data": "\n".join(comments)}
return {
"event": event,
"data": "\n".join(data_lines),
**({"id": event_id} if event_id is not None else {}),
}
def _connect(
client: TestClient,
query: str = SSE_QUERY,
headers: dict[str, str] | None = None,
) -> SSETestConnection:
return SSETestConnection(client.app, query, headers)
async def _expect_close(
connection: SSETestConnection, code: int, reason: str
) -> None:
event = await connection.next_notification()
assert event["event"] == "close"
assert json.loads(event["data"]) == {"code": code, "reason": reason}
async def test_sse_kernel_ready(client: TestClient) -> None:
async with _connect(client) as connection:
event = await connection.next_notification()
assert connection.status == 200
assert connection.headers["content-type"].startswith(
"text/event-stream"
)
assert event["event"] == "message"
message = json.loads(event["data"])
assert message["op"] == "kernel-ready"
assert_kernel_ready_response(message)
@pytest.mark.parametrize(("query", "expected"), QUERY_PARAMS_CASES)
async def test_sse_query_params(
client: TestClient, query: str, expected: dict[str, str | list[str]]
) -> None:
async with _connect(client, f"{SSE_QUERY}&{query}") as connection:
event = await connection.next_notification()
assert_kernel_ready_response(json.loads(event["data"]))
session = get_session_manager(client).get_session("123")
assert session is not None
assert session._kernel_manager.app_metadata.query_params == expected
async def test_sse_requires_session_id(client: TestClient) -> None:
async with _connect(client, "access_token=fake-token") as connection:
await _expect_close(connection, 1000, "MARIMO_NO_SESSION_ID")
async def test_sse_requires_authentication(client: TestClient) -> None:
async with _connect(client, "session_id=123") as connection:
await _expect_close(connection, 3000, "MARIMO_UNAUTHORIZED")
async def test_sse_authenticates_with_bearer_header(
client: TestClient,
) -> None:
# The frontend SSE transport sends auth in headers, not the URL
async with _connect(
client,
"session_id=123",
headers={"Authorization": "Bearer fake-token"},
) as connection:
event = await connection.next_notification()
assert json.loads(event["data"])["op"] == "kernel-ready"
async def test_sse_rejects_invalid_query_token(client: TestClient) -> None:
async with _connect(
client, "session_id=123&access_token=wrong-token"
) as connection:
await _expect_close(connection, 3000, "MARIMO_UNAUTHORIZED")
async def test_sse_rejects_invalid_bearer_token(client: TestClient) -> None:
async with _connect(
client,
"session_id=123",
headers={"Authorization": "Bearer wrong-token"},
) as connection:
await _expect_close(connection, 3000, "MARIMO_UNAUTHORIZED")
@pytest.mark.parametrize(
"authorization",
[
"Bearer", # no credentials
"Unknown fake-token", # unsupported scheme
"Basic !!!not-base64!!!",
"Basic dXNlcm5hbWUtb25seQ==", # no password ("username-only")
],
)
async def test_sse_rejects_malformed_authorization_header(
client: TestClient, authorization: str
) -> None:
async with _connect(
client,
"session_id=123",
headers={"Authorization": authorization},
) as connection:
await _expect_close(connection, 3000, "MARIMO_UNAUTHORIZED")
async def test_sse_unauthorized_has_no_side_effects(
client: TestClient,
) -> None:
"""A rejected request must not create a session or leak anything."""
session_manager = get_session_manager(client)
async with _connect(client, "session_id=123") as connection:
await _expect_close(connection, 3000, "MARIMO_UNAUTHORIZED")
assert session_manager.sessions == {}
# The stream ends after the close event; nothing else is sent
assert connection.stream_ended()
assert not connection.has_pending_events()
# Failed auth must not issue an authenticated session cookie
assert "set-cookie" not in connection.headers
async def test_sse_allows_unauthenticated_when_auth_disabled(
client: TestClient,
) -> None:
# Trusted environments (e.g. --no-token) disable marimo's own auth
client.app.state.enable_auth = False
async with _connect(client, "session_id=123") as connection:
event = await connection.next_notification()
assert json.loads(event["data"])["op"] == "kernel-ready"
async def test_sse_kiosk_not_allowed_in_run_mode(client: TestClient) -> None:
get_session_manager(client).mode = SessionMode.RUN
async with _connect(client, f"{SSE_QUERY}&kiosk=true") as connection:
await _expect_close(connection, 1008, "MARIMO_KIOSK_NOT_ALLOWED")
assert get_session_manager(client).sessions == {}
async def test_sse_hides_code_when_include_code_false(
client: TestClient,
) -> None:
session_manager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
session_manager.include_code = False
async with _connect(client) as connection:
event = await connection.next_notification()
message = json.loads(event["data"])
assert message["op"] == "kernel-ready"
assert message["data"]["last_executed_code"] == {} # hidden
async def test_sse_kernel_startup_error(client: TestClient) -> None:
with patch.object(
SessionEventStream,
"_connect_session",
side_effect=KernelStartupError("boom"),
):
async with _connect(client) as connection:
event = await connection.next_notification()
message = json.loads(event["data"])
assert message["op"] == "kernel-startup-error"
assert message["data"]["error"] == "boom"
await _expect_close(
connection, 1011, "MARIMO_KERNEL_STARTUP_ERROR"
)
@pytest.mark.parametrize("outcome", ["ready", "error", "disconnect"])
async def test_sandbox_progress_during_preparation(
client: TestClient,
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
outcome: str,
) -> None:
preparing = asyncio.Event()
release = asyncio.Event()
cleaned_up = asyncio.Event()
python = (
sys.executable
if outcome == "ready"
else str(tmp_path / "missing-python")
)
environment = Environment(python, sys.prefix, "unchanged")
async def prepare_environment(*_args: Any, **_kwargs: Any) -> Environment:
preparing.set()
try:
await release.wait()
return environment
finally:
cleaned_up.set()
# Control sandbox preparation while exercising real kernel startup.
# A missing interpreter triggers a launch failure after preparation succeeds.
adapter = MagicMock(spec=BackendAdapter)
adapter.name = backends.current_backend()
adapter.sync_async.side_effect = prepare_environment
adapter.launch.return_value = ProcessPlan(
(python, "-m", "marimo._ipc.launch_kernel"), os.environ.copy()
)
monkeypatch.setattr(backends, "adapter_for", lambda *_: adapter)
manager = get_session_manager(client)
manager.sandbox = True
if outcome == "disconnect":
manager.ttl_seconds = 0
async with _connect(client) as connection:
event = await connection.next_notification()
assert json.loads(event["data"]) == {
"op": "startup-progress",
"data": {
"op": "startup-progress",
"phase": "preparing-environment",
"logs": "",
"log_mode": "replace",
},
}
running = json.loads((await connection.next_notification())["data"])
assert running["op"] == "environment-operation"
assert running["data"]["action"] == "prepare"
assert running["data"]["status"] == {"kind": "running"}
assert not manager.sessions
await asyncio.wait_for(preparing.wait(), timeout=5)
if outcome == "disconnect":
connection.disconnect()
await asyncio.wait_for(cleaned_up.wait(), timeout=5)
else:
release.set()
completed = json.loads(
(await connection.next_notification())["data"]
)
assert (
completed["data"]["operation_id"]
== running["data"]["operation_id"]
)
assert completed["data"]["status"] == {"kind": "succeeded"}
event = await connection.next_notification()
assert json.loads(event["data"]) == {
"op": "startup-progress",
"data": {
"op": "startup-progress",
"phase": "starting-kernel",
"logs": "",
"log_mode": "replace",
},
}
event = await connection.next_notification()
message = json.loads(event["data"])
if outcome == "ready":
assert_kernel_ready_response(message)
else:
assert message["op"] == "kernel-startup-error"
assert (
"Failed to start kernel subprocess"
in message["data"]["error"]
)
await _expect_close(
connection, 1011, "MARIMO_KERNEL_STARTUP_ERROR"
)
if outcome != "ready":
assert not manager.sessions
async def test_sse_kiosk_without_session(client: TestClient) -> None:
async with _connect(client, f"{SSE_QUERY}&kiosk=true") as connection:
await _expect_close(connection, 1000, "MARIMO_NO_SESSION")
async def test_sse_disconnect_and_reconnect(client: TestClient) -> None:
async with _connect(client) as connection:
event = await connection.next_notification()
assert json.loads(event["data"])["op"] == "kernel-ready"
# Reconnect with the same session id
async with _connect(client) as connection:
event = await connection.next_notification()
assert json.loads(event["data"])["op"] == "reconnected"
event = await connection.next_notification()
assert json.loads(event["data"])["op"] == "alert"
async def test_sse_second_connection_joins_as_viewer(
client: TestClient,
) -> None:
async with _connect(client) as connection:
event = await connection.next_notification()
assert json.loads(event["data"])["op"] == "kernel-ready"
async with _connect(client, OTHER_SSE_QUERY) as viewer:
event = await viewer.next_notification()
message = json.loads(event["data"])
assert message["op"] == "kernel-ready"
assert_kernel_ready_response(
message, create_response({"kiosk": True, "resumed": True})
)
async def test_sse_heartbeat(client: TestClient) -> None:
with_heartbeat = partial(SessionEventStream, heartbeat_seconds=0.01)
with patch(
"marimo._server.api.endpoints.ws_endpoint.SessionEventStream",
with_heartbeat,
):
async with _connect(client) as connection:
while True:
event = await connection.next_notification()
if event["event"] != "comment":
break
assert json.loads(event["data"])["op"] == "kernel-ready"
# Drain until the first heartbeat comment arrives
for _ in range(20):
event = await connection.next_notification()
if event["event"] == "comment":
break
assert event == {"event": "comment", "data": "keep-alive"}
# Unit tests for the stream generator
def _make_handler(
request: MagicMock, *, mode: SessionMode = SessionMode.RUN
) -> SessionEventStream:
params = ConnectionParams(
session_id=SessionId("s1"),
file_key="test.py",
kiosk=False,
auto_instantiate=False,
)
handler = SessionEventStream(
connection=request,
notebook=None,
bridge=MagicMock(),
types=None,
cursor=None,
manager=MagicMock(mode=mode),
params=params,
heartbeat_seconds=60,
)
handler.status = ConnectionState.OPEN
# Bypass SessionConnector; unit tests drive the handler directly
session = MagicMock()
session.room.main_consumer = handler
session.ttl_seconds = 120
session.disconnect_consumer.side_effect = lambda consumer: (
consumer.on_detach()
)
handler.manager.get_session.return_value = session
async def connect(_request: Any) -> None:
handler.on_attach(session, MagicMock())
handler._connect_session = AsyncMock( # type: ignore[method-assign]
side_effect=connect
)
return handler
def _never_receive() -> Any:
async def receive() -> dict[str, Any]:
await asyncio.Event().wait()
raise AssertionError("unreachable")
return receive
async def test_stream_sends_messages_and_close_event() -> None:
request = MagicMock()
request._receive = _never_receive()
handler = _make_handler(request)
stream = handler.sse()
handler.notify(
serialize_kernel_message(
AlertNotification(title="hello", description="world")
)
)
first = await asyncio.wait_for(stream.__anext__(), timeout=10)
assert first.startswith("event: marimo\n")
assert json.loads(_parse_record(first)["data"])["marimo"]["op"] == "alert"
# Detaching from the session requests a SHUTDOWN close
handler.on_detach()
second = await asyncio.wait_for(stream.__anext__(), timeout=10)
assert second == format_close_event(1000, "MARIMO_SHUTDOWN")
with pytest.raises(StopAsyncIteration):
await asyncio.wait_for(stream.__anext__(), timeout=10)
assert not handler._is_transport_connected()
async def test_stream_does_not_connect_until_iterated() -> None:
"""A response body that is never consumed must not attach a consumer."""
request = MagicMock()
request._receive = _never_receive()
handler = _make_handler(request)
stream = handler.sse()
await asyncio.sleep(0)
handler._connect_session.assert_not_called()
await stream.aclose()
handler._connect_session.assert_not_called()
async def test_disconnect_during_startup_progress_detaches_session() -> None:
request = MagicMock()
request._receive = _never_receive()
handler = _make_handler(request)
session = handler.manager.get_session.return_value
handler.notify(
serialize_kernel_message(
StartupProgressNotification(
phase="starting-kernel", logs="", log_mode="replace"
)
)
)
stream = handler.sse()
assert "startup-progress" in await anext(stream)
await asyncio.sleep(0) # Complete attachment while the yield is suspended.
await stream.aclose()
session.disconnect_consumer.assert_called_once_with(handler)
assert handler.connection_state() == ConnectionState.CLOSED
assert not handler._is_transport_connected()
async def test_stream_flushes_pending_messages_before_close() -> None:
"""Messages enqueued before a server close are sent, then the close."""
request = MagicMock()
request._receive = _never_receive()
handler = _make_handler(request)
handler.notify(
serialize_kernel_message(
AlertNotification(title="one", description="")
)
)
handler.notify(
serialize_kernel_message(
AlertNotification(title="two", description="")
)
)
handler.on_detach()
events = [event async for event in handler.sse()]
assert len(events) == 3
assert (
json.loads(_parse_record(events[0])["data"])["marimo"]["title"]
== "one"
)
assert (
json.loads(_parse_record(events[1])["data"])["marimo"]["title"]
== "two"
)
assert events[2] == format_close_event(1000, "MARIMO_SHUTDOWN")
async def test_stream_ends_on_client_disconnect() -> None:
request = MagicMock()
async def receive() -> dict[str, Any]:
return {"type": "http.disconnect"}
request._receive = receive
handler = _make_handler(request, mode=SessionMode.EDIT)
handler.manager.get_session.return_value = None
handler.manager.ttl_seconds = None
events = [event async for event in handler.sse()]
assert events == []
assert handler.connection_state() == ConnectionState.CLOSED
async def test_check_status_update_runs_off_the_event_loop(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""The synchronous update check must not block kernel messages."""
from marimo._config.settings import GLOBAL_SETTINGS
from marimo._server.api.endpoints.ws import session_handler
monkeypatch.setattr(GLOBAL_SETTINGS, "CHECK_STATUS_UPDATE", True)
monkeypatch.setattr(session_handler, "has_toasted", False)
started = threading.Event()
release = threading.Event()
def slow_check(on_update: Any) -> None:
started.set()
assert release.wait(timeout=10)
on_update("0.0.1", MagicMock(latest_version="9.9.9", notices=[]))
monkeypatch.setattr(session_handler, "check_for_updates", slow_check)
handler = _make_handler(MagicMock(), mode=SessionMode.EDIT)
# Returns immediately, while the check is still running on a thread
handler._check_status_update()
assert await asyncio.wait_for(asyncio.to_thread(started.wait, 10), 20)
assert handler._events.empty()
# Once the check completes, the alert is delivered onto the queue
release.set()
message = await asyncio.wait_for(handler._events.get(), timeout=10)
assert "Update available" in message.event.data.marimo.title
async def test_stream_heartbeat_without_messages() -> None:
request = MagicMock()
request._receive = _never_receive()
handler = _make_handler(request)
handler.heartbeat_seconds = 0.01
stream = handler.sse()
first = await asyncio.wait_for(stream.__anext__(), timeout=10)
assert first == ": keep-alive\n\n"
handler._request_close(1000, "MARIMO_SHUTDOWN")
async for _ in stream:
pass
# Unit tests for SSE framing
def test_format_sse_event() -> None:
assert format_sse_event('{"op": "alert"}') == 'data: {"op": "alert"}\n\n'
assert (
format_sse_event('{"code": 1}', event="close")
== 'event: close\ndata: {"code": 1}\n\n'
)
# Multi-line payloads become one data line each
assert format_sse_event("a\nb") == "data: a\ndata: b\n\n"
def test_format_close_event() -> None:
assert format_close_event(1000, "MARIMO_SHUTDOWN") == (
'event: close\ndata: {"code": 1000, "reason": "MARIMO_SHUTDOWN"}\n\n'
)
@pytest.mark.parametrize("mode", [SessionMode.EDIT, SessionMode.RUN])
async def test_sse_host_snapshot_and_cursor_replay(
client: TestClient, mode: SessionMode
) -> None:
manager = get_session_manager(client)
manager.mode = mode
manager.include_code = False
query = SSE_QUERY + "&types=notebook,cell,custom,marimo"
async with _connect(client, query) as connection:
snapshot = []
while True:
record = await connection.next_event()
snapshot.append(record)
if record["event"] == "ready":
cursor = record["id"]
break
cells = [
json.loads(r["data"])["cell"]
for r in snapshot
if r["event"] == "cell"
]
assert cells
assert cells[0]["code"] == (
None if mode == SessionMode.RUN else "import marimo as mo"
)
# Finish the session handshake before disconnecting.
await connection.next_notification()
context = client.app.state.host_context
session = manager.get_session(SessionId("123"))
assert session is not None
notebook = context.bridge.notebook_for_session(session)
assert notebook is not None
notebook.emit("test.missed", {"value": 1})
async with _connect(
client, query, {"Last-Event-ID": cursor}
) as connection:
first = await connection.next_event()
assert first["event"] == "custom"
assert json.loads(first["data"])["custom"]["data"] == {"value": 1}
assert (await connection.next_event())["event"] == "ready"
async with _connect(client, query + "&cursor=stale") as connection:
assert (await connection.next_event())["event"] == "reset"
assert (await connection.next_event())["event"] == "notebook"
@pytest.mark.parametrize(
"options", ["cursor=", "types=invalid", "run_id=unknown"]
)
async def test_sse_rejects_invalid_subscription_before_startup(
client: TestClient, options: str
) -> None:
async with _connect(client, SSE_QUERY + "&" + options) as connection:
record = await connection.next_event()
assert record["event"] == "close"
assert json.loads(record["data"])["code"] == 1008
assert not get_session_manager(client).sessions