nat-as-server/TESTING.md

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:

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:

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

composer install
npm install
cd website && npm install && cd ..
npx playwright install

Test database key

Tests use a fixed master key (not for production):

QDB_MASTER_KEY=dGVzdC1tYXN0ZXIta2V5LXRoaXQtMzJieXRzIQ==

PHPUnit writes to tests/var/uploads/. Playwright and manual E2E seed uploads/ via:

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):

npm run test

Alias: npm run test:all.

PHP (unit + integration)

composer test

Integration tests reset the database before each test method (isolated state; slightly slower).

Website unit (Vitest)

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.

npm run test:e2e

Continuous integration (Gitea Actions)

Workflow: .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:

   [actions]
   ENABLED = true
   

2. Register an 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:

   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:

npm run test:e2e:ui

Manual development server

# 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/.

Layout

.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)