Metadata-Version: 2.4
Name: caldarium
Version: 0.1.0
Summary: End-to-end GUI testing framework for Toga applications
Author-email: Andrew Elgert <andrew.elgert@gmail.com>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/elgertam/caldarium
Project-URL: Repository, https://github.com/elgertam/caldarium
Project-URL: Issues, https://github.com/elgertam/caldarium/issues
Keywords: testing,gui,toga,beeware,e2e
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Framework :: Pytest
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=13.0
Requires-Dist: anyio>=4.0.0
Provides-Extra: toga
Requires-Dist: toga>=0.4.0; extra == "toga"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: toga>=0.4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: briefcase>=0.4.4; extra == "dev"
Requires-Dist: tox>=4.0; extra == "dev"
Dynamic: license-file

# Caldarium

**End-to-end GUI testing for [Toga](https://toga.readthedocs.io/) 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`](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)

```bash
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:

```python
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.
