trainUs/tests/README.md

Test Suite

End-to-end tests for TrainUs using Playwright (Python) and pytest.

Setup (first time)

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

Running Tests

The Vite dev server starts automatically on port 5199 via the app_url fixture in conftest.py. It is stopped automatically when all tests finish.

Available commands (from project root)

Command	Browsers	Mode
npm run test	Firefox	Sequential
npm run test:chromium	Chromium	Sequential
npm run test:parallel	Firefox + Chromium	Parallel (all CPU cores)
npm run test:parallel:firefox	Firefox	Parallel (all CPU cores)
npm run test:parallel:chromium	Chromium	Parallel (all CPU cores)
npm run test:parallel:n	Firefox + Chromium	Parallel, N workers (WORKERS=N)

Running directly with pytest

# All tests, Firefox only
cd tests && .venv/bin/python -m pytest --browser firefox -v

# Single file, Firefox
cd tests && .venv/bin/python -m pytest test_step3_exercises.py --browser firefox -v

# Parallel via shell script
./tests/run_parallel.sh

# Parallel, Firefox only, 4 workers
PYTEST_WORKERS=4 PYTEST_BROWSERS="firefox" ./tests/run_parallel.sh

# Single file in parallel via shell script
./tests/run_parallel.sh test_step3_exercises.py

Browser Targets

• Firefox — primary browser; all tests must pass
• Chromium — secondary browser; all tests must also pass

File Naming Convention

test_step<N>_<feature_name>.py

Each file corresponds to one implementation step. Tests within a file cover both green paths (happy flow) and red paths (bad inputs, edge cases, error states).

Test Files

File	Feature	Tests
test_step0_scaffolding.py	App shell, navigation, i18n	5
test_step1_database.py	DB init, CRUD, persistence	15
test_step2_settings.py	Language, theme, name, DB export/restore	21
test_step2b_schema_hardening.py	UNIQUE constraints, suffix table	10
test_step3_exercises.py	Exercise CRUD, search, validation	17
test_step3b_exercise_export_import.py	JSON export/import, collisions, suffixes	23
test_step3c_backup.py	Backup filename, reminder, threshold	11
test_step4_combos.py	Combo CRUD, exercise ordering, reps/weight	19
test_step5_sessions.py	Session CRUD, items, reps/weight	20
test_step6_collections_home.py	Collections CRUD, home page stats	19
test_step7_import_export.py	Full multi-entity export/import	14
test_step8_execution.py	Execution mode, queue, partial logs	17
test_step9_stats.py	Statistics charts, streak, date range	16
test_step10_pwa.py	PWA manifest, install prompt, accessibility	11
test_step12_timers.py	EMOM/AMRAP/TABATA timers, pause/resume	20
test_step13_markdown.py	Markdown rendering in detail views	9
test_step14_form_shortcuts.py	Ctrl+Enter save, Escape cancel on forms	10
test_step15_audio_cues.py	TABATA/AMRAP audio cue timing (fake clock)	7
Total		264

Infrastructure

• conftest.py: Pytest fixtures. Starts the Vite dev server (npm run dev -- --port 5199) before the first test and stops it after all tests complete. Handles multiple concurrent workers safely using file locks.
• pytest.ini: Sets base_url = http://localhost:5199.
• run_parallel.sh: Shell wrapper for pytest-xdist parallel runs. Accepts PYTEST_WORKERS and PYTEST_BROWSERS environment variables.
• requirements.txt: playwright, pytest, pytest-playwright, pytest-xdist.