just testing the environment

TESTING.md

@@ -0,0 +1,146 @@
+# Testing
+
+Automated tests cover the PHP API (`api/`, `handlers/`), shared libraries, and the admin SPA in `website/`. Legacy root PHP scripts and duplicate `api/*.php` files are **not** tested.
+
+## Requirements
+
+- **PHP 8.x** with extensions: `pdo_sqlite`, `openssl`, `json`
+- **Composer**
+- **Node.js 20+** and npm
+
+### PHP: enable SQLite (Windows)
+
+If `composer test` fails with `PDOException: could not find driver`, PDO has no SQLite driver loaded. Check:
+
+```powershell
+php -r "print_r(PDO::getAvailableDrivers());"
+```
+
+You should see `sqlite` in the list. If not, edit the `php.ini` shown by `php --ini` and uncomment:
+
+```ini
+extension=pdo_sqlite
+extension=sqlite3
+```
+
+Restart the terminal, then run the check again. Winget’s PHP package uses a path like:
+
+`%LOCALAPPDATA%\Microsoft\WinGet\Packages\PHP.PHP.8.4_*\php.ini`
+
+## One-time setup
+
+```bash
+composer install
+npm install
+cd website && npm install && cd ..
+npx playwright install
+```
+
+## Test database key
+
+Tests use a fixed master key (not for production):
+
+```text
+QDB_MASTER_KEY=dGVzdC1tYXN0ZXIta2V5LXRoaXQtMzJieXRzIQ==
+```
+
+PHPUnit writes to `tests/var/uploads/`. Playwright and manual E2E seed `uploads/` via:
+
+```bash
+php tests/bin/seed-test-db.php
+```
+
+### Seeded accounts
+
+| Username        | Password      | Role        |
+|-----------------|---------------|-------------|
+| testadmin       | testpass123   | admin       |
+| testsuper1      | testpass123   | supervisor  |
+| testcoach1      | testpass123   | coach       |
+| testmustchange  | testpass123   | coach (must change password on first login) |
+
+Sample questionnaire ID: `questionnaire_test_demo` (active, with question `q1`).
+
+## Run tests
+
+### All suites
+
+From the repository root (PHPUnit, Vitest, then Playwright):
+
+```bash
+npm run test
+```
+
+Alias: `npm run test:all`.
+
+### PHP (unit + integration)
+
+```bash
+composer test
+```
+
+Integration tests reset the database before **each** test method (isolated state; slightly slower).
+
+### Website unit (Vitest)
+
+```bash
+cd website && npm run test:unit
+```
+
+### End-to-end (Playwright)
+
+Starts `php -S 127.0.0.1:8080 dev-router.php`, seeds the DB, then runs HTTP smoke tests and website UI tests. Detailed API behaviour is covered by PHPUnit; Playwright API tests are smoke + password-change flow only.
+
+```bash
+npm run test:e2e
+```
+
+### Continuous integration (Gitea Actions)
+
+Workflow: [`.gitea/workflows/tests.yml`](.gitea/workflows/tests.yml) — same three steps on push and pull request (`CI=true` for E2E so the dev server is always started fresh).
+
+**Prerequisites on your Gitea instance:**
+
+1. **Enable Actions** in `app.ini`:
+   ```ini
+   [actions]
+   ENABLED = true
+   ```
+2. **Register an [act_runner](https://gitea.com/gitea/act_runner)** on a Linux host (needs Docker or host tools for Playwright system deps). Use a label that matches the workflow, e.g. `ubuntu-latest`:
+   ```bash
+   act_runner register --instance https://your-gitea.example --token <token>
+   act_runner daemon
+   ```
+3. **Enable Actions** on this repository (Settings → Actions).
+4. **Third-party actions** (`actions/checkout`, `setup-php`, `setup-node`) are fetched from GitHub by default (`DEFAULT_ACTIONS_URL = github`). On air-gapped instances, mirror those actions or switch the workflow to shell `apt`/`composer` installs.
+
+Gitea also reads `.github/workflows/` for migrated repos; this project uses **`.gitea/workflows/`** only to avoid duplicate runs.
+
+Interactive UI:
+
+```bash
+npm run test:e2e:ui
+```
+
+## Manual development server
+
+```bash
+# Optional: seed test data into uploads/
+php tests/bin/seed-test-db.php
+
+$env:QDB_MASTER_KEY="dGVzdC1tYXN0ZXIta2V5LXRoaXQtMzJieXRzIQ=="
+php -S 127.0.0.1:8080 dev-router.php
+```
+
+Open [http://127.0.0.1:8080/website/](http://127.0.0.1:8080/website/).
+
+## Layout
+
+```text
+.gitea/workflows/  Gitea Actions CI (tests.yml)
+tests/             PHPUnit (Unit/, Integration/, Support/)
+tests/fixtures/    schema.sql copy for tests
+website/tests/     Vitest unit tests
+e2e/api/           Playwright HTTP smoke tests (Android API)
+e2e/website/       Playwright browser tests (hash routes)
+```