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.

feat: code-mode .screenshot() api (#9232)

Myles Scolnickece866051c5e
diff --git a/marimo/_code_mode/_context.py b/marimo/_code_mode/_context.py
index 1a5b92ae4d..a4bf79acd9 100644
--- a/marimo/_code_mode/_context.py
+++ b/marimo/_code_mode/_context.py
@@ -88,11 +88,13 @@ from marimo._utils.formatter import DefaultFormatter
if TYPE_CHECKING:
from collections.abc import Iterator, Sequence
+ from os import PathLike
from types import TracebackType
from typing_extensions import Self
from marimo._ast.cell_manager import CellManager
+ from marimo._code_mode.screenshot import _ScreenshotSession
from marimo._runtime.dataflow import DirectedGraph
from marimo._runtime.runtime import Kernel
@@ -614,6 +616,7 @@ class AsyncCodeModeContext:
self._ui_updates: list[tuple[UIElementId, Any]] = []
self._cells_to_run: set[CellId_t] = set()
self._entered = False
+ self._screenshot_session: _ScreenshotSession | None = None
def _require_entered(self) -> None:
if not self._entered:
@@ -671,6 +674,8 @@ class AsyncCodeModeContext:
self._ui_updates = []
self._cells_to_run = set()
+ await self.close_screenshot_session()
+
if exc_type is not None:
self._packages._reset()
return # let exception propagate, discard queued ops
@@ -1199,6 +1204,197 @@ class AsyncCodeModeContext:
)
self._cells_to_run.add(cell_id)
+ # ------------------------------------------------------------------
+ # Screenshot
+ # ------------------------------------------------------------------
+
+ async def screenshot(
+ self,
+ target: int | str | NotebookCell | None = None,
+ *,
+ timeout_ms: int = 30_000,
+ as_data_url: bool = False,
+ save_to: str | PathLike[str] | None = None,
+ ) -> bytes | str:
+ """Capture a cell's rendered output as a PNG screenshot.
+
+ Launches a headless Chromium browser (reused across calls)
+ connected to this server in kiosk mode.
+
+ Requires ``playwright`` + its Chromium binary::
+
+ ctx.install_packages("playwright")
+ # then once: python -m playwright install chromium
+
+ Does **not** require ``async with``.
+
+ Args:
+ target: Cell to screenshot.
+
+ - ``None`` — last cell.
+ - ``int`` — cell index (negative OK).
+ - ``str`` — cell ID or name.
+ - ``NotebookCell`` — e.g. ``ctx.cells[0]``.
+
+ For an object defined by a cell, resolve first::
+
+ cid = ctx.find_cell_defining_object(chart)
+ img = await ctx.screenshot(cid)
+
+ timeout_ms: Max wait (ms) for the output to be visible.
+ as_data_url: Return ``data:image/png;base64,...`` str
+ instead of raw bytes.
+ save_to: Also write the PNG to this path.
+
+ Returns:
+ ``bytes`` (PNG), or ``str`` (data URL) if *as_data_url*.
+
+ Raises:
+ ScreenshotError: Missing playwright, missing browser,
+ unknown cell, empty output, or invisible element.
+ """
+ from pathlib import Path
+
+ from marimo._code_mode.screenshot import (
+ ScreenshotError,
+ _ScreenshotSession,
+ _to_data_url,
+ )
+ from marimo._messaging.context import HTTP_REQUEST_CTX
+
+ cell_id = self._resolve_screenshot_target(target)
+
+ # Resolve server URL from the current HTTP request context.
+ request = HTTP_REQUEST_CTX.get(None)
+ if request is None:
+ raise ScreenshotError(
+ "Cannot take screenshots: no HTTP request context "
+ "available. screenshot() must be called during cell "
+ "execution (e.g. from code-mode)."
+ )
+ # Read trusted server URL and auth token injected by the
+ # /execute endpoint (from server config, not request headers).
+ server_url: str | None = request.meta.get("screenshot_server_url")
+ if server_url is None:
+ raise ScreenshotError(
+ "Cannot take screenshots: screenshot_server_url not "
+ "found in request.meta. This endpoint may not "
+ "support screenshots."
+ )
+ screenshot_auth_token: str | None = request.meta.get(
+ "screenshot_auth_token"
+ )
+
+ # Lazy-init the screenshot session (browser reuse).
+ if self._screenshot_session is None:
+ self._screenshot_session = _ScreenshotSession(
+ server_url,
+ screenshot_auth_token=screenshot_auth_token,
+ )
+
+ image = await self._screenshot_session.capture(
+ cell_id, timeout_ms=timeout_ms
+ )
+
+ if save_to is not None:
+ # Screenshot writes are infrequent and small; a sync write
+ # keeps the API simple without meaningful blocking cost.
+ Path(save_to).write_bytes(image) # noqa: ASYNC240
+
+ if as_data_url:
+ return _to_data_url(image)
+ return image
+
+ async def close_screenshot_session(self) -> None:
+ """Close the Playwright browser opened by :meth:`screenshot`.
+
+ Called automatically in ``__aexit__``. Call this explicitly
+ when using ``screenshot()`` outside ``async with`` to avoid
+ leaking a headless browser process.
+ """
+ if self._screenshot_session is not None:
+ try:
+ await self._screenshot_session.close()
+ except Exception:
+ LOGGER.debug(
+ "Failed to close screenshot session", exc_info=True
+ )
+ self._screenshot_session = None
+
+ def _resolve_screenshot_target(
+ self,
+ target: int | str | NotebookCell | None,
+ ) -> CellId_t:
+ """Resolve a screenshot *target* to a cell ID."""
+ from marimo._code_mode.screenshot import ScreenshotError
+
+ if target is None:
+ if len(self.cells) == 0:
+ raise ScreenshotError(
+ "Notebook has no cells. Create and run a cell first."
+ )
+ return self.cells[-1].id
+
+ if isinstance(target, bool):
+ # Guard before the ``int`` branch — ``bool`` subclasses
+ # ``int`` in Python, and ``ctx.screenshot(True)`` almost
+ # certainly reflects a caller mistake.
+ raise TypeError(
+ "screenshot target cannot be a bool; pass a cell ID, "
+ "cell name, integer index, or NotebookCell."
+ )
+
+ if isinstance(target, int):
+ try:
+ return self.cells[target].id
+ except IndexError as exc:
+ raise ScreenshotError(
+ f"Cell index {target} out of range "
+ f"(notebook has {len(self.cells)} cells)."
+ ) from exc
+
+ if isinstance(target, str):
+ try:
+ return self.cells._resolve(target)
+ except KeyError as exc:
+ raise ScreenshotError(
+ f"Unknown cell ID or name: {target!r}."
+ ) from exc
+
+ if isinstance(target, NotebookCell):
+ return target.id
+
+ raise TypeError(
+ f"Unsupported screenshot target type: {type(target).__name__}. "
+ "Pass a cell ID (str), cell name (str), integer index, "
+ "or NotebookCell."
+ )
+
+ def find_cell_defining_object(self, obj: Any) -> CellId_t | None:
+ """Return the cell ID whose ``defs`` include a variable bound to *obj*.
+
+ Uses identity (``is``) matching against kernel globals.
+ Returns ``None`` if no cell defines *obj*.
+
+ Example::
+
+ cell_id = ctx.find_cell_defining_object(chart)
+ if cell_id is not None:
+ image = await ctx.screenshot(cell_id)
+ """
+ globals_map = self.globals
+ names = [name for name, value in globals_map.items() if value is obj]
+ if not names:
+ return None
+
+ graph_cells = self.graph.cells
+
+ name_set = set(names)
+ for cell_id, cell_impl in graph_cells.items():
+ if name_set & getattr(cell_impl, "defs", set()):
+ return cell_id
+ return None
+
# ------------------------------------------------------------------
# Apply queued operations
# ------------------------------------------------------------------
diff --git a/marimo/_code_mode/screenshot.py b/marimo/_code_mode/screenshot.py
new file mode 100644
index 0000000000..3648dd5c5f
--- /dev/null
+++ b/marimo/_code_mode/screenshot.py
@@ -0,0 +1,413 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Headless Chromium screenshot session for cell outputs.
+
+Lazily launches a browser connected to the running notebook server
+in kiosk mode and reuses it across captures.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import time
+from typing import TYPE_CHECKING, Any
+
+from marimo import _loggers
+from marimo._server.export._pdf_raster import (
+ WAIT_FOR_NEXT_PAINT,
+ WAIT_FOR_PAGE_READY,
+)
+
+if TYPE_CHECKING:
+ from marimo._types.ids import CellId_t
+
+LOGGER = _loggers.marimo_logger()
+
+_READINESS_TIMEOUT_MS = 90_000
+_NETWORK_IDLE_TIMEOUT_MS = 10_000
+_VIEWPORT_WIDTH = 1440
+_VIEWPORT_HEIGHT = 1000
+_DEVICE_SCALE_FACTOR = 2.0
+
+# Minimum slice of `timeout_ms` budget to spend looking for the cell
+# container in the DOM. If the container never attaches, we fail fast
+# with a clear error (rather than letting the locator consume the full
+# user-provided timeout on a branch that will never succeed).
+_ATTACH_TIMEOUT_MS = 5_000
+
+# When the container exists but we're probing selector variants for the
+# output element, each candidate selector gets a short wait before we
+# move on to the next one.
+_SELECTOR_PROBE_TIMEOUT_MS = 1_000
+
+
+def _suppress() -> Any:
+ """contextlib.suppress(Exception) without the import."""
+ import contextlib
+
+ return contextlib.suppress(Exception)
+
+
+class ScreenshotError(RuntimeError):
+ """A cell screenshot could not be captured.
+
+ Messages include actionable hints (available cell IDs,
+ install commands, likely misconfigurations).
+ """
+
+
+def _to_data_url(image: bytes) -> str:
+ """Convert raw PNG bytes to a ``data:image/png;base64,...`` string."""
+ encoded = base64.b64encode(image).decode("ascii")
+ return f"data:image/png;base64,{encoded}"
+
+
+def _require_playwright() -> Any:
+ """Import ``async_playwright``, raising :class:`ScreenshotError` if missing."""
+ from marimo._dependencies.dependencies import DependencyManager
+
+ if not DependencyManager.playwright.has():
+ raise ScreenshotError(
+ "Playwright is not installed.\n"
+ "Fix:\n"
+ " 1. pip install playwright\n"
+ " 2. python -m playwright install chromium"
+ )
+
+ from playwright.async_api import ( # type: ignore[import-not-found]
+ async_playwright,
+ )
+
+ return async_playwright
+
+
+def _raise_browser_missing(err: Exception) -> None:
+ """Raise :class:`ScreenshotError` for a missing Chromium binary."""
+ raise ScreenshotError(
+ "Chromium browser binary is not installed.\n"
+ "Fix: python -m playwright install chromium\n"
+ f"Underlying error: {err}"
+ ) from err
+
+
+class _ScreenshotSession:
+ """Reusable Playwright browser session for cell screenshots.
+
+ Lazily launches on first :meth:`capture`, reuses across calls.
+ Call :meth:`close` to release resources.
+ """
+
+ def __init__(
+ self, server_url: str, screenshot_auth_token: str | None = None
+ ) -> None:
+ self._server_url = server_url
+ self._screenshot_auth_token = screenshot_auth_token
+ self._playwright: Any = None
+ self._browser: Any = None
+ self._page: Any = None
+ self._init_lock = asyncio.Lock()
+
+ async def _ensure_ready(self) -> None:
+ """Launch browser and navigate to the notebook if not already done."""
+ if self._page is not None:
+ return
+
+ async with self._init_lock:
+ # Re-check after acquiring the lock.
+ if self._page is not None:
+ return
+ await self._init_browser()
+
+ async def _init_browser(self) -> None:
+ """Start Playwright + Chromium and navigate to the kiosk page.
+
+ On failure, any partially-created resources are cleaned up
+ before re-raising.
+ """
+ async_playwright = _require_playwright()
+
+ LOGGER.debug("Screenshot session: launching browser")
+ pw = await async_playwright().start()
+ browser: Any = None
+ page: Any = None
+ try:
+ try:
+ browser = await pw.chromium.launch()
+ except Exception as err:
+ msg = str(err).lower()
+ if (
+ "executable doesn't exist" in msg
+ or "looks like playwright" in msg
+ ):
+ _raise_browser_missing(err)
+ raise
+
+ context = await browser.new_context(
+ viewport={
+ "width": _VIEWPORT_WIDTH,
+ "height": _VIEWPORT_HEIGHT,
+ },
+ device_scale_factor=_DEVICE_SCALE_FACTOR,
+ )
+ page = await context.new_page()
+ await page.emulate_media(reduced_motion="reduce")
+
+ # Commit only after full success.
+ self._playwright = pw
+ self._browser = browser
+ self._page = page
+ await self._navigate(initial=True)
+ LOGGER.debug("Screenshot session: ready")
+ except BaseException:
+ # Clean up partially-created resources.
+ if browser is not None:
+ with _suppress():
+ await browser.close()
+ with _suppress():
+ await pw.stop()
+ raise
+
+ async def _navigate(self, *, initial: bool) -> None:
+ """Navigate (initial=True) or reload (initial=False) the kiosk page."""
+ assert self._page is not None
+
+ params = "kiosk=true"
+ if self._screenshot_auth_token:
+ params += f"&access_token={self._screenshot_auth_token}"
+ page_url = f"{self._server_url}?{params}"
+ if initial:
+ LOGGER.debug(
+ "Screenshot session: navigating to %s", self._server_url
+ )
+ await self._page.goto(page_url, wait_until="domcontentloaded")
+ else:
+ LOGGER.debug("Screenshot session: reloading page")
+ await self._page.reload(wait_until="domcontentloaded")
+
+ try:
+ await self._page.wait_for_function(
+ WAIT_FOR_PAGE_READY, timeout=_READINESS_TIMEOUT_MS
+ )
+ except Exception:
+ LOGGER.warning(
+ "Screenshot session: page readiness check timed out"
+ )
+
+ try:
+ await self._page.wait_for_load_state(
+ "networkidle", timeout=_NETWORK_IDLE_TIMEOUT_MS
+ )
+ except Exception:
+ pass
+
+ async def capture(
+ self,
+ cell_id: CellId_t,
+ *,
+ timeout_ms: int = 30_000,
+ ) -> bytes:
+ """Screenshot a cell's output and return PNG bytes.
+
+ Raises :class:`ScreenshotError` if the cell container is
+ missing, has no content, or no output element becomes visible.
+ """
+ await self._ensure_ready()
+ assert self._page is not None
+
+ LOGGER.debug("Screenshot: capturing cell %s", cell_id)
+
+ # Step 1: find the cell container in the DOM. The page is
+ # cached, so if a cell was added after launch we reload once.
+ container_selector = f"#output-{cell_id}"
+ attach_timeout = min(_ATTACH_TIMEOUT_MS, timeout_ms)
+ try:
+ await self._wait_for_container(
+ container_selector, timeout=attach_timeout
+ )
+ except Exception:
+ LOGGER.debug(
+ "Screenshot: container %s missing, reloading page once",
+ container_selector,
+ )
+ try:
+ await self._navigate(initial=False)
+ except Exception:
+ # If reload itself blows up, fall through to the
+ # original error path — we still want to surface the
+ # missing-container hints to the caller.
+ LOGGER.warning("Screenshot: page reload failed")
+ try:
+ await self._wait_for_container(
+ container_selector, timeout=attach_timeout
+ )
+ except Exception as err:
+ available = await self._list_cell_ids()
+ raise ScreenshotError(
+ self._format_missing_container_error(cell_id, available)
+ ) from err
+
+ # Step 2: container exists but may be empty (cell not run, or
+ # returned None).
+ if not await self._container_has_content(container_selector):
+ raise ScreenshotError(
+ f"Cell {cell_id!r} has no rendered content.\n"
+ "Fix: run the cell first (`ctx.run_cell(...)`) and "
+ "ensure its last expression is not None."
+ )
+
+ # Step 3: resolve the screenshottable element via prioritised
+ # selector list (.output, .vega-embed, .plotly, etc.).
+ target = await self._resolve_output_locator(
+ container_selector, timeout_ms=timeout_ms
+ )
+
+ await target.scroll_into_view_if_needed(timeout=timeout_ms)
+ await self._page.evaluate(WAIT_FOR_NEXT_PAINT)
+ image: bytes = await target.screenshot(
+ type="png",
+ animations="disabled",
+ timeout=timeout_ms,
+ )
+ LOGGER.debug(
+ "Screenshot: captured cell %s (%d bytes)", cell_id, len(image)
+ )
+ return image
+
+ async def _resolve_output_locator(
+ self,
+ container_selector: str,
+ *,
+ timeout_ms: int,
+ ) -> Any:
+ """Return the first visible locator from a prioritised selector list."""
+ assert self._page is not None
+
+ # Most-specific → most-general, then the container itself.
+ candidates: list[str] = [
+ f"{container_selector} > .output",
+ f"{container_selector} > .vega-embed",
+ f"{container_selector} > .plotly",
+ f"{container_selector} > .anywidget",
+ f"{container_selector} > div",
+ container_selector,
+ ]
+
+ # Track a hard deadline so total probing never exceeds timeout_ms.
+ deadline = time.monotonic() + timeout_ms / 1000.0
+
+ last_error: Exception | None = None
+ for selector in candidates:
+ remaining_ms = max(0, int((deadline - time.monotonic()) * 1000))
+ if remaining_ms == 0:
+ break
+ probe = min(_SELECTOR_PROBE_TIMEOUT_MS, remaining_ms)
+ locator = self._page.locator(selector).first
+ try:
+ await locator.wait_for(state="visible", timeout=probe)
+ LOGGER.debug(
+ "Screenshot: resolved output via selector %s", selector
+ )
+ return locator
+ except Exception as err:
+ last_error = err
+ continue
+
+ # Every candidate failed.
+ dom_snapshot = await self._describe_container(container_selector)
+ raise ScreenshotError(
+ f"No visible output element under {container_selector!r}.\n"
+ f"Tried: {candidates}\n"
+ f"Container: {dom_snapshot}\n"
+ "Fix: increase `timeout_ms`, or ensure the output is "
+ "not hidden (display:none)."
+ ) from last_error
+
+ async def _wait_for_container(
+ self, container_selector: str, *, timeout: int
+ ) -> None:
+ """Wait for a cell output container to attach to the DOM."""
+ assert self._page is not None
+ await self._page.locator(container_selector).first.wait_for(
+ state="attached", timeout=timeout
+ )
+
+ async def _list_cell_ids(self) -> list[str]:
+ """Return the cell IDs currently rendered on the page."""
+ assert self._page is not None
+ try:
+ ids: list[str] = await self._page.eval_on_selector_all(
+ "[id^='output-']",
+ "els => els.map(e => e.id.replace(/^output-/, ''))",
+ )
+ return ids
+ except Exception:
+ return []
+
+ async def _container_has_content(self, container_selector: str) -> bool:
+ """Whether the cell container has any rendered children."""
+ assert self._page is not None
+ try:
+ return bool(
+ await self._page.eval_on_selector(
+ container_selector,
+ "el => el.children.length > 0 "
+ "|| el.textContent.trim().length > 0",
+ )
+ )
+ except Exception:
+ return False
+
+ async def _describe_container(self, container_selector: str) -> str:
+ """Human-readable snapshot of the container for error messages."""
+ assert self._page is not None
+ try:
+ info = await self._page.eval_on_selector(
+ container_selector,
+ """el => ({
+ childCount: el.children.length,
+ firstChildTag: el.children[0]?.tagName ?? null,
+ firstChildClass: el.children[0]?.className ?? null,
+ innerLen: el.innerHTML.length,
+ visible: el.offsetParent !== null,
+ })""",
+ )
+ return str(info)
+ except Exception as err:
+ return f"<failed to inspect container: {err}>"
+
+ @staticmethod
+ def _format_missing_container_error(
+ cell_id: CellId_t, available: list[str]
+ ) -> str:
+ """Compose the error raised when the cell container is absent."""
+ if available:
+ # Keep the list digestible when there are many cells.
+ shown = available[:20]
+ truncated = (
+ f" (+{len(available) - len(shown)} more)"
+ if len(available) > len(shown)
+ else ""
+ )
+ available_line = f"Cells currently on the page: {shown}{truncated}"
+ else:
+ available_line = (
+ "No cell output containers are on the page at all."
+ )
+ return (
+ f"Cell {cell_id!r} not found on the page.\n"
+ f"{available_line}\n"
+ "Fix: verify the cell ID/name/index, and ensure the "
+ "context manager has exited (which flushes new cells "
+ "to the frontend)."
+ )
+
+ async def close(self) -> None:
+ """Release browser resources."""
+ if self._browser is not None:
+ await self._browser.close()
+ self._browser = None
+ if self._playwright is not None:
+ await self._playwright.stop()
+ self._playwright = None
+ self._page = None
+ LOGGER.debug("Screenshot session: closed")
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index 74dda0c48d..638585f86e 100644
--- a/marimo/_server/api/endpoints/execution.py
+++ b/marimo/_server/api/endpoints/execution.py
@@ -301,10 +301,24 @@ async def execute_code(
listener = ScratchCellListener()
with session.scoped(listener):
async with session.scratchpad_lock:
+ http_req = HTTPRequest.from_request(request)
+ # Inject trusted server URL and auth token for
+ # code-mode screenshot support. We use the
+ # server's own host/port (from config) rather
+ # than the request's Host header to prevent
+ # header-spoofing attacks.
+ http_req.meta["screenshot_auth_token"] = str(
+ app_state.session_manager.auth_token
+ )
+ base_url = app_state.base_url.rstrip("/")
+ scheme = request.url.scheme or "http"
+ http_req.meta["screenshot_server_url"] = (
+ f"{scheme}://{app_state.host}:{app_state.port}{base_url}"
+ )
session.put_control_request(
ExecuteScratchpadCommand(
code=body.code,
- request=HTTPRequest.from_request(request),
+ request=http_req,
notebook_cells=tuple(session.document.cells),
),
from_consumer_id=None,
diff --git a/tests/_code_mode/test_screenshot.py b/tests/_code_mode/test_screenshot.py
new file mode 100644
index 0000000000..06718de3d7
--- /dev/null
+++ b/tests/_code_mode/test_screenshot.py
@@ -0,0 +1,183 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import base64
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import pytest
+
+from marimo._ast.cell import CellConfig
+from marimo._code_mode._context import (
+ AsyncCodeModeContext,
+ NotebookCell,
+)
+from marimo._code_mode.screenshot import (
+ ScreenshotError,
+ _ScreenshotSession,
+ _to_data_url,
+)
+from marimo._messaging.notebook.document import (
+ NotebookCell as _DocNotebookCell,
+)
+from marimo._types.ids import CellId_t
+
+if TYPE_CHECKING:
+ from typing import Any
+
+
+class TestToDataUrl:
+ def test_round_trip(self) -> None:
+ payload = b"\x89PNG\r\n\x1a\n"
+ result = _to_data_url(payload)
+ assert result.startswith("data:image/png;base64,")
+ decoded = base64.b64decode(result.split(",", 1)[1])
+ assert decoded == payload
+
+ def test_empty(self) -> None:
+ result = _to_data_url(b"")
+ assert result == "data:image/png;base64,"
+
+
+class TestScreenshotSessionAuthUrl:
+ def test_url_without_auth(self) -> None:
+ session = _ScreenshotSession("http://localhost:1234")
+ assert session._server_url == "http://localhost:1234"
+ assert session._screenshot_auth_token is None
+
+ def test_url_with_auth(self) -> None:
+ session = _ScreenshotSession(
+ "http://localhost:1234", screenshot_auth_token="tok123"
+ )
+ assert session._screenshot_auth_token == "tok123"
+
+ def test_page_url_includes_screenshot_auth_token(self) -> None:
+ """The kiosk page URL must include the access_token query param."""
+ session = _ScreenshotSession(
+ "http://localhost:9999", screenshot_auth_token="secret"
+ )
+ # Replicate the URL-building logic from _ensure_ready.
+ params = "kiosk=true"
+ if session._screenshot_auth_token:
+ params += f"&access_token={session._screenshot_auth_token}"
+ page_url = f"{session._server_url}?{params}"
+
+ assert "access_token=secret" in page_url
+ assert "kiosk=true" in page_url
+
+ def test_page_url_omits_token_when_none(self) -> None:
+ session = _ScreenshotSession("http://localhost:9999")
+ params = "kiosk=true"
+ if session._screenshot_auth_token:
+ params += f"&access_token={session._screenshot_auth_token}"
+ page_url = f"{session._server_url}?{params}"
+
+ assert "access_token" not in page_url
+ assert page_url == "http://localhost:9999?kiosk=true"
+
+
+class _FakeCells:
+ """Minimal stand-in for ``_CellsView`` used by the resolver tests.
+
+ Supports the operations ``_resolve_screenshot_target`` actually
+ calls — ``__len__``, integer indexing, and ``_resolve(str)`` — so
+ the resolver can run without a live kernel/document.
+ """
+
+ def __init__(
+ self,
+ cell_ids: list[str],
+ names: dict[str, str] | None = None,
+ ) -> None:
+ self._ids = [CellId_t(cid) for cid in cell_ids]
+ self._names = names or {}
+
+ def __len__(self) -> int:
+ return len(self._ids)
+
+ def __getitem__(self, idx: int) -> Any:
+ return SimpleNamespace(id=self._ids[idx])
+
+ def _resolve(self, target: str) -> CellId_t:
+ if target in self._ids:
+ return CellId_t(target)
+ for cid, name in self._names.items():
+ if name == target:
+ return CellId_t(cid)
+ raise KeyError(target)
+
+
+def _fake_ctx(cell_ids: list[str], names: dict[str, str] | None = None) -> Any:
+ """Build an object usable as ``self`` for the resolver method."""
+ return SimpleNamespace(cells=_FakeCells(cell_ids, names))
+
+
+def _resolve(ctx: Any, target: Any) -> CellId_t:
+ return AsyncCodeModeContext._resolve_screenshot_target(ctx, target)
+
+
+class TestResolveScreenshotTarget:
+ def test_none_with_empty_notebook_raises(self) -> None:
+ with pytest.raises(ScreenshotError, match="no cells"):
+ _resolve(_fake_ctx([]), None)
+
+ def test_none_returns_last_cell(self) -> None:
+ ctx = _fake_ctx(["cell-a", "cell-b", "cell-c"])
+ assert _resolve(ctx, None) == CellId_t("cell-c")
+
+ def test_bool_raises_type_error(self) -> None:
+ # ``bool`` is a subclass of ``int``; guard before the int branch
+ # so ``ctx.screenshot(True)`` surfaces as a caller mistake.
+ ctx = _fake_ctx(["cell-a"])
+ with pytest.raises(TypeError, match="bool"):
+ _resolve(ctx, True)
+ with pytest.raises(TypeError, match="bool"):
+ _resolve(ctx, False)
+
+ def test_int_positive_index(self) -> None:
+ ctx = _fake_ctx(["cell-a", "cell-b", "cell-c"])
+ assert _resolve(ctx, 0) == CellId_t("cell-a")
+ assert _resolve(ctx, 1) == CellId_t("cell-b")
+
+ def test_int_negative_index(self) -> None:
+ ctx = _fake_ctx(["cell-a", "cell-b", "cell-c"])
+ assert _resolve(ctx, -1) == CellId_t("cell-c")
+ assert _resolve(ctx, -3) == CellId_t("cell-a")
+
+ def test_int_out_of_range_raises(self) -> None:
+ ctx = _fake_ctx(["cell-a"])
+ with pytest.raises(ScreenshotError, match="out of range"):
+ _resolve(ctx, 5)
+ with pytest.raises(ScreenshotError, match="out of range"):
+ _resolve(ctx, -2)
+
+ def test_str_resolves_cell_id(self) -> None:
+ ctx = _fake_ctx(["cell-a", "cell-b"])
+ assert _resolve(ctx, "cell-a") == CellId_t("cell-a")
+
+ def test_str_resolves_cell_name(self) -> None:
+ ctx = _fake_ctx(["cell-a", "cell-b"], names={"cell-b": "my_cell"})
+ assert _resolve(ctx, "my_cell") == CellId_t("cell-b")
+
+ def test_str_unknown_raises(self) -> None:
+ ctx = _fake_ctx(["cell-a"])
+ with pytest.raises(ScreenshotError, match="Unknown cell ID or name"):
+ _resolve(ctx, "does-not-exist")
+
+ def test_notebook_cell_target(self) -> None:
+ doc_cell = _DocNotebookCell(
+ id=CellId_t("cell-x"),
+ code="x = 1",
+ name="",
+ config=CellConfig(),
+ )
+ nb_cell = NotebookCell(doc_cell, cell_impl=None)
+ ctx = _fake_ctx(["cell-a"]) # cell-x deliberately not in view
+ assert _resolve(ctx, nb_cell) == CellId_t("cell-x")
+
+ def test_unsupported_type_raises(self) -> None:
+ ctx = _fake_ctx(["cell-a"])
+ with pytest.raises(TypeError, match="Unsupported"):
+ _resolve(ctx, 3.14)
+ with pytest.raises(TypeError, match="Unsupported"):
+ _resolve(ctx, object())
diff --git a/tests/_server/api/endpoints/test_execution.py b/tests/_server/api/endpoints/test_execution.py
index adce1b573a..8d5e28be7a 100644
--- a/tests/_server/api/endpoints/test_execution.py
+++ b/tests/_server/api/endpoints/test_execution.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import json
import sys
import time
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
import pytest
@@ -159,6 +159,58 @@ class TestExecutionRoutes_EditMode:
assert response.headers["content-type"] == "application/json"
assert "success" in response.json()
+ @staticmethod
+ @with_session(SESSION_ID)
+ def test_execute_injects_screenshot_meta(client: TestClient) -> None:
+ """`/api/kernel/execute` injects a trusted server URL + auth token
+ into ``HTTPRequest.meta`` so ``ctx.screenshot()`` can authenticate
+ Playwright against this server. Regression guard: deleting either
+ injection line in the endpoint should fail this test.
+ """
+ from unittest.mock import patch
+
+ from marimo._runtime.commands import ExecuteScratchpadCommand
+ from marimo._server import scratchpad as scratchpad_mod
+
+ session = get_session_manager(client).get_session(SESSION_ID)
+ assert session is not None
+
+ captured: list[object] = []
+
+ def capture(req: object, from_consumer_id: object) -> None: # noqa: ARG001
+ captured.append(req)
+
+ async def empty_stream(self: object): # noqa: ARG001
+ if False:
+ yield "" # makes this an async generator that yields nothing
+
+ with (
+ patch.object(session, "put_control_request", side_effect=capture),
+ patch.object(
+ scratchpad_mod.ScratchCellListener,
+ "stream",
+ empty_stream,
+ ),
+ ):
+ response = client.post(
+ "/api/kernel/execute",
+ headers=HEADERS,
+ json={"code": "x = 1"},
+ )
+
+ assert response.status_code == 200, response.text
+
+ scratchpad_cmds = [
+ c for c in captured if isinstance(c, ExecuteScratchpadCommand)
+ ]
+ assert len(scratchpad_cmds) == 1, (
+ f"expected one ExecuteScratchpadCommand, got {captured!r}"
+ )
+ meta = scratchpad_cmds[0].request.meta
+ assert meta["screenshot_auth_token"] == "fake-token"
+ # Mock server uses host="localhost", port=1234, base_url=""
+ assert meta["screenshot_server_url"] == "http://localhost:1234"
+
@staticmethod
@with_session(SESSION_ID)
def test_takeover_no_file_key(client: TestClient) -> None:
@@ -399,7 +451,7 @@ class TestExecutionRoutes_RunMode:
def get_printed_object(
client: TestClient, cell_id: CellId_t
-) -> dict[str, Any]:
+) -> dict[str, object]:
session = get_session_manager(client).get_session(SESSION_ID)
assert session