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 json
import logging
import os
import signal
import sys
import tempfile
from pathlib import Path
from typing import TYPE_CHECKING
from unittest.mock import Mock, call, patch
import pytest
from starlette.websockets import WebSocketDisconnect
from marimo._server.api.endpoints.terminal import (
LOGGER,
_create_process_cleanup_handler,
_create_shell_environment,
_decode_pty_data,
_manage_command_buffer,
_resize_pty,
_setup_child_process,
_should_close_on_command,
)
from marimo._server.session_manager import SessionManager
from marimo._session.model import SessionMode
from tests._server.mocks import get_session_manager
TERMINAL_WS_URL = "/terminal/ws?access_token=fake-token"
if TYPE_CHECKING:
from starlette.testclient import TestClient
is_windows = sys.platform == "win32"
is_mac = sys.platform == "darwin"
@pytest.mark.skipif(is_windows, reason="Skip on Windows")
@pytest.mark.skipif(
is_mac,
reason=(
"pty.fork() is unsafe on macOS when mixed with higher-level system "
"APIs and segfaults intermittently under the multi-threaded test "
"client; see https://docs.python.org/3/library/pty.html"
),
)
def test_terminal_ws(client: TestClient) -> None:
with client.websocket_connect(TERMINAL_WS_URL) as websocket:
# Send echo message
websocket.send_text("echo hello")
data = websocket.receive_text()
assert "echo hello" in data
@pytest.mark.skipif(
is_windows or is_mac, reason="PTY integration requires Linux"
)
@pytest.mark.timeout(10)
@pytest.mark.parametrize(
("query", "expected_size"),
[
("&rows=30&cols=140", (30, 140)),
("", (24, 80)),
("&rows=0&cols=140", (24, 80)),
("&rows=30&cols=-1", (24, 80)),
("&rows=invalid&cols=140", (24, 80)),
("&rows=30&cols=65536", (24, 80)),
],
)
def test_terminal_ws_initial_size(
client: TestClient,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
query: str,
expected_size: tuple[int, int],
) -> None:
shell = tmp_path / "shell"
shell.write_text(
"#!/bin/sh\nstty size\nwhile read -r line; do stty size; done\n"
)
shell.chmod(0o755)
monkeypatch.setenv("SHELL", str(shell))
with client.websocket_connect(TERMINAL_WS_URL + query) as websocket:
# No resize message is sent until the shell has reported its size.
data = ""
while "\n" not in data:
data += websocket.receive_text()
assert tuple(map(int, data.split())) == expected_size
websocket.send_text(
json.dumps({"type": "resize", "rows": 40, "cols": 160})
)
websocket.send_text("\n")
data = ""
while "40 160" not in data:
data += websocket.receive_text()
assert data.strip() == "40 160"
@pytest.mark.skipif(
is_windows or is_mac, reason="PTY integration requires Linux"
)
@pytest.mark.timeout(10)
@pytest.mark.parametrize("log_level", [logging.WARNING, logging.DEBUG])
def test_terminal_ws_long_prompt(
client: TestClient,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
caplog: pytest.LogCaptureFixture,
log_level: int,
) -> None:
caplog.set_level(log_level, logger=LOGGER.name)
# Use the real stderr so the inherited handler writes to the PTY slave.
monkeypatch.setattr(
LOGGER, "handlers", [logging.StreamHandler(sys.__stderr__)]
)
shell = tmp_path / "shell"
shell.write_text("#!/bin/sh\nexec /bin/bash --noprofile --norc -i\n")
shell.chmod(0o755)
monkeypatch.setenv("SHELL", str(shell))
prompt = (
"henkan@session-gbm-henkan-notebook-m-6b3c03b8238e-56ddd64d76-5p27b"
":~/notebooks$ "
)
monkeypatch.setenv("PS1", prompt)
monkeypatch.setenv("LC_ALL", "C")
monkeypatch.delenv("PROMPT_COMMAND", raising=False)
with client.websocket_connect(
TERMINAL_WS_URL + "&rows=30&cols=140"
) as websocket:
data = ""
while "$ " not in data:
data += websocket.receive_text()
# Type before sending any resize message, as on a slow connection.
websocket.send_text("ls")
while not data.endswith("ls"):
data += websocket.receive_text()
# A wrong initial width makes Bash emit a carriage return after the
# prompt, placing typed characters over its first letters.
assert data.replace("\x1b[?2004h", "") == prompt + "ls"
def test_terminal_ws_not_allowed_in_run(client: TestClient) -> None:
session_manager: SessionManager = get_session_manager(client)
session_manager.mode = SessionMode.RUN
with pytest.raises(WebSocketDisconnect):
with client.websocket_connect(TERMINAL_WS_URL) as websocket:
websocket.send_text("echo hello")
session_manager.mode = SessionMode.EDIT
def test_terminal_ws_unauthorized(client: TestClient) -> None:
"""Test terminal websocket rejects unauthenticated connections."""
with pytest.raises(WebSocketDisconnect) as exc_info:
with client.websocket_connect("/terminal/ws"):
pass
assert exc_info.value.code == 3000
def test_terminal_ws_wrong_token(client: TestClient) -> None:
"""Test terminal websocket rejects wrong token."""
with pytest.raises(WebSocketDisconnect) as exc_info:
with client.websocket_connect("/terminal/ws?access_token=wrong-token"):
pass
assert exc_info.value.code == 3000
# Unit tests for terminal utility functions
@pytest.mark.skipif(is_windows, reason="Skip on Windows")
@pytest.mark.parametrize("log", [True, False])
def test_resize_pty_logging(log: bool) -> None:
import pty
master, slave = pty.openpty()
try:
with patch("marimo._server.api.endpoints.terminal.LOGGER") as logger:
_resize_pty(slave, 30, 140, log=log)
assert os.get_terminal_size(slave) == (140, 30)
assert logger.mock_calls == (
[call.debug("PTY resized to 140x30")] if log else []
)
finally:
os.close(master)
os.close(slave)
@pytest.mark.skipif(is_windows, reason="Skip on Windows")
@pytest.mark.parametrize("log", [True, False])
def test_resize_pty_failure_logging(log: bool) -> None:
with (
patch("fcntl.ioctl", side_effect=OSError("resize failed")),
patch("marimo._server.api.endpoints.terminal.LOGGER") as logger,
):
_resize_pty(0, 30, 140, log=log)
assert logger.mock_calls == (
[call.warning("Failed to resize PTY: resize failed")]
if log
else []
)
class TestCreateShellEnvironment:
def test_create_shell_environment_default_cwd(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Test shell environment creation with default working directory."""
monkeypatch.delenv("SHELL", raising=False)
shell, env = _create_shell_environment()
assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
assert env["TERM"] == "xterm-256color"
assert "LANG" in env
assert "LC_ALL" in env
def test_create_shell_environment_custom_cwd(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Test shell environment creation with custom working directory."""
monkeypatch.delenv("SHELL", raising=False)
with tempfile.TemporaryDirectory() as temp_dir:
shell, env = _create_shell_environment(cwd=temp_dir)
assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
assert env["TERM"] == "xterm-256color"
@patch("os.getcwd")
@patch("pathlib.Path.home")
def test_create_shell_environment_fallback_cwd(
self,
mock_home: Mock,
mock_getcwd: Mock,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Test shell environment creation when getcwd fails."""
monkeypatch.delenv("SHELL", raising=False)
mock_getcwd.side_effect = OSError("No such directory")
mock_home.return_value = Path("/home/user")
shell, env = _create_shell_environment()
assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
assert env["TERM"] == "xterm-256color"
@patch("os.getcwd")
@patch("pathlib.Path.home")
def test_create_shell_environment_ultimate_fallback(
self,
mock_home: Mock,
mock_getcwd: Mock,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Test shell environment creation when both getcwd and home fail."""
monkeypatch.delenv("SHELL", raising=False)
mock_getcwd.side_effect = OSError("No such directory")
mock_home.side_effect = Exception("No home directory")
shell, env = _create_shell_environment()
assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
assert env["TERM"] == "xterm-256color"
@patch("os.path.exists")
@patch.dict(os.environ, {"SHELL": "/nonexistent/shell"})
def test_create_shell_environment_shell_fallback(
self, mock_exists: Mock
) -> None:
"""Test shell selection fallback when default shell doesn't exist."""
# Mock that the default shell doesn't exist, but /bin/bash does
def exists_side_effect(path: str) -> bool:
return path == "/bin/bash"
mock_exists.side_effect = exists_side_effect
shell, env = _create_shell_environment()
assert shell == "/bin/bash"
assert env["TERM"] == "xterm-256color"
class TestDecodeProxyData:
def test_decode_pty_data_valid_utf8(self) -> None:
"""Test decoding valid UTF-8 data."""
buffer = b"hello world"
text, remaining = _decode_pty_data(buffer)
assert text == "hello world"
assert remaining == b""
def test_decode_pty_data_with_unicode(self) -> None:
"""Test decoding UTF-8 data with unicode characters."""
buffer = "hello 🌍".encode()
text, remaining = _decode_pty_data(buffer)
assert text == "hello 🌍"
assert remaining == b""
def test_decode_pty_data_invalid_utf8_ignored(self) -> None:
"""Test decoding invalid UTF-8 data with ignore errors."""
buffer = b"hello\xff\xfeinvalid"
text, remaining = _decode_pty_data(buffer)
assert text == "helloinvalid" # Invalid bytes are ignored
assert remaining == b""
def test_decode_pty_data_buffer_too_large(self) -> None:
"""Test decoding when buffer exceeds max size."""
large_buffer = b"x" * 100000 # Larger than MAX_BUFFER_SIZE
text, remaining = _decode_pty_data(large_buffer, max_buffer_size=1024)
assert text == "x" * 100000 # Should decode with replacement
assert remaining == b""
def test_decode_pty_data_empty_buffer(self) -> None:
"""Test decoding empty buffer."""
buffer = b""
text, remaining = _decode_pty_data(buffer)
assert text == ""
assert remaining == b""
class TestShouldCloseOnCommand:
def test_should_close_on_command_exit_with_return(self) -> None:
"""Test exit command detection with return key."""
assert _should_close_on_command("exit", "\r") is True
assert _should_close_on_command("EXIT", "\r") is True
assert _should_close_on_command(" exit ", "\r") is True
def test_should_close_on_command_exit_with_newline(self) -> None:
"""Test exit command detection with newline."""
assert _should_close_on_command("exit", "\n") is True
assert _should_close_on_command("EXIT", "\n") is True
assert _should_close_on_command(" exit ", "\n") is True
def test_should_close_on_command_not_exit(self) -> None:
"""Test non-exit commands don't trigger close."""
assert _should_close_on_command("ls", "\r") is False
assert _should_close_on_command("echo hello", "\n") is False
assert _should_close_on_command("exit_status", "\r") is False
def test_should_close_on_command_no_enter(self) -> None:
"""Test exit command without enter key doesn't trigger close."""
assert _should_close_on_command("exit", "x") is False
assert _should_close_on_command("exit", "") is False
def test_should_close_on_command_empty_buffer(self) -> None:
"""Test empty command buffer."""
assert _should_close_on_command("", "\r") is False
assert _should_close_on_command(" ", "\n") is False
class TestManageCommandBuffer:
def test_manage_command_buffer_normal_size(self) -> None:
"""Test command buffer management under normal size."""
buffer = "ls -la"
new_buffer = _manage_command_buffer(buffer, " /home")
assert new_buffer == "ls -la /home"
def test_manage_command_buffer_exceeds_max_size(self) -> None:
"""Test command buffer management when exceeding max size."""
# Create a buffer that will exceed max size
long_command = "x" * 1000
buffer = long_command
new_buffer = _manage_command_buffer(buffer, "y", max_size=500)
# Should keep only the last 512 chars (KEEP_COMMAND_CHARS)
assert len(new_buffer) == 512 # Exactly KEEP_COMMAND_CHARS
assert new_buffer.endswith("y")
assert new_buffer.startswith("x")
def test_manage_command_buffer_empty_buffer(self) -> None:
"""Test command buffer management with empty buffer."""
buffer = ""
new_buffer = _manage_command_buffer(buffer, "hello")
assert new_buffer == "hello"
def test_manage_command_buffer_exactly_max_size(self) -> None:
"""Test command buffer management at exactly max size."""
buffer = "x" * 100
new_buffer = _manage_command_buffer(buffer, "y", max_size=100)
assert len(new_buffer) == 101
assert new_buffer == buffer + "y"
@pytest.mark.skipif(is_windows, reason="Skip on Windows")
class TestCreateProcessCleanupHandler:
def test_create_process_cleanup_handler_normal_cleanup(self) -> None:
"""Test process cleanup handler creation and execution."""
mock_child_pid = 12345
mock_fd = 10
cleanup = _create_process_cleanup_handler(mock_child_pid, mock_fd)
with (
patch("os.kill") as mock_kill,
patch("os.waitpid") as mock_waitpid,
patch("os.close") as mock_close,
):
cleanup()
# Should try graceful termination first
mock_kill.assert_any_call(mock_child_pid, signal.SIGTERM)
# Should try force kill
mock_kill.assert_any_call(mock_child_pid, signal.SIGKILL)
mock_waitpid.assert_called()
mock_close.assert_any_call(mock_fd)
def test_create_process_cleanup_handler_process_not_found(self) -> None:
"""Test cleanup handler when process doesn't exist."""
mock_child_pid = 12345
mock_fd = 10
cleanup = _create_process_cleanup_handler(mock_child_pid, mock_fd)
with (
patch("os.kill") as mock_kill,
patch("os.waitpid") as mock_waitpid,
patch("os.close") as mock_close,
):
mock_kill.side_effect = [
None,
ProcessLookupError("No such process"),
]
cleanup()
# Should still try to close the file descriptor
mock_close.assert_any_call(mock_fd)
def test_create_process_cleanup_handler_fd_error(self) -> None:
"""Test cleanup handler when file descriptor close fails."""
mock_child_pid = 12345
mock_fd = 10
cleanup = _create_process_cleanup_handler(mock_child_pid, mock_fd)
with (
patch("os.kill") as mock_kill,
patch("os.waitpid") as mock_waitpid,
patch("os.close") as mock_close,
):
mock_close.side_effect = OSError("Bad file descriptor")
# Should not raise an exception
cleanup()
mock_close.assert_any_call(mock_fd)
def test_cleanup_closes_master_before_blocking_waitpid(self) -> None:
"""Regression: the pty master fd must be closed BEFORE the blocking
`os.waitpid(pid, 0)`.
The child shell is the pty's session leader. If it is killed while the
server still holds the master open and a foreground child keeps the
slave open (e.g. a long-lived REPL or coding agent), the kernel cannot
revoke the controlling terminal, the shell never becomes a reapable
zombie, and the blocking `os.waitpid` deadlocks the asyncio event
loop forever (frozen server, `Ctrl-C` ignored, recoverable only with
`kill -9`). Closing the master first lets the shell be reaped, so this
call ordering is load-bearing.
"""
child_pid, fd = 4321, 7
calls: list = []
cleanup = _create_process_cleanup_handler(child_pid, fd)
with (
patch(
"os.kill",
side_effect=lambda p, s: calls.append(("kill", p, s)),
),
patch(
"os.waitpid",
side_effect=lambda p, f: (
calls.append(("waitpid", p, f)) or (0, 0)
),
),
patch(
"os.close",
side_effect=lambda d: calls.append(("close", d)),
),
):
cleanup()
close_idx = next(i for i, c in enumerate(calls) if c == ("close", fd))
blocking_wait_idx = next(
i for i, c in enumerate(calls) if c == ("waitpid", child_pid, 0)
)
assert close_idx < blocking_wait_idx, (
"os.close(fd) must run before the blocking os.waitpid(pid, 0) to "
f"avoid the terminal-cleanup deadlock; call order was {calls}"
)
class TestSetupChildProcess:
@patch("os.chdir")
@patch("os.execve")
def test_setup_child_process_success(
self, mock_execve: Mock, mock_chdir: Mock
) -> None:
"""Test successful child process setup."""
shell = "/bin/bash"
env = {"TERM": "xterm-256color", "PATH": "/usr/bin"}
cwd = "/home/user"
_setup_child_process(shell, env, cwd)
mock_chdir.assert_called_once_with(cwd)
mock_execve.assert_called_once_with(shell, [shell], env)
@patch("os.chdir")
@patch("os.execve")
@patch("sys.exit")
def test_setup_child_process_chdir_fails(
self, mock_exit: Mock, mock_execve: Mock, mock_chdir: Mock
) -> None:
"""Test child process setup when chdir fails."""
shell = "/bin/bash"
env = {"TERM": "xterm-256color"}
cwd = "/nonexistent"
mock_chdir.side_effect = OSError("No such directory")
_setup_child_process(shell, env, cwd)
mock_chdir.assert_called_once_with(cwd)
mock_execve.assert_not_called()
mock_exit.assert_called_once_with(1)
@patch("os.chdir")
@patch("os.execve")
@patch("sys.exit")
def test_setup_child_process_execve_fails(
self, mock_exit: Mock, mock_execve: Mock, mock_chdir: Mock
) -> None:
"""Test child process setup when execve fails."""
shell = "/bin/bash"
env = {"TERM": "xterm-256color"}
cwd = "/home/user"
mock_execve.side_effect = OSError("Exec format error")
_setup_child_process(shell, env, cwd)
mock_chdir.assert_called_once_with(cwd)
mock_execve.assert_called_once_with(shell, [shell], env)
mock_exit.assert_called_once_with(1)
# Additional edge case tests
class TestDecodeProxyDataEdgeCases:
def test_decode_pty_data_partial_utf8_sequence(self) -> None:
"""Test handling of partial UTF-8 sequences."""
# Create a partial UTF-8 sequence (emoji split across buffers)
full_emoji = "🌍".encode() # 4 bytes
partial_buffer = full_emoji[:2] # First 2 bytes only
text, remaining = _decode_pty_data(partial_buffer)
# Should handle gracefully with ignore errors
assert isinstance(text, str)
assert remaining == b""
def test_decode_pty_data_mixed_valid_invalid(self) -> None:
"""Test decoding buffer with mix of valid and invalid UTF-8."""
buffer = b"hello\xff\xfe world \xe2\x9c\x93" # hello[invalid] world ✓
text, remaining = _decode_pty_data(buffer)
assert "hello" in text
assert "world" in text
assert remaining == b""
class TestCommandBufferEdgeCases:
def test_manage_command_buffer_unicode_characters(self) -> None:
"""Test command buffer with unicode characters."""
buffer = "echo 🌍"
new_buffer = _manage_command_buffer(buffer, " 🚀")
assert new_buffer == "echo 🌍 🚀"
def test_manage_command_buffer_control_characters(self) -> None:
"""Test command buffer with control characters."""
buffer = "ls\x1b[1m" # ANSI escape sequence
new_buffer = _manage_command_buffer(buffer, "\x1b[0m")
assert new_buffer == "ls\x1b[1m\x1b[0m"
def test_should_close_on_command_case_variations(self) -> None:
"""Test exit command detection with various case combinations."""
test_cases = [
("exit", "\r", True),
("Exit", "\r", True),
("EXIT", "\r", True),
("eXiT", "\r", True),
("quit", "\r", False), # Only 'exit' should work
("logout", "\r", False),
]
for command, key, expected in test_cases:
assert _should_close_on_command(command, key) == expected
@pytest.mark.skipif(is_windows, reason="Skip on Windows")
@pytest.mark.skipif(
is_mac,
reason=(
"pty.fork() is unsafe on macOS when mixed with higher-level system "
"APIs and segfaults intermittently under the multi-threaded test "
"client; see https://docs.python.org/3/library/pty.html"
),
)
def test_terminal_ws_unicode_input(client: TestClient) -> None:
"""Test terminal websocket with unicode input."""
with client.websocket_connect(TERMINAL_WS_URL) as websocket:
# Send unicode command
websocket.send_text("echo 'Hello 🌍'")
websocket.send_text("\r")
data = websocket.receive_text()
# Should handle unicode properly
assert isinstance(data, str)
def test_terminal_ws_invalid_session_mode(client: TestClient) -> None:
"""Test terminal websocket rejects non-edit mode sessions."""
session_manager: SessionManager = get_session_manager(client)
original_mode = session_manager.mode
try:
# Test with RUN mode
session_manager.mode = SessionMode.RUN
with pytest.raises(WebSocketDisconnect):
with client.websocket_connect(TERMINAL_WS_URL):
pass # Should fail immediately
finally:
# Restore original mode
session_manager.mode = original_mode