Skip to content

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.

22.3 KB
Raw Blame
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations

import contextlib
import dataclasses
import functools
import inspect
import shutil
import sys
import textwrap
from pathlib import Path
from typing import TYPE_CHECKING, Any
from unittest.mock import Mock, patch

import pytest
from _pytest import runner

from marimo._ast.app import App
from marimo._ast.cell_manager import CellManager
from marimo._dependencies.dependencies import DependencyManager
from marimo._output.formatters.formatters import register_formatters
from marimo._runtime.commands import ExecuteCellCommand
from marimo._save.stubs.module_stub import ModuleStub
from marimo._server.utils import initialize_mimetypes
from marimo._session.model import SessionMode
from marimo._session.state.session_view import SessionView
from marimo._types.ids import CellId_t
from tests._runtime._helpers.session import TestKernel, mocked_kernel_session
from tests._runtime._helpers.streams import (
    MockStderr,
    MockStdin,
    MockStdout,
    MockStream,
)

# Back-compat alias: tests/_runtime/test_redirect_streams.py still imports this.
_MockStream = MockStream

if TYPE_CHECKING:
    import threading
    from collections.abc import Callable, Generator
    from types import ModuleType, TracebackType
    from typing import Self

    from marimo._runtime.runtime import Kernel

# register import hooks for third-party module formatters
register_formatters()

# Initialize mimetypes for consistent behavior across platforms (especially Windows)
initialize_mimetypes()


@pytest.fixture(scope="session", autouse=True)
def _isolate_jedi_cache(
    tmp_path_factory: pytest.TempPathFactory,
) -> Generator[None, None, None]:
    import jedi

    # Parso's disk cache writes are not atomic across pytest workers.
    with pytest.MonkeyPatch.context() as monkeypatch:
        monkeypatch.setattr(
            jedi.settings,
            "cache_directory",
            str(tmp_path_factory.mktemp("jedi")),
        )
        yield


def pytest_collection_modifyitems(
    config: pytest.Config, items: list[pytest.Item]
) -> None:
    """Auto-skip tests based on @pytest.mark.requires() markers."""
    del config  # Unused but required by pytest hook signature
    for item in items:
        requires_marker = item.get_closest_marker("requires")
        if not requires_marker:
            continue

        missing_deps = []
        # Get dependency names from marker args
        for dep_name in requires_marker.args:
            # Try to get the dependency from DependencyManager
            dep_manager = getattr(DependencyManager, dep_name, None)
            if dep_manager is not None:
                if not dep_manager.has():
                    missing_deps.append(dep_name)
            else:
                # Unknown dependency name
                missing_deps.append(f"{dep_name} (unknown)")

        # Skip test if any dependencies are missing
        if missing_deps:
            deps_str = ", ".join(missing_deps)
            reason = f"requires {deps_str}"
            item.add_marker(pytest.mark.skip(reason=reason))


# Captured at conftest import time (i.e. at worker startup, before any test
# runs on any xdist worker), so the on-disk file can be mutated mid-session by
# a leaking `uv add` without corrupting `tests/test_project_dependencies.py`.
_PYPROJECT_PATH = Path(__file__).parent.parent / "pyproject.toml"
_PYPROJECT_TEXT_AT_SESSION_START = (
    _PYPROJECT_PATH.read_text() if _PYPROJECT_PATH.is_file() else None
)


@pytest.fixture(scope="session")
def pyproject_text() -> str:
    """`pyproject.toml` content as it was at session start.

    Use this instead of reading `pyproject.toml` directly in tests so the
    read is immune to mid-session mutations by parallel tests (e.g. a
    leaking real `uv add`).
    """
    if _PYPROJECT_TEXT_AT_SESSION_START is None:
        pytest.fail(
            f"pyproject.toml not found at {_PYPROJECT_PATH} when conftest "
            f"was imported."
        )
    return _PYPROJECT_TEXT_AT_SESSION_START


@pytest.fixture(scope="session")
def _venv_canary_path() -> Path | None:
    """Resolve an on-disk file whose existence signals the test venv is intact.

    We use `hypothesis`: it's in the `test` dependency group but not in
    `[project.dependencies]`, so if a test calls through to the real
    `UvPackageManager.install`/`uninstall` (which shells out to
    `uv add`/`uv remove` → `uv sync`), the sync resolves against
    `[project.dependencies]` only and deletes every test-group package
    from `.venv`. Watching `hypothesis/__init__.py` catches that
    mutation with a single stat call.
    """
    import importlib.util

    spec = importlib.util.find_spec("hypothesis")
    if spec is None or spec.origin is None:
        return None
    path = Path(spec.origin)
    return path if path.exists() else None


@pytest.fixture(autouse=True)
def _assert_venv_not_wiped(
    _venv_canary_path: Path | None, request: pytest.FixtureRequest
) -> Generator[None, None, None]:
    """Fail fast if a test mutates the shared test venv.

    The historical failure this guards against: an unmocked call to
    `UvPackageManager.install`/`uninstall` (e.g. via
    `ctx.packages.add`/`remove` in code-mode tests) runs
    `uv add`/`uv remove` against the project's `pyproject.toml`,
    then `uv sync` resolves only `[project.dependencies]` and deletes
    every `[dependency-groups].test` package — pytest, hypothesis,
    numpy, matplotlib, execnet, the `.venv/bin/pytest` shim — from the
    venv. Subsequent tests cascade into obscure
    `ModuleNotFoundError`/`FileNotFoundError` failures.

    Checking the canary before and after each test pinpoints the exact
    offender: see `tests/_code_mode/test_context.py::TestPackages` for
    the required mocking pattern.

    Under pytest-xdist, other workers run concurrently; the post-check
    can fire on a worker whose current test did not cause the mutation.
    We soften the post-check message in that case and recommend
    rerunning with `-p no:xdist` to identify the culprit.
    """
    import os

    under_xdist = "PYTEST_XDIST_WORKER" in os.environ

    if _venv_canary_path is None:
        # Could not establish a canary (e.g. hypothesis not installed on
        # disk); nothing to protect.
        yield
        return

    if not _venv_canary_path.exists():
        pytest.fail(
            f"Test venv was mutated before {request.node.nodeid!r}: "
            f"canary {_venv_canary_path} is missing. A previous test "
            f"invoked the real package manager (likely via "
            f"ctx.packages.add/remove without mocking pm.install/"
            f"pm.uninstall). See tests/_code_mode/test_context.py::"
            f"TestPackages for the required pattern."
        )
    yield
    if not _venv_canary_path.exists():
        if under_xdist:
            pytest.fail(
                f"Test venv was mutated during or concurrent with "
                f"{request.node.nodeid!r}: canary {_venv_canary_path} "
                f"no longer exists. Under xdist the mutator may be a "
                f"different worker's test. Rerun with `-p no:xdist` "
                f"to identify the culprit. See "
                f"tests/_code_mode/test_context.py::TestPackages for "
                f"the required mocking pattern."
            )
        else:
            pytest.fail(
                f"Test {request.node.nodeid!r} mutated the shared venv: "
                f"canary {_venv_canary_path} no longer exists. This test "
                f"(or a fixture it uses) invoked the real package manager. "
                f"Mock pm.install/pm.uninstall — see "
                f"tests/_code_mode/test_context.py::TestPackages for the "
                f"required pattern."
            )


@pytest.fixture(scope="session")
def _fake_main_file(tmp_path_factory: pytest.TempPathFactory) -> Path:
    """A benign empty .py file to assign as __main__.__file__ in tests.

    Why not reuse the real pytest launcher path? On Windows,
    shutil.which("pytest") returns pytest.exe — a zipapp. If a cell
    spawns a child process via multiprocessing.Manager() (or anything
    using the "spawn" start method), the child runs
    multiprocessing.spawn._fixup_main_from_path(__main__.__file__),
    which calls runpy.run_path() on the parent's __file__. For a zipapp
    pytest.exe that means pytest starts running inside the child
    process, never writes the Manager's server address back, and the
    parent hangs at reader.recv(). An empty .py file has no side
    effects when runpy executes it.
    """
    path = tmp_path_factory.mktemp("marimo_test_main") / "pytest_main.py"
    path.write_text("")
    return path


@pytest.fixture(autouse=True)
def _ensure_main_has_file(
    _fake_main_file: Path,
) -> Generator[None, None, None]:
    """Make sure main has a file ...

    xdist workers don't always set __file__ on __main__, which causes
    marimo's kernel (create_main_module) to set __file__=None,
    breaking tests that rely on __file__ being a real path.
    """
    main = sys.modules.get("__main__")
    if main is None:
        yield
        return

    had_file_attr = hasattr(main, "__file__")
    original_file = getattr(main, "__file__", None)

    if not had_file_attr or original_file is None:
        main.__file__ = str(_fake_main_file)

    try:
        yield
    finally:
        current_main = sys.modules.get("__main__")
        if current_main is not None:
            if had_file_attr:
                # Restore the original value (which may be None)
                current_main.__file__ = original_file
            elif hasattr(current_main, "__file__"):
                del current_main.__file__


@pytest.fixture(autouse=True)
def _save_and_restore_main(
    _ensure_main_has_file: None,
) -> Generator[None, None, None]:
    """Restore sys.modules["__main__"] after each test.

    marimo's kernel swaps out the main module via patch_main_module;
    without this fixture, that swap leaks into subsequent tests.
    """
    main = sys.modules.get("__main__")
    if main is None:
        yield
        return

    try:
        yield
    finally:
        sys.modules["__main__"] = main


@pytest.fixture(autouse=True)
def patch_random_seed(monkeypatch: pytest.MonkeyPatch) -> None:
    """Patch UIElement._random_seed to use a fixed seed for testing"""
    import random

    from marimo._plugins.ui._core.ui_element import UIElement

    # Patch the random seed to be deterministic for testing
    monkeypatch.setattr(UIElement, "_random_seed", random.Random(42))


@pytest.fixture
def cleanup_watchers(
    monkeypatch: pytest.MonkeyPatch,
) -> Generator[None, None, None]:
    from marimo._runtime.threads import Thread
    from marimo._runtime.watch import _directory, _file, _path

    watchers: list[tuple[Thread, threading.Event]] = []

    def track_thread(
        *,
        target: Callable[..., None],
        args: tuple[Path, _path.PathState, threading.Event],
        daemon: bool,
    ) -> Thread:
        thread = Thread(target=target, args=args, daemon=daemon)
        watchers.append((thread, args[2]))
        return thread

    monkeypatch.setattr(_path, "Thread", track_thread)
    # Restore intervals changed by notebook cells after each test.
    monkeypatch.setattr(_file, "_TEST_SLEEP_INTERVAL", None)
    monkeypatch.setattr(_directory, "_TEST_SLEEP_INTERVAL", None)
    try:
        yield
    finally:
        # The watcher target holds its PathState alive, so __del__ cannot
        # stop the thread when the test kernel clears its globals.
        for _, should_exit in watchers:
            should_exit.set()
        for thread, _ in watchers:
            thread.join(timeout=5)
            assert not thread.is_alive()


@dataclasses.dataclass
class MockedKernel:
    """Should only be created in fixtures b/c inits a runtime context."""

    _tk: TestKernel
    _cm: contextlib.AbstractContextManager[TestKernel]

    @classmethod
    def open(cls, **kwargs: Any) -> MockedKernel:
        cm = mocked_kernel_session(**kwargs)
        tk = cm.__enter__()
        return cls(_tk=tk, _cm=cm)

    @property
    def k(self) -> Kernel:
        return self._tk.kernel

    @property
    def stream(self) -> MockStream:
        return self._tk.stream

    @property
    def stdout(self) -> MockStdout:
        return self._tk.stdout

    @property
    def stderr(self) -> MockStderr:
        return self._tk.stderr

    @property
    def stdin(self) -> MockStdin:
        return self._tk.stdin

    def teardown(self) -> None:
        self._cm.__exit__(None, None, None)


# fixture that provides a kernel (and tears it down)
@pytest.fixture
def k() -> Generator[Kernel, None, None]:
    with mocked_kernel_session() as tk:
        yield tk.kernel


# kernel configured with runtime=lazy
@pytest.fixture
def lazy_kernel() -> Generator[Kernel, None, None]:
    with mocked_kernel_session(
        execution_type="relaxed", reactive_mode="lazy"
    ) as tk:
        yield tk.kernel


# kernel configured with strict execution
@pytest.fixture
def strict_kernel() -> Generator[Kernel, None, None]:
    with mocked_kernel_session(
        execution_type="strict", reactive_mode="autorun"
    ) as tk:
        yield tk.kernel


# kernel configured in SessionMode.RUN mode
@pytest.fixture
def run_mode_kernel() -> Generator[MockedKernel, None, None]:
    mocked = MockedKernel.open(mode=SessionMode.RUN)
    yield mocked
    mocked.teardown()


@pytest.fixture(params=["k", "strict_kernel"])
def execution_kernel(request: Any) -> Kernel:
    return request.getfixturevalue(request.param)


@pytest.fixture(params=["k", "strict_kernel", "lazy_kernel"])
def any_kernel(request: Any) -> Kernel:
    return request.getfixturevalue(request.param)


# fixture that wraps a kernel and other mocked objects
@pytest.fixture
def mocked_kernel() -> Generator[MockedKernel, None, None]:
    mocked = MockedKernel.open()
    yield mocked
    mocked.teardown()


# Installs an execution context without stream redirection
@pytest.fixture
def executing_kernel() -> Generator[Kernel, None, None]:
    from marimo._messaging.types import KernelStreams

    mocked = MockedKernel.open()
    mocked.k._streams = KernelStreams(
        stream=mocked.k.stream, stdout=None, stderr=None, stdin=None
    )
    with mocked.k._install_execution_context(cell_id="0"):
        yield mocked.k
    mocked.teardown()


@pytest.fixture(scope="session")
def default_snippets():
    """Read all default snippets once per test session."""
    import asyncio

    from marimo._config.config import merge_default_config
    from marimo._snippets.snippets import read_snippets

    return asyncio.run(read_snippets(merge_default_config({})))


FIXTURE_DIR = Path(__file__).parent / "fixtures"


def _make_temp_fixture(fixture_name: str, subdir: str):
    @pytest.fixture
    def _fixture(tmp_path: Path) -> str:
        fixture_file = FIXTURE_DIR / fixture_name
        tmp_file = tmp_path / subdir / fixture_name.rsplit("/", maxsplit=1)[-1]
        tmp_file.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy(fixture_file, tmp_file)
        return str(tmp_file)

    return _fixture


temp_marimo_file = _make_temp_fixture("notebook.py", "test")
temp_sandboxed_marimo_file = _make_temp_fixture(
    "notebook_sandboxed.py", "sandboxed"
)
temp_async_marimo_file = _make_temp_fixture("notebook_async.py", "async")
temp_unparsable_marimo_file = _make_temp_fixture(
    "notebook_unparsable.py", "unparsable"
)
temp_marimo_file_with_md = _make_temp_fixture("notebook_with_md.py", "with_md")
temp_marimo_file_with_media = _make_temp_fixture(
    "notebook_with_media.py", "with_media"
)
temp_md_marimo_file = _make_temp_fixture("notebook.md", "with_md")
temp_marimo_file_with_errors = _make_temp_fixture(
    "notebook_with_errors.py", "with_errors"
)
temp_marimo_file_with_multiple_definitions = _make_temp_fixture(
    "notebook_with_multiple_definitions.py", "with_multiple_definitions"
)


@pytest.fixture
def session_view() -> Generator[SessionView, None, None]:
    from tests.utils import assert_serialize_roundtrip

    sv = SessionView()

    yield sv

    # Test all operations can be serialized/deserialized
    for operation in sv.snapshot_notifications():
        assert_serialize_roundtrip(operation)


# Factory to create ExecuteCellCommands and abstract away cell ID
class ExecReqProvider:
    def __init__(self) -> None:
        self.cell_manager = CellManager()

    def get(self, code: str) -> ExecuteCellCommand:
        key = self.cell_manager.create_cell_id()
        return ExecuteCellCommand(cell_id=key, code=textwrap.dedent(code))

    def get_with_id(self, cell_id: CellId_t, code: str) -> ExecuteCellCommand:
        return ExecuteCellCommand(cell_id=cell_id, code=textwrap.dedent(code))


# fixture that provides an ExecReqProvider
@pytest.fixture
def exec_req() -> ExecReqProvider:
    return ExecReqProvider()


class MockPyodide:
    """Simulate running in a Pyodide environment.

    Patches `sys.platform` to `"emscripten"` so `is_pyodide()` returns
    True, and stubs `pyodide` (plus any `extra_modules`) in
    `sys.modules` so `import pyodide` (and friends) succeeds.

    Usable as a context manager or as a decorator on sync or async tests::

        with mock_pyodide():
            ...

        @mock_pyodide()
        async def test_foo(...): ...

        @mock_pyodide(already_installed=Mock())
        def test_bar(...): ...
    """

    def __init__(self, **extra_modules: Any) -> None:
        self._extra_modules = extra_modules
        self._stack: contextlib.ExitStack | None = None

    def __enter__(self) -> Self:
        modules = {"pyodide": Mock(), **self._extra_modules}
        stack = contextlib.ExitStack()
        stack.__enter__()
        stack.enter_context(patch.object(sys, "platform", "emscripten"))
        stack.enter_context(patch.dict(sys.modules, modules))
        self._stack = stack
        return self

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_value: BaseException | None,
        traceback: TracebackType | None,
    ) -> None:
        assert self._stack is not None
        self._stack.__exit__(exc_type, exc_value, traceback)
        self._stack = None

    def __call__(self, func: Any) -> Any:
        extra = self._extra_modules
        if inspect.iscoroutinefunction(func):

            @functools.wraps(func)
            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
                with MockPyodide(**extra):
                    return await func(*args, **kwargs)

            return async_wrapper

        @functools.wraps(func)
        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
            with MockPyodide(**extra):
                return func(*args, **kwargs)

        return sync_wrapper


# Lowercase alias for context-manager-style usage at call sites.
mock_pyodide = MockPyodide


@pytest.fixture
def pyodide_env() -> Generator[None, None, None]:
    """Pytest fixture that simulates running in a Pyodide environment."""
    with mock_pyodide():
        yield


# Library fixtures for direct marimo integration with pytest.
@pytest.fixture
def mo_fixture() -> ModuleType:
    import marimo as mo

    return mo


# Sets some non-public attributes on App and runs it.
@pytest.fixture
def app() -> Generator[App, None, None]:
    app = App()
    # Needed for consistent stack trace paths.
    app._anonymous_file = True
    # Provides verbose traceback on assertion errors. Note it does alter the
    # cell AST.
    app._pytest_rewrite = True
    yield app
    app.run()


class TestableModuleStub(ModuleStub):
    __test__ = False

    def __eq__(self, other: object) -> bool:
        # Used for testing, equality otherwise not useful.
        if not isinstance(other, ModuleStub):
            return False
        return self.name == other.name

    def __hash__(self) -> int:
        return hash(self.name) + hash("module")


# A pytest hook to fail when raw marimo cells are not collected.
# Meta testing gets a little messy, and may leave you a little testy. This is
# increasingly coupled with the following specific tests that test testing:
# _ast/
#    ./test_pytest
#    ./test_pytest_toplevel
#    ./test_pytest_scoped
@pytest.hookimpl
def pytest_make_collect_report(collector):
    # If it's not a module, we must early.
    if not isinstance(collector, pytest.Module):
        return None

    report = runner.pytest_make_collect_report(collector)

    # Defined within the file does not seem to hook correctly, as such filter
    # for the test_pytest specific file here.
    if not (
        "test_pytest" in str(collector.path) and "_ast" in str(collector.path)
    ):
        return report

    # Classes may also be registered, but they will be hidden behind a cell.
    # As such, let's just collect functions.
    collected = {
        fn.originalname
        for fn in collector.collect()
        if isinstance(fn, pytest.Function)
    }
    classes = {
        cls.name
        for cls in collector.collect()
        if isinstance(cls, pytest.Class)
    }
    from tests._ast.test_pytest import app as app_pytest
    from tests._ast.test_pytest_scoped import app as app_scoped
    from tests._ast.test_pytest_toplevel import app as app_toplevel

    app = {
        "test_pytest": app_pytest,
        "test_pytest_toplevel": app_toplevel,
        "test_pytest_scoped": app_scoped,
    }[collector.path.stem]

    # Just a quick check to make sure the class is actually exported.
    if app == app_pytest and len(classes) == 0:
        report.outcome = "failed"
        report.longrepr = (
            f"Expected class in {collector.path}, found none "
            " (tests/conftest.py)."
        )
        return report
    for cls in classes:
        if not (
            cls.startswith("MarimoTestBlock")
            or cls
            in (
                "TestClassWorks",
                "TestClassWithFixtures",
                "TestClassDefinitionWithFixtures",
            )
        ):
            report.outcome = "failed"
            report.longrepr = (
                f"Unknown class '{cls}' in {collector.path}"
                " (tests/conftest.py)."
            )

            return report

    # Check the functions match cells in the app.
    invalid = []
    for name in app._cell_manager.names():
        if name.startswith("test_") and name not in collected:
            invalid.append(f"'{name}'")
    if invalid:
        tests = ", ".join([f"'{test}'" for test in collected])
        report.outcome = "failed"
        report.longrepr = (
            f"Cannot collect test(s) {', '.join(invalid)} from {tests}"
            " (tests/conftest.py)."
        )
    return report