Gäld — Docker Test Environment for Playwright

Run the full annual procedure test suite against an isolated local Docker stack, without touching production and without manual email verification.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                    Docker test stack                          │
│                                                              │
│  ┌────────────┐  ┌─────────┐  ┌─────────┐  ┌────────────┐  │
│  │  Laravel    │  │ Postgres│  │  Redis  │  │  Mailpit   │  │
│  │  app-test   │  │ 16-alp  │  │ 7-alp  │  │  (email)   │  │
│  │  :8080      │  │ :5433   │  │ :6380  │  │  :8025 UI  │  │
│  └────────────┘  └─────────┘  └─────────┘  └────────────┘  │
└──────────────────────────────────────────────────────────────┘
         ▲
         │ http://localhost:8080
         │
┌────────┴───────┐
│   Playwright   │
│  (host machine)│
└────────────────┘

Quick Start

# 1. Start Docker stack + provision database + create test user
./scripts/test-setup.sh

# 2. Run the annual procedure test suite
cd web
npm run test:annual:docker

# 3. Tear down (wipes all data)
./scripts/test-setup.sh --down

What test-setup.sh Does

1. Starts Docker containers — PostgreSQL, Redis, Mailpit, Laravel app
2. Installs Composer dependencies (if not already present)
3. Runs database migrations — fresh schema
4. Runs gaeld:install — creates admin user + organization + seeds chart of accounts & VAT rates
5. Creates a test user (test@gaeld-test.ch) with pre-verified email, attached to the organization

Benefits vs. Production Testing

Aspect	Production (app.gaeld.ch)	Docker (localhost:8080)
Rate limiting	5 POST/min on /login, /register	Disabled (APP_ENV=testing)
Email verification	Manual (click inbox link or run SQL)	Pre-verified (install command)
Registration	Required every run (unique email)	Skipped (pre-created user)
Data isolation	Shared with real users	Fully isolated
Reset	Manual cleanup	./scripts/test-setup.sh --reset
Speed	~7 min (includes 30s email wait)	~5 min (no email wait)
CI-ready	No (requires human for email)	Yes

Commands

# First run
./scripts/test-setup.sh

# Reset everything (wipe DB, recreate user)
./scripts/test-setup.sh --reset

# Tear down containers & volumes
./scripts/test-setup.sh --down

# Run tests headless (CI)
cd web && TEST_ENV=docker npx playwright test --project=annual-procedure

# Run tests with visible browser
cd web && TEST_ENV=docker npx playwright test --project=annual-procedure --headed

# View Mailpit (all caught emails)
open http://localhost:8025

# Connect to test database
psql -h localhost -p 5433 -U gaeld_test -d gaeld_test  # password: testing

Environment Variables

Variable	Default	Description
TEST_ENV	(unset)	Set to docker to use Docker URLs and skip registration
APP_URL	http://localhost:8080 (when TEST_ENV=docker)	Override the app URL
TEST_EMAIL	test@gaeld-test.ch (Docker) / procedure-{timestamp}@gaeld-test.ch (prod)	Test user email
TEST_PASSWORD	Pr0cedure!Test2025#Secure	Test user password

File Structure

docker-compose.test.yml        # Docker Compose for test stack
scripts/test-setup.sh          # Automated setup script
api/
  app/Http/Middleware/
    DisableThrottleInTesting.php  # Bypasses rate limiting when APP_ENV=testing
  bootstrap/app.php              # Registers throttle bypass in testing env
web/
  playwright.config.ts           # TEST_ENV=docker → baseURL=localhost:8080
  tests/annual-procedure/
    fixtures/test-data.ts        # IS_DOCKER flag, fixed email in Docker mode
    00-registration.spec.ts      # Skips registration/verification in Docker mode

Troubleshooting

Container won't start: Check port conflicts — the test stack uses 8080, 5433, 6380, 8025.

"Already installed": The gaeld:install command only runs once. Use --reset to start fresh:

./scripts/test-setup.sh --reset

Tests still hit production: Make sure you're using npm run test:annual:docker or setting TEST_ENV=docker.

Need to inspect the database: Connect directly:

docker compose -f docker-compose.test.yml exec pgsql-test psql -U gaeld_test -d gaeld_test