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 sys
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from inline_snapshot import snapshot
from marimo._dependencies.dependencies import DependencyManager
from marimo._utils.formatter import (
BlackFormatter,
CellCodes,
DefaultFormatter,
FormatError,
Formatter,
RuffFormatter,
ruff,
)
HAS_RUFF = DependencyManager.ruff.has() or DependencyManager.which("ruff")
class TestFormatter:
"""Test the base Formatter class."""
async def test_base_formatter_returns_unchanged_codes(self):
"""Test that base Formatter returns codes unchanged."""
formatter = Formatter(line_length=88)
codes: CellCodes = {"cell1": "x = 1\ny = 2", "cell2": "z = 3"}
result = await formatter.format(codes)
assert result == codes
assert result is codes # Should be the same object
class TestDefaultFormatter:
"""Test the DefaultFormatter class that tries ruff, then black."""
@patch("marimo._utils.formatter.RuffFormatter")
@patch("marimo._dependencies.dependencies.DependencyManager.which")
@patch("marimo._dependencies.dependencies.DependencyManager.ruff")
async def test_uses_ruff_when_available(
self,
mock_ruff: MagicMock,
mock_which: MagicMock,
mock_ruff_formatter: MagicMock,
) -> None:
"""Test DefaultFormatter uses RuffFormatter when ruff is available."""
# Mock ruff as available
mock_ruff.has.return_value = True
mock_which.return_value = "/usr/bin/ruff"
# Mock RuffFormatter
mock_instance = AsyncMock()
mock_ruff_formatter.return_value = mock_instance
mock_instance.format.return_value = {"cell1": "formatted_code"}
formatter = DefaultFormatter(line_length=88)
codes: CellCodes = {"cell1": "x=1"}
result = await formatter.format(codes)
mock_ruff_formatter.assert_called_once_with(88)
mock_instance.format.assert_called_once_with(
codes, stdin_filename=None
)
assert result == {"cell1": "formatted_code"}
@patch("marimo._utils.formatter.BlackFormatter")
@patch("marimo._dependencies.dependencies.DependencyManager.black")
@patch("marimo._dependencies.dependencies.DependencyManager.which")
@patch("marimo._dependencies.dependencies.DependencyManager.ruff")
async def test_uses_black_when_ruff_unavailable_but_black_available(
self,
mock_ruff: MagicMock,
mock_which: MagicMock,
mock_black: MagicMock,
mock_black_formatter: MagicMock,
) -> None:
"""Test DefaultFormatter uses BlackFormatter when ruff unavailable but black available."""
# Mock ruff as unavailable, black as available
mock_ruff.has.return_value = False
mock_which.return_value = None
mock_black.has.return_value = True
# Mock BlackFormatter
mock_instance = AsyncMock()
mock_black_formatter.return_value = mock_instance
mock_instance.format.return_value = {"cell1": "formatted_code"}
formatter = DefaultFormatter(line_length=88)
codes: CellCodes = {"cell1": "x=1"}
result = await formatter.format(codes)
mock_black_formatter.assert_called_once_with(88)
mock_instance.format.assert_called_once_with(codes)
assert result == {"cell1": "formatted_code"}
@patch("marimo._dependencies.dependencies.DependencyManager.black")
@patch("marimo._dependencies.dependencies.DependencyManager.which")
@patch("marimo._dependencies.dependencies.DependencyManager.ruff")
async def test_raises_module_not_found_when_no_formatters_available(
self,
mock_ruff: MagicMock,
mock_which: MagicMock,
mock_black: MagicMock,
) -> None:
"""Test DefaultFormatter raises ModuleNotFoundError when no formatters available."""
# Mock both ruff and black as unavailable
mock_ruff.has.return_value = False
mock_which.return_value = None
mock_black.has.return_value = False
formatter = DefaultFormatter(line_length=88)
codes: CellCodes = {"cell1": "x=1"}
with pytest.raises(ModuleNotFoundError) as exc_info:
await formatter.format(codes)
assert "ruff or black" in str(exc_info.value)
assert exc_info.value.name == "ruff"
class TestRuffFormatter:
"""Test the RuffFormatter class."""
@patch("marimo._utils.formatter.ruff")
async def test_ruff_formatter_calls_ruff_function(
self, mock_ruff: MagicMock
) -> None:
"""Test RuffFormatter wraps cell code before formatting."""
import textwrap
mock_ruff.return_value = {"cell1": "def _():\n x = 1"}
formatter = RuffFormatter(line_length=100)
codes: CellCodes = {"cell1": "x=1"}
result = await formatter.format(codes)
wrapped_codes: CellCodes = {
"cell1": "def _():\n" + textwrap.indent("x=1", " ")
}
mock_ruff.assert_called_once_with(
wrapped_codes,
"format",
"--line-length",
"100",
stdin_filename=None,
)
assert result == {"cell1": "x = 1"}
@patch("marimo._utils.formatter.ruff")
async def test_ruff_formatter_passes_stdin_filename(
self, mock_ruff: MagicMock
) -> None:
"""Test RuffFormatter forwards notebook filename for config discovery."""
import textwrap
mock_ruff.return_value = {"cell1": "def _():\n x = 1"}
formatter = RuffFormatter(line_length=100)
codes: CellCodes = {"cell1": "x=1"}
result = await formatter.format(
codes, stdin_filename="/tmp/notebook.py"
)
wrapped_codes: CellCodes = {
"cell1": "def _():\n" + textwrap.indent("x=1", " ")
}
mock_ruff.assert_called_once_with(
wrapped_codes,
"format",
"--line-length",
"100",
stdin_filename="/tmp/notebook.py",
)
assert result == {"cell1": "x = 1"}
@patch("marimo._utils.formatter.ruff")
async def test_ruff_formatter_nested_function_single_blank_line(
self, mock_ruff: MagicMock
) -> None:
"""Regression test for #9848: nested functions get 1 blank line (function
scope), not 2 (file scope). The wrap/unwrap logic ensures ruff sees cell
code as a function body, not a module."""
cell_code = "x = 3\ndef _foo():\n return x + 1\nprint(_foo())"
# Ruff formats the wrapped cell with 1 blank line around the nested def
wrapped_formatted = "def _():\n x = 3\n\n def _foo():\n return x + 1\n\n print(_foo())"
mock_ruff.return_value = {"cell1": wrapped_formatted}
formatter = RuffFormatter(line_length=88)
result = await formatter.format({"cell1": cell_code})
# Unwrapped result must have exactly 1 blank line before and after _foo,
# not 2 (which file-scope ruff would produce without the wrap).
output = result["cell1"]
assert (
output == "x = 3\n\ndef _foo():\n return x + 1\n\nprint(_foo())"
)
assert "\n\n\n" not in output
@patch("marimo._utils.formatter.ruff")
async def test_ruff_formatter_app_function_cell(
self, mock_ruff: MagicMock
) -> None:
"""Regression test: @app.function cells (top-level function definitions)
are wrapped before formatting so ruff applies E301 (nested defs get
1 blank line), not E302 (top-level defs get 2 blank lines)."""
cell_code = 'def foo():\n """Something here"""'
wrapped_formatted = (
'def _():\n def foo():\n """Something here"""'
)
mock_ruff.return_value = {"cell1": wrapped_formatted}
formatter = RuffFormatter(line_length=88)
result = await formatter.format({"cell1": cell_code})
assert result == {"cell1": 'def foo():\n """Something here"""'}
@patch("marimo._utils.formatter.ruff")
async def test_ruff_formatter_preserves_class_decorator(
self, mock_ruff: MagicMock
) -> None:
cell_code = (
"@dataclasses.dataclass\nclass Test:\n name: str\n age: int"
)
wrapped_formatted = (
"def _():\n"
" @dataclasses.dataclass\n"
" class Test:\n"
" name: str\n"
" age: int"
)
mock_ruff.return_value = {"cell1": wrapped_formatted}
formatter = RuffFormatter(line_length=88)
result = await formatter.format({"cell1": cell_code})
assert result == {"cell1": cell_code}
@pytest.mark.skipif(not HAS_RUFF, reason="ruff not installed")
async def test_ruff_formatter_preserves_comments(self) -> None:
"""Regression test for #10054/#10057: comments must survive the real
wrap -> ruff -> unwrap round-trip. Comments are not AST nodes, so a
leading comment sits before the first body statement's lineno and a
trailing comment sits after the last statement's end_lineno; both were
previously dropped."""
cell_code = "# leading comment\nx=1\ny = 2 # inline comment\n# interior comment\nz = 3 # last-line comment\n# trailing comment"
result = await RuffFormatter(line_length=88).format({"c": cell_code})
assert result["c"] == snapshot(
"""\
# leading comment
x = 1
y = 2 # inline comment
# interior comment
z = 3 # last-line comment
# trailing comment"""
)
@patch("marimo._utils.formatter.ruff")
async def test_ruff_formatter_comment_only_cell(
self, mock_ruff: MagicMock
) -> None:
"""Comment-only cells are left unwrapped (def _(): # comment is a
syntax error) and passed through ruff unchanged."""
cell_code = "# just a comment"
mock_ruff.return_value = {"cell1": cell_code}
formatter = RuffFormatter(line_length=88)
result = await formatter.format({"cell1": cell_code})
# ruff receives the comment unwrapped, not inside def _():
mock_ruff.assert_called_once_with(
{"cell1": cell_code},
"format",
"--line-length",
"88",
stdin_filename=None,
)
assert result == {"cell1": cell_code}
@patch("marimo._utils.formatter.ruff")
async def test_ruff_formatter_propagates_exceptions(
self, mock_ruff: MagicMock
) -> None:
"""Test RuffFormatter propagates exceptions from ruff function."""
mock_ruff.side_effect = ModuleNotFoundError("ruff not found")
formatter = RuffFormatter(line_length=88)
codes: CellCodes = {"cell1": "x=1"}
with pytest.raises(ModuleNotFoundError):
await formatter.format(codes)
class TestBlackFormatter:
"""Test the BlackFormatter class."""
@patch("marimo._dependencies.dependencies.DependencyManager.black")
async def test_black_formatter_requires_dependency(
self, mock_black: MagicMock
):
"""Test BlackFormatter calls require on black dependency."""
mock_black.require.side_effect = ModuleNotFoundError("black required")
formatter = BlackFormatter(line_length=88)
codes: CellCodes = {"cell1": "x=1"}
with pytest.raises(ModuleNotFoundError):
await formatter.format(codes)
mock_black.require.assert_called_once_with("to enable code formatting")
@patch("asyncio.to_thread")
@patch("marimo._dependencies.dependencies.DependencyManager.black")
async def test_black_formatter_formats_code_successfully(
self, mock_black_dep: MagicMock, mock_to_thread: MagicMock
):
"""Test BlackFormatter successfully formats code using black."""
# Mock dependency requirement to pass
mock_black_dep.require.return_value = None
# Mock black module with __spec__ attribute
mock_black = MagicMock()
mock_black.__spec__ = MagicMock()
mock_mode = MagicMock()
mock_black.Mode.return_value = mock_mode
mock_black.format_str.return_value = "formatted_code\n"
with patch.dict(sys.modules, {"black": mock_black}):
mock_to_thread.return_value = "formatted_code\n"
formatter = BlackFormatter(line_length=100)
codes: CellCodes = {"cell1": "x=1", "cell2": "y=2"}
result = await formatter.format(codes)
assert result == {
"cell1": "formatted_code",
"cell2": "formatted_code",
}
mock_black.Mode.assert_called_with(line_length=100)
assert mock_to_thread.call_count == 2
@patch("asyncio.to_thread")
@patch("marimo._dependencies.dependencies.DependencyManager.black")
async def test_black_formatter_handles_formatting_errors_gracefully(
self, mock_black_dep: MagicMock, mock_to_thread: MagicMock
):
"""Test BlackFormatter handles black formatting errors gracefully."""
# Mock dependency requirement to pass
mock_black_dep.require.return_value = None
# Mock black module with __spec__ attribute
mock_black = MagicMock()
mock_black.__spec__ = MagicMock()
mock_mode = MagicMock()
mock_black.Mode.return_value = mock_mode
with patch.dict(sys.modules, {"black": mock_black}):
# First call succeeds, second call fails
mock_to_thread.side_effect = [
"formatted_code\n",
Exception("Black error"),
]
formatter = BlackFormatter(line_length=88)
codes: CellCodes = {"cell1": "x=1", "cell2": "y=2"}
result = await formatter.format(codes)
# Should return formatted code for successful cells, original for failed
assert result == {
"cell1": "formatted_code",
"cell2": "y=2",
}
class TestRuffFunction:
"""Test the ruff async function."""
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_with_module_ruff_available(
self, mock_subprocess_safe: MagicMock
):
"""Test ruff function when ruff is available as a module."""
# Mock help command success, then format command success
mock_subprocess_safe.side_effect = [
(b"", b"", 0), # help command success
(b"formatted_code\n", b"", 0), # format command success
]
codes: CellCodes = {"cell1": "x=1"}
result = await ruff(codes, "format", "--line-length", "88")
assert result == {"cell1": "formatted_code"}
# Check that help command was called first
help_call = mock_subprocess_safe.call_args_list[0]
assert help_call[0] == (sys.executable, "-m", "ruff", "--help")
# Check that format command was called
format_call = mock_subprocess_safe.call_args_list[1]
assert format_call[0] == (
sys.executable,
"-m",
"ruff",
"format",
"--line-length",
"88",
"-",
)
assert format_call[1]["input_data"] == b"x=1"
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_passes_stdin_filename(
self, mock_subprocess_safe: MagicMock
):
"""Test ruff includes --stdin-filename when provided."""
mock_subprocess_safe.side_effect = [
(b"", b"", 0), # help command success
(b"formatted_code\n", b"", 0), # format command success
]
codes: CellCodes = {"cell1": "x=1"}
result = await ruff(
codes,
"format",
"--line-length",
"88",
stdin_filename="/tmp/notebook.py",
)
assert result == {"cell1": "formatted_code"}
format_call = mock_subprocess_safe.call_args_list[1]
assert format_call[0] == (
sys.executable,
"-m",
"ruff",
"format",
"--line-length",
"88",
"--stdin-filename",
"/tmp/notebook.py",
"-",
)
assert format_call[1]["input_data"] == b"x=1"
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_falls_back_to_global_ruff(
self, mock_subprocess_safe: MagicMock
):
"""Test ruff function falls back to global ruff when module unavailable."""
# Mock module ruff failing, global ruff succeeding for help, then format success
mock_subprocess_safe.side_effect = [
(b"", b"", 1), # module help fails
(b"", b"", 0), # global help succeeds
(b"formatted_code\n", b"", 0), # format succeeds
]
codes: CellCodes = {"cell1": "x=1"}
result = await ruff(codes, "format")
assert result == {"cell1": "formatted_code"}
# Check that global ruff was used for format command
format_call = mock_subprocess_safe.call_args_list[2]
assert format_call[0] == ("ruff", "format", "-")
assert format_call[1]["input_data"] == b"x=1"
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_raises_module_not_found_when_unavailable(
self, mock_subprocess_safe: MagicMock
):
"""Test ruff function raises ModuleNotFoundError when ruff is unavailable."""
# Mock both module and global ruff failing
mock_subprocess_safe.return_value = (b"", b"", 1)
codes: CellCodes = {"cell1": "x=1"}
with pytest.raises(ModuleNotFoundError) as exc_info:
await ruff(codes, "format")
assert "ruff" in str(exc_info.value)
assert exc_info.value.name == "ruff"
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_handles_format_failures_gracefully(
self, mock_subprocess_safe: MagicMock
):
"""Test ruff function handles individual cell formatting failures gracefully."""
# Mock help command success, then format commands - one success, one failure
mock_subprocess_safe.side_effect = [
(b"", b"", 0), # help succeeds
(b"formatted_code\n", b"", 0), # first format succeeds
(b"", b"syntax error", 1), # second format fails
]
codes: CellCodes = {"cell1": "x=1", "cell2": "invalid syntax"}
result = await ruff(codes, "format")
# Should only include successfully formatted code
assert result == {"cell1": "formatted_code"}
@patch("marimo._utils.formatter.LOGGER")
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_handles_communication_exceptions(
self, mock_subprocess_safe: MagicMock, mock_logger: MagicMock
):
"""Test ruff function handles communication exceptions gracefully."""
del mock_logger
# Mock help command success, then format command that raises exception
mock_subprocess_safe.side_effect = [
(b"", b"", 0), # help succeeds
Exception("Communication failed"), # format fails with exception
]
codes: CellCodes = {"cell1": "x=1"}
result = await ruff(codes, "format")
# Should return empty dict when all cells fail
assert result == {}
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_strips_whitespace_from_output(
self, mock_subprocess_safe: MagicMock
):
"""Test ruff function strips whitespace from formatted output."""
# Mock help command success, then format with whitespace in output
mock_subprocess_safe.side_effect = [
(b"", b"", 0), # help succeeds
(b" formatted_code \n\n", b"", 0), # format with whitespace
]
codes: CellCodes = {"cell1": "x=1"}
result = await ruff(codes, "format")
assert result == {"cell1": "formatted_code"}
@patch("marimo._utils.formatter.LOGGER")
@patch("marimo._utils.formatter._run_subprocess_safe")
async def test_ruff_function_raises_format_error_on_non_zero_exit(
self, mock_subprocess_safe: MagicMock, mock_logger: MagicMock
):
"""Test ruff function raises FormatError when format command fails."""
del mock_logger
# Mock help command success, then format command that fails
mock_subprocess_safe.side_effect = [
(b"", b"", 0), # help succeeds
(b"", b"format error", 1), # format fails
]
codes: CellCodes = {"cell1": "x=1"}
result = await ruff(codes, "format")
# Should skip failed cells
assert result == {}
@patch("asyncio.to_thread")
@patch("asyncio.create_subprocess_exec")
async def test_run_subprocess_safe_falls_back_on_windows(
self, mock_subprocess_exec: MagicMock, mock_to_thread: MagicMock
):
"""Test _run_subprocess_safe falls back to subprocess.run on Windows."""
from marimo._utils.formatter import _run_subprocess_safe
# Mock asyncio.create_subprocess_exec to raise NotImplementedError (Windows behavior)
mock_subprocess_exec.side_effect = NotImplementedError()
# Mock asyncio.to_thread to return subprocess result
mock_to_thread.return_value = (b"output", b"error", 0)
result = await _run_subprocess_safe("python", "--version")
assert result == (b"output", b"error", 0)
mock_to_thread.assert_called_once()
class TestFormatError:
"""Test the FormatError exception class."""
def test_format_error_is_exception(self) -> None:
"""Test FormatError is a proper Exception subclass."""
error = FormatError("test message")
assert isinstance(error, Exception)
assert str(error) == "test message"
def test_format_error_can_be_raised_and_caught(self) -> None:
"""Test FormatError can be raised and caught properly."""
with pytest.raises(FormatError) as exc_info:
raise FormatError("test formatting error")
assert str(exc_info.value) == "test formatting error"
class TestFormatterIntegration:
"""Integration tests for formatter classes working together."""
async def test_formatter_inheritance_structure(self) -> None:
"""Test that all formatter classes inherit from base Formatter properly."""
assert issubclass(DefaultFormatter, Formatter)
assert issubclass(RuffFormatter, Formatter)
assert issubclass(BlackFormatter, Formatter)
async def test_all_formatters_accept_line_length_parameter(self) -> None:
"""Test all formatters accept and store line_length parameter."""
formatters = [
Formatter(100),
DefaultFormatter(100),
RuffFormatter(100),
BlackFormatter(100),
]
for formatter in formatters:
assert formatter.line_length == 100
async def test_cell_codes_type_alias_works_correctly(self) -> None:
"""Test CellCodes type alias works as expected."""
codes: CellCodes = {"cell1": "code1", "cell2": "code2"}
assert isinstance(codes, dict)
assert all(isinstance(k, str) for k in codes)
assert all(isinstance(v, str) for v in codes.values())