Headless Testing¶

Playwright-based helpers for rendering and screenshotting viewers without a display. Used by the CI render-check job and available for local verification.

pip install "cesiumkit[testing]"
python -m playwright install chromium

The render helpers close the viewer when each render finishes. Construct a fresh equivalent Viewer when a test needs both a screenshot and render state.

testing ¶

Headless rendering helpers for tests and CI (optional playwright dep).

These helpers start the local viewer server, load the page in headless Chromium, and let you assert on render state or save screenshots. Each helper closes its viewer when finished; create an equivalent fresh viewer for a second render. They are what scripts/render_examples.py uses in CI and for the docs gallery.

Playwright is imported lazily, so import cesiumkit.testing is cheap even when it is not installed.

Functions:

Name	Description
`start_server`	Start `viewer.show()` in a background thread and return the server.
`serve`	Context manager yielding the served URL of a viewer.
`render_state`	Load the viewer headlessly and report how the scene initialized.
`render_screenshot`	Load the viewer, save a PNG screenshot to `path`, then close it.

start_server ¶

start_server(viewer: Any, port: int = 0) -> Any

Start viewer.show() in a background thread and return the server.

Raises RuntimeError if the server does not come up within ~10s.

serve ¶

serve(viewer: Any, port: int = 0) -> Iterator[str]

Context manager yielding the served URL of a viewer.

render_state ¶

render_state(
    viewer: Any,
    *,
    wait_ms: int = DEFAULT_WAIT_MS,
    viewport: dict[str, int] | None = None,
) -> dict[str, Any]

Load the viewer headlessly and report how the scene initialized.

Closes viewer before returning. Returns a dict with ok (viewer + globe initialized), tilesLoaded, imageryLayers, cesiumScript (the script URL as written in the page), and pageErrors (uncaught JS exceptions).

render_screenshot ¶

render_screenshot(
    viewer: Any,
    path: str,
    *,
    wait_ms: int = DEFAULT_WAIT_MS,
    viewport: dict[str, int] | None = None,
    screenshot_timeout_ms: int = 60000,
) -> str

Load the viewer, save a PNG screenshot to path, then close it.