147 lines
4.0 KiB
Markdown
147 lines
4.0 KiB
Markdown
# 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)
|
||
```
|