Caldarium

End-to-end GUI testing for Toga applications.

Inspired by Detox, but built on a key insight: a Toga app under test is already running CPython, so the test client is a pure-Python agent running on the app's own event loop — not a foreign native client. This makes ~80% of the framework platform-independent; only the per-platform driver (native interaction) and launch orchestration differ.

Status: pre-alpha, under active rebuild. See caldarium-replan-2026.md for the architecture and roadmap. The previous implementation lives under legacy/ and is superseded.

Architecture (MVP)

Two components: the pytest host (runs a WebSocket server + the test API) and an in-app agent (asyncio tasks injected into the app). The host resolves elements against Toga's interface layer (app.widgets), and a per-platform driver performs real interactions (modelled on Toga's own backend test probes).

pytest host  ──WebSocket(JSON)──►  in-app agent (on the app's RubiconEventLoop)
  By/element/expect                  resolver (app.widgets) + cocoa driver

Develop & test (macOS)

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v        # launches the sample Toga app and drives it

The sample app lives in samples/calsample/. Tests target it via the caldarium fixture:

from caldarium import By, expect

async def test_counter(caldarium):
    app = await caldarium("calsample.app:main")
    await app.element(By.id("increment")).tap()
    await expect(app.element(By.id("count"))).to_have_text("Count: 1")

License

BSD 3-Clause.