trainUs/scripts/screenshots/README.md

Screenshot scripts

Small, standalone Playwright (Python) scripts that drive the app in a browser to produce PNGs for visual investigations or documentation figures.

These are not tests — they contain no assertions. For the automated test suite, see tests/.

Prerequisites

• Playwright for Python installed (see tests/requirements.txt):

  pip install -r tests/requirements.txt
  python -m playwright install firefox chromium
  

• Vite dev server running on port 5199:

  npm run dev -- --port 5199 --strictPort
  

Running

# All pages, modals and dialogs (seeds DB automatically)
python scripts/screenshots/all_pages.py
python scripts/screenshots/all_pages.py --browser chromium
python scripts/screenshots/all_pages.py --width 390 --height 844   # mobile viewport
python scripts/screenshots/all_pages.py --out-dir /tmp/shots

# Exercise list only
python scripts/screenshots/exercise_list.py --help
python scripts/screenshots/exercise_list.py                       # Firefox, 1920x1080
python scripts/screenshots/exercise_list.py --browser chromium
python scripts/screenshots/exercise_list.py --width 2560 --height 1440
python scripts/screenshots/exercise_list.py --out /tmp/custom.png

Output location

By default, PNGs are written to tmp/ at the project root (which is gitignored). Override with --out PATH if you need a different location.

Conventions for new scripts

• One script per page/flow; name it after the page (e.g., exercise_list.py, combo_detail.py).
• Use argparse with at least these flags: --url, --browser, --width, --height, --out.
• Default the output to tmp/<script-name>-<browser>-<WxH>.png.
• Seed the database through the UI if the target page requires data; skip seeding when cards already exist so the script is idempotent.
• Keep the script free of assertions — if you want to verify behavior, add a test under tests/ instead.