The live-Viron validation anchor cannot be run in a headless/containerized environment

[dmccoystephenson]

Observation

The project's validation story for anything touching the render loop is a manual run against a live Viron server on http://localhost:9999, as described in the README's "Starting Viron" section. That anchor cannot be satisfied in a headless or containerized checkout, for two independent reasons:

1. Docker is not reachable. up.bat and its documented docker compose -f Viron/compose.yml up -d --build equivalent are the only supported way to start Viron. In a WSL/container checkout without Docker Desktop integration, docker resolves to a shim that reports The command 'docker' could not be found in this WSL 2 distro.
2. Viron cannot be imported below Python 3.10. main.py imports Viron's EnvironmentService and LocationService. Those modules annotate with PEP 585 generics, for example def get_all_environments(self) -> list[Environment]: in Viron/src/main/python/preponderous/viron/services/environmentService.py. On Python 3.8 the import fails at class-definition time with TypeError: 'type' object is not subscriptable. The README already states a 3.10+ prerequisite, so this is expected rather than a defect — but it means the anchor additionally depends on the interpreter version, not only on Docker.

There is also no display, so pygame.display.set_mode raises pygame.error: No available video device unless SDL_VIDEODRIVER=dummy is set.

Consequence

Any change to main.py's render loop or its service call sites is unverifiable by the project's own stated anchor in such an environment. The change can still be exercised — PR #23 substituted a mocked unittest suite plus a headless run under SDL_VIDEODRIVER=dummy with the Viron services stubbed, which drove the real RenderWindow, real Graphik and real pygame — but that substitute is assembled ad hoc per change rather than being something a reviewer can re-run from the repository. The result is that such PRs terminate in a hand-off for manual confirmation rather than in a verified merge, regardless of the quality of the change.

Suggested resolutions

These are complementary rather than alternatives:

• Land Add CI to run the unit test suite on pull requests #17. Running python -m unittest discover -s tests on pull requests would give a reproducible, reviewable green signal for everything the mocked suite covers, which is the larger part of what currently has to be re-established by hand each time.
• Commit the headless harness. A checked-in script that sets SDL_VIDEODRIVER=dummy, registers stub Viron services in sys.modules and drives main() end to end would turn the ad hoc substitute into something reviewers and CI can both run. The harness written for PR Make main.py importable and cap its render loop #23 measured the render loop at roughly 58 frames per second against its 60 cap, which is the kind of evidence that is worth being able to reproduce on demand.
• Document a non-Windows path for starting Viron. The README gives the docker compose equivalents already; a note on what to do when Docker is unavailable, or a lightweight fake Viron server for local use, would close the remaining gap.

Acceptance criteria

• A contributor without Docker and without a display can run a documented command that meaningfully exercises main.py, and the command is recorded in the README.

This issue body was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson