run-app

name	run-app
description	Launch the DigitalSreeni Image Annotator headlessly and run its smoke tests. Use when asked to run/launch the app, verify it starts after a change, or check for import/startup errors in a display-less (web/CI) session.

Run the app headlessly + smoke tests

This is a PyQt6 GUI app; sessions without a display must use Qt's offscreen platform plugin. GUI interaction is impossible offscreen — a clean launch proves imports, window construction, and signal wiring, nothing more.

Launch check (no display)

QT_QPA_PLATFORM=offscreen timeout 10 python -m src.digitalsreeni_image_annotator.main

• Exit code 124 (timeout killed it) = SUCCESS: the app started and stayed up.
• Any traceback before the timeout = startup failure; fix before proceeding.
• Installed entry points work the same way: timeout 10 digitalsreeni-image-annotator / sreeni.

Smoke tests (always run after code changes)

pytest tests/integration/test_smoke.py -v

Includes the AST-based inline-import gate (ADR-016) — a "clean-looking" launch alone is NOT sufficient after moving modules. Full suite: pytest tests/ -v.

Linux runtime deps

If Qt fails to load its platform plugin, install the Qt6 runtime set (Debian/Ubuntu): libxcb-cursor0 libegl1 libgl1 libxcb-xinerama0 libxkbcommon-x11-0 (see .github/workflows/tests.yml for the full CI list).

Limits

Do not claim GUI behaviour (rendering, dark mode, mouse interaction) was "verified" from an offscreen launch — say so explicitly and fall back to the test suite or ask the user to check visually.