feat: enable parallel pytest-xdist test execution with isolated per-worker databases and data directories

README.md

@@ -549,11 +549,14 @@ SQLite is synchronous by design and will never be made async. It is more than fa
 
 - **419 tests** across 34 files: Playwright integration + in-process unit tests
 - Playwright (NOT pytest-playwright plugin - conflicts, uninstall it)
-- Server starts as subprocess on port 10501 with isolated temp database
+- Runs in parallel via pytest-xdist (`make test` = `-n auto --dist loadfile`); each worker is an isolated uvicorn subprocess on port 10501+ with its own temp database and `DEVPLACE_DATA_DIR`
+- `loadfile` keeps every test in a file on one worker so session fixtures and ordering hold; cap workers with `make test TEST_WORKERS=4`
+- `make test-serial` runs everything in one process for debugging
 - Test users `alice_test` / `bob_test` seeded via HTTP at session start
 - Tests stop at first failure (`-x` flag)
 - Failure screenshots auto-save to `/tmp/devplace_test_screenshots/`
-- Headed mode: `PLAYWRIGHT_HEADLESS=0 make test`
+- Headed mode: `make test-headed` (parallel, one Chromium window per worker); `make test-headed-serial` for a single window
+- Cap headed windows the same way: `make test-headed TEST_WORKERS=2`
 
 ### Key test patterns
 
@@ -634,7 +637,7 @@ The app runs correctly under multiple Uvicorn workers (independent processes sha
 Gitea Actions workflow at `.gitea/workflows/test.yaml`:
 - Runs on push/PR to `master`
 - Sets up Python 3.13, installs dependencies + Playwright Chromium
-- Runs the full test suite under coverage (`coverage run -m pytest -p no:xdist`)
+- Runs the full test suite under coverage in parallel (`coverage run -m pytest -n auto --dist loadfile`); `.coveragerc` `parallel=true` lets the per-worker `.coverage.*` files combine
 - Builds and publishes the coverage HTML as an artifact on every run
 - Uploads failure screenshots as artifacts when a test fails