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 inspect
import json
import os
import sys
import tempfile
import textwrap
from pathlib import Path
from typing import TYPE_CHECKING
from urllib.parse import urlencode
import pytest
from marimo._core.protocol import ProjectMessage
from marimo._server.models.home import MarimoFile
from marimo._server.workspace import (
DirectoryWorkspace,
EmptyWorkspace,
FixedFilesWorkspace,
SingleFileWorkspace,
)
from marimo._session.model import SessionMode
from marimo._utils.marimo_path import MarimoPath
from tests._server.api.endpoints.test_sse import SSETestConnection
from tests._server.host.drive import socket_snapshot
from tests._server.host.test_editor_websocket import receive_notification
from tests._server.mocks import get_session_manager, token_header, with_session
if TYPE_CHECKING:
from starlette.testclient import TestClient
SESSION_ID = "session-123"
HEADERS = {
"Marimo-Session-Id": SESSION_ID,
**token_header("fake-token"),
}
@with_session(SESSION_ID)
def test_workspace_files(client: TestClient) -> None:
current_filename = get_session_manager(
client
).workspace.get_unique_file_key()
assert current_filename
response = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body = response.json()
files = body["files"]
assert len(files) == 1
assert files[0]["path"] == current_filename
# Check that new fields are present
assert "hasMore" in body
assert "fileCount" in body
assert body["hasMore"] is False
assert body["fileCount"] == 1
@with_session(SESSION_ID)
def test_workspace_files_no_files(client: TestClient) -> None:
response = client.post(
"/api/home/recent_files",
headers=HEADERS,
)
body = response.json()
files = body["files"]
assert files is not None
@with_session(SESSION_ID)
def test_running_notebooks(client: TestClient) -> None:
current_filename = get_session_manager(
client
).workspace.get_unique_file_key()
assert current_filename
response = client.post(
"/api/home/running_notebooks",
headers=HEADERS,
)
body = response.json()
files = body["files"]
assert len(files) == 1
assert files[0]["path"] == current_filename
# TODO: Debug on Windows
@pytest.mark.skipif(sys.platform == "win32", reason="Failing on Windows CI")
@with_session(SESSION_ID, auto_shutdown=False)
def test_shutdown_session(client: TestClient) -> None:
response = client.post(
"/api/home/shutdown_session",
headers=HEADERS,
json={"sessionId": SESSION_ID},
)
assert response.status_code == 200
assert response.json() == {"files": []}
assert get_session_manager(client).get_session(SESSION_ID) is None
@with_session(SESSION_ID)
def test_open_tutorial(client: TestClient) -> None:
response = client.post(
"/api/home/tutorial/open",
headers=HEADERS,
json={"tutorialId": "intro"},
)
assert response.status_code == 200
data = response.json()
assert data["name"] == "intro.py"
assert data["path"].endswith("intro.py")
@with_session(SESSION_ID)
def test_cant_open_non_tutorial(client: TestClient) -> None:
response = client.post(
"/api/home/tutorial/open",
headers=HEADERS,
json={"tutorialId": "non-tutorial"},
)
assert response.status_code == 400
assert response.json() == {"detail": "Tutorial not found"}
@with_session(SESSION_ID)
def test_workspace_files_in_run_mode(client: TestClient) -> None:
session_manager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
with tempfile.TemporaryDirectory() as temp_dir:
marker = Path(temp_dir) / "marker.txt"
marimo_file = Path(temp_dir) / "notebook.py"
marimo_file.write_text(
f"""# /// script
# [tool.marimo.opengraph]
# title = "Static Title"
# generator = "generate_opengraph"
# ///
import marimo
app = marimo.App()
with app.setup:
open({str(marker)!r}, "w").write("executed")
def generate_opengraph(context, parent):
return {{"title": "Dynamic Title"}}
""",
encoding="utf-8",
)
non_marimo_file = Path(temp_dir) / "text.txt"
non_marimo_file.write_text("This is not a marimo file")
session_manager.workspace = DirectoryWorkspace(
temp_dir, include_markdown=False
)
response = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body = response.json()
files = body["files"]
assert len(files) == 1
assert body["root"] == temp_dir
assert files[0]["path"] == marimo_file.name
assert files[0]["opengraph"]["title"] == "Static Title"
assert not marker.exists()
@with_session(SESSION_ID)
def test_workspace_files_run_mode_watch_directory_refreshes_add_remove(
client: TestClient,
) -> None:
session_manager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
session_manager.watch = True
with tempfile.TemporaryDirectory() as temp_dir:
file_one = Path(temp_dir) / "one.py"
file_one.write_text("import marimo\napp = marimo.App()")
session_manager.workspace = DirectoryWorkspace(
temp_dir, include_markdown=False
)
response_initial = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body_initial = response_initial.json()
assert response_initial.status_code == 200
assert body_initial["root"] == temp_dir
assert {file["path"] for file in body_initial["files"]} == {
file_one.name
}
file_two = Path(temp_dir) / "two.py"
file_two.write_text("import marimo\napp = marimo.App()")
response_after_add = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body_after_add = response_after_add.json()
assert response_after_add.status_code == 200
assert {file["path"] for file in body_after_add["files"]} == {
file_one.name,
file_two.name,
}
file_one.unlink()
response_after_remove = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body_after_remove = response_after_remove.json()
assert response_after_remove.status_code == 200
assert {file["path"] for file in body_after_remove["files"]} == {
file_two.name
}
@with_session(SESSION_ID)
def test_workspace_files_empty_directory(client: TestClient) -> None:
session_manager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
with tempfile.TemporaryDirectory() as temp_dir:
session_manager.workspace = DirectoryWorkspace(
temp_dir, include_markdown=False
)
response = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body = response.json()
files = body["files"]
assert len(files) == 0
@with_session(SESSION_ID)
def test_workspace_files_run_mode_allowlist(client: TestClient) -> None:
session_manager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
with tempfile.TemporaryDirectory() as temp_dir:
file_one = Path(temp_dir) / "one.py"
file_one.write_text("import marimo\napp = marimo.App()")
file_two = Path(temp_dir) / "two.py"
file_two.write_text("import marimo\napp = marimo.App()")
marimo_files = [
MarimoFile(
name=file_one.name,
path=str(file_one),
last_modified=file_one.stat().st_mtime,
),
MarimoFile(
name=file_two.name,
path=str(file_two),
last_modified=file_two.stat().st_mtime,
),
]
session_manager.workspace = FixedFilesWorkspace(
marimo_files, directory=temp_dir
)
response = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body = response.json()
files = body["files"]
assert body["root"] == temp_dir
assert {file["path"] for file in files} == {
str(file_one),
str(file_two),
}
@with_session(SESSION_ID)
def test_workspace_files_run_mode_allowlist_skips_deleted_file(
client: TestClient,
) -> None:
session_manager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
with tempfile.TemporaryDirectory() as temp_dir:
file_one = Path(temp_dir) / "one.py"
file_one.write_text("import marimo\napp = marimo.App()")
file_two = Path(temp_dir) / "two.py"
file_two.write_text("import marimo\napp = marimo.App()")
marimo_files = [
MarimoFile(
name=file_one.name,
path=str(file_one),
last_modified=file_one.stat().st_mtime,
),
MarimoFile(
name=file_two.name,
path=str(file_two),
last_modified=file_two.stat().st_mtime,
),
]
session_manager.workspace = FixedFilesWorkspace(
marimo_files, directory=temp_dir
)
file_two.unlink()
response = client.post(
"/api/home/workspace_files",
headers=HEADERS,
json={"include_markdown": False},
)
body = response.json()
files = body["files"]
assert response.status_code == 200
assert body["root"] == temp_dir
assert body["fileCount"] == 1
assert body["hasMore"] is False
assert [file["path"] for file in files] == [str(file_one)]
@with_session(SESSION_ID)
def test_thumbnail_redirects_for_https_opengraph_image(
client: TestClient,
) -> None:
session_manager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
with tempfile.TemporaryDirectory() as temp_dir:
marimo_file = Path(temp_dir) / "notebook.py"
marimo_file.write_text(
textwrap.dedent(
"""
# /// script
# [tool.marimo.opengraph]
# image = "https://example.com/opengraph.png"
# ///
import marimo
app = marimo.App()
"""
).lstrip()
)
session_manager.workspace = DirectoryWorkspace(
temp_dir, include_markdown=False
)
response = client.get(
"/og/thumbnail?file=notebook.py",
headers=HEADERS,
follow_redirects=False,
)
assert response.status_code == 307
assert (
response.headers["location"] == "https://example.com/opengraph.png"
)
@with_session(SESSION_ID)
def test_tutorial_file_accessible_after_open(client: TestClient) -> None:
"""Test that a tutorial file can be accessed after being opened.
This is an integration test for issue #7424.
When a tutorial is opened via the endpoint, it creates a file in a temp
directory. This test verifies that the workspace can access that
file despite it being outside the base directory.
"""
# Open a tutorial
response = client.post(
"/api/home/tutorial/open",
headers=HEADERS,
json={"tutorialId": "intro"},
)
assert response.status_code == 200
data = response.json()
tutorial_path = data["path"]
# Verify the temp directory was registered with the workspace
session_manager = get_session_manager(client)
workspace = session_manager.workspace
# Only test for directory-based workspaces
if isinstance(workspace, DirectoryWorkspace):
assert workspace.is_in_allowed_temp_dir(tutorial_path)
# Try to get a file manager for the tutorial file
# This should not raise an HTTPException about being outside the directory
file_manager = session_manager.app_manager(tutorial_path)
assert file_manager is not None
assert file_manager.path == tutorial_path
@with_session(SESSION_ID)
def test_running_notebooks_returns_relative_paths(client: TestClient) -> None:
"""Test that running_notebooks returns paths relative to workspace directory.
This is a regression test for the bug where `marimo edit subdirectory`
would return paths like `subdirectory/notebook.py` instead of `notebook.py`.
"""
session_manager = get_session_manager(client)
# Create a temp directory structure: /tmp/xxx/subdir/notebook.py
with tempfile.TemporaryDirectory() as tmp_base:
subdir = os.path.join(tmp_base, "subdir")
os.makedirs(subdir)
# Create a notebook file in the subdirectory
notebook_path = os.path.join(subdir, "notebook.py")
content = inspect.cleandoc(
"""
import marimo
app = marimo.App()
@app.cell
def __():
return
if __name__ == "__main__":
app.run()
"""
)
with open(notebook_path, "w") as f:
f.write(content)
# Create a workspace pointing to the subdirectory
# This simulates `marimo edit subdir`
workspace = DirectoryWorkspace(subdir, include_markdown=False)
# Replace the session manager's workspace
original_workspace = session_manager.workspace
session_manager.workspace = workspace
# Update the session's filename to the absolute path of the notebook
session = session_manager.get_session(SESSION_ID)
assert session is not None
original_filename = session.app_file_manager.filename
session.app_file_manager.filename = notebook_path
try:
response = client.post(
"/api/home/running_notebooks",
headers=HEADERS,
)
body = response.json()
files = body["files"]
assert len(files) == 1
# The path should be relative to the subdirectory, not the CWD
# i.e., "notebook.py" not "subdir/notebook.py"
assert files[0]["path"] == "notebook.py"
assert files[0]["name"] == "notebook.py"
finally:
# Restore original state
session_manager.workspace = original_workspace
session.app_file_manager.filename = original_filename
@pytest.mark.skipif(sys.platform == "win32", reason="Failing on Windows CI")
@with_session(SESSION_ID, auto_shutdown=False)
def test_shutdown_session_returns_relative_paths(client: TestClient) -> None:
"""Test that shutdown_session returns paths relative to workspace directory."""
session_manager = get_session_manager(client)
# Create a second session to test shutdown returns correct paths
# for remaining sessions
with tempfile.TemporaryDirectory() as tmp_base:
subdir = os.path.join(tmp_base, "subdir")
os.makedirs(subdir)
notebook_path = os.path.join(subdir, "notebook.py")
content = inspect.cleandoc(
"""
import marimo
app = marimo.App()
@app.cell
def __():
return
if __name__ == "__main__":
app.run()
"""
)
with open(notebook_path, "w") as f:
f.write(content)
workspace = DirectoryWorkspace(subdir, include_markdown=False)
original_workspace = session_manager.workspace
session_manager.workspace = workspace
session = session_manager.get_session(SESSION_ID)
assert session is not None
original_filename = session.app_file_manager.filename
session.app_file_manager.filename = notebook_path
try:
# Shutdown the session - response should have empty files
# since we're shutting down the only session
response = client.post(
"/api/home/shutdown_session",
headers=HEADERS,
json={"sessionId": SESSION_ID},
)
assert response.status_code == 200
# After shutdown, no sessions remain
assert response.json() == {"files": []}
finally:
session_manager.workspace = original_workspace
# Note: session is already shut down, so we don't restore filename
@pytest.mark.xfail(
sys.platform == "win32",
reason="Flaky on Windows - websocket cleanup may hang due to background threads. See #7774",
strict=False,
)
def test_running_notebooks_handles_files_outside_directory(
client: TestClient,
) -> None:
"""Test that files outside the directory still get pretty_path treatment."""
session_manager = get_session_manager(client)
auth_token = session_manager.auth_token
headers = token_header(auth_token)
# Connect a session
with client.websocket_connect(
f"/ws?session_id={SESSION_ID}", headers=headers
) as websocket:
data = websocket.receive_text()
assert data
# Create two separate temp directories
with tempfile.TemporaryDirectory() as router_dir:
with tempfile.TemporaryDirectory() as file_dir:
# Create a notebook in file_dir (outside router_dir)
notebook_path = os.path.join(file_dir, "outside.py")
content = inspect.cleandoc(
"""
import marimo
app = marimo.App()
@app.cell
def __():
return
if __name__ == "__main__":
app.run()
"""
)
with open(notebook_path, "w") as f:
f.write(content)
# Set up workspace pointing to router_dir
workspace = DirectoryWorkspace(
router_dir, include_markdown=False
)
original_workspace = session_manager.workspace
session_manager.workspace = workspace
session = session_manager.get_session(SESSION_ID)
assert session is not None
original_filename = session.app_file_manager.filename
session.app_file_manager.filename = notebook_path
try:
response = client.post(
"/api/home/running_notebooks",
headers=HEADERS,
)
body = response.json()
files = body["files"]
assert len(files) == 1
# File is outside directory, so it should use pretty_path
# which returns the path as-is or relative to CWD
# The important thing is it doesn't crash
assert files[0]["name"] == "outside.py"
# Path should contain the filename (exact path depends on CWD)
assert "outside.py" in files[0]["path"]
finally:
session_manager.workspace = original_workspace
session.app_file_manager.filename = original_filename
@pytest.mark.parametrize("transport", ["ws", "sse"])
@pytest.mark.parametrize("source", ["tutorial", "single-file", "empty"])
def test_open_notebook_connects_and_reconnects_to_host(
client: TestClient, tmp_path: Path, transport: str, source: str
) -> None:
manager = get_session_manager(client)
root = tmp_path / "workspace"
root.mkdir()
if source == "tutorial":
manager.workspace = DirectoryWorkspace(
str(root), include_markdown=False
)
else:
path = str(tmp_path / "opened.py")
Path(path).write_text("import marimo\napp = marimo.App()\n")
if source == "empty":
manager.workspace = EmptyWorkspace()
else:
original = root / "original.py"
original.write_text("import marimo\napp = marimo.App()\n")
manager.workspace = SingleFileWorkspace.from_path(
MarimoPath(str(original))
)
with client:
if source == "tutorial":
response = client.post(
"/api/home/tutorial/open",
headers=HEADERS,
json={"tutorialId": "intro"},
)
assert response.status_code == 200, response.text
path = response.json()["path"]
query = urlencode(
{
"session_id": SESSION_ID,
"file": path,
"access_token": "fake-token",
}
)
notebook = None
for notification in ("kernel-ready", "reconnected"):
if transport == "ws":
with client.websocket_connect(f"/ws?{query}") as socket:
snapshot = socket_snapshot(socket)
ready = receive_notification(socket, notification)
else:
async def read_sse():
async with SSETestConnection(
client.app, query
) as connection:
snapshot = []
while True:
event = await connection.next_event()
snapshot.append(
{
"event": event["event"],
"data": json.loads(event["data"]),
}
)
if event["event"] == "ready":
break
ready = json.loads(
(await connection.next_notification())["data"]
)["data"]
return snapshot, ready
assert client.portal is not None
snapshot, ready = client.portal.call(read_sse)
bridge = client.app.state.host_context.bridge
record = bridge.index.notebook_for(path)
assert record is not None
if notebook is None:
notebook = record
assert record == notebook
[project] = [
e.event.data.project
for e in bridge.host.events()
if isinstance(e.event.data, ProjectMessage)
and e.event.data.project.id == record.project_id
]
assert (project.name, project.root, record.path) == (
"Open notebooks",
None,
None,
)
assert snapshot[0]["data"]["notebook"]["id"] == record.id
assert ready["op"] == notification
if notification == "kernel-ready":
assert ready["consumer_capabilities"]["edit"] is True
if source == "tutorial":
assert any(
e["event"] == "cell" and e["data"]["cell"]["code"]
for e in snapshot
)
assert client.portal is not None
client.portal.call(bridge.index.refresh_async)