# End-to-End Tests

The e2e suite uses pytest plus Playwright. The preferred path is the containerized runner, which joins the same Docker Compose network as the web app and opens `http://web`.

## Containerized Run

```bash
docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d db api web
docker compose -f docker-compose.yml -f docker-compose.e2e.yml run --rm e2e
```

The e2e override sets `E2E_BASE_URL=http://web`, makes the web container generate relative API config for browser-side requests, and forces the API container to use an e2e-only Compose database.

The e2e database is a real MySQL server, but it is isolated from the normal dev database:

- DB container: `ppr_e2e_db`
- API container: `ppr_e2e_api`
- Web container: `ppr_e2e_web`
- Database name: `ppr_e2e`
- Volume: `pprdev_ppr_e2e_mysql_data`

The e2e DB image is plain `mysql:8.0`, so the API should see a fresh empty database and create schema through Alembic migrations instead of stamping an older `db-init` schema.

Authenticated tests are skipped unless credentials are supplied:

```bash
E2E_ADMIN_USERNAME=admin \
E2E_ADMIN_PASSWORD=admin123 \
docker compose -f docker-compose.yml -f docker-compose.e2e.yml run --rm e2e
```

## Rebuild The Test Image

```bash
docker compose -f docker-compose.yml -f docker-compose.e2e.yml build e2e
```

## Test Evidence

Containerized runs write evidence to `test-results/`:

- `test-results/e2e-report.html` for a human-readable report
- `test-results/e2e-junit.xml` for CI systems
- Playwright traces and screenshots on failures

If the report files are not owned by your host user, pass your UID/GID:

```bash
E2E_ARTIFACT_UID=$(id -u) \
E2E_ARTIFACT_GID=$(id -g) \
docker compose -f docker-compose.yml -f docker-compose.e2e.yml run --rm e2e
```

## Host Run

Running on the host is still supported for quick debugging if Python and Playwright are installed locally.

First-time host setup:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
pip install -r tests/e2e/requirements.txt
python -m playwright install --with-deps chromium
```

Run against a host-exposed web port:

```bash
E2E_BASE_URL=http://localhost:8082 pytest tests/e2e
```

Run authenticated host tests:

```bash
E2E_BASE_URL=http://localhost:8082 \
E2E_ADMIN_USERNAME=admin \
E2E_ADMIN_PASSWORD=admin123 \
pytest tests/e2e
```

## Adding Tests

Put browser specs in `tests/e2e/test_*.py`. Start with user-visible behavior and stable selectors:

- Navigate through the same URLs users open.
- Prefer roles and labels, such as `get_by_role()` and `get_by_label()`.
- Use API setup only when a test needs specific records to exist.
- Keep specs independent so they can run in any order.