# Yellow Bank Soal - Testing Walkthrough Guide

Date: 2026-03-31

This guide walks through local verification after the defect-fix batch:
- model mapping/FK fixes
- admin runtime gating and auth wiring
- query and normalization fixes
- migration baseline setup

## 1) Prerequisites

- Python 3.10+
- PostgreSQL (for integration/API tests)
- Redis (required when `ENABLE_ADMIN=true`)

## 2) Environment Setup

From project root:

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

Create `.env` from `.env.example` and set at minimum:

```env
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/irt_bank_soal
REDIS_URL=redis://localhost:6379/0
ENVIRONMENT=development

# Keep false unless explicitly testing admin:
ENABLE_ADMIN=false

# Required only when ENABLE_ADMIN=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=change-me
ADMIN_SESSION_EXPIRE_SECONDS=3600
```

## 3) Fast Checks (No DB Required)

### 3.1 Compile check

```bash
.venv/bin/python -m compileall -q app tests alembic
```

Expected: no errors.

### 3.2 Model mapping smoke test

```bash
.venv/bin/python - <<'PY'
from sqlalchemy.orm import configure_mappers
import app.models  # noqa: F401
configure_mappers()
print("mappers_ok")
PY
```

Expected output:

```text
mappers_ok
```

### 3.3 Unit tests

```bash
.venv/bin/pytest -q
```

Expected: all tests pass.

## 4) Migration Checks

### 4.1 Confirm migration chain

```bash
.venv/bin/alembic history
```

Expected head:

```text
<base> -> 20260331_000001 (head), initial schema
```

### 4.2 Offline SQL generation (safe dry run)

```bash
.venv/bin/alembic upgrade head --sql > /tmp/alembic_upgrade.sql
head -n 30 /tmp/alembic_upgrade.sql
```

Expected: SQL script containing `CREATE TABLE` for `websites`, `tryouts`, `users`, `items`, `sessions`, `tryout_stats`, `user_answers`.

### 4.3 Apply migration to DB (online)

```bash
.venv/bin/alembic upgrade head
```

Expected: upgrade completes without error.

## 5) API Smoke Test

Start app:

```bash
.venv/bin/uvicorn app.main:app --reload --port 8000
```

Then check:

```bash
curl -s http://127.0.0.1:8000/health | jq
```

Expected:
- `status` is `healthy` or `degraded` (if DB unavailable)
- API responds with JSON (no startup crash)

## 6) Admin Auth Test (Optional)

Only for explicit admin verification.

1. Ensure Redis is running.
2. Set:

```env
ENABLE_ADMIN=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=change-me
```

3. Start server and open:
- `http://127.0.0.1:8000/admin/login`

4. Validate:
- invalid credentials -> login page with error
- valid credentials -> redirect to admin dashboard
- logout -> access token removed and redirected to login

## 7) Regression Targets Checklist

- [ ] ORM mapper configuration succeeds (`mappers_ok`)
- [ ] normalization tests are assertion-based and passing
- [ ] cast-related query paths run without SQLAlchemy cast errors
- [ ] `avg_nn` in tryout comparison is derived from session NN aggregates
- [ ] admin endpoints are disabled when `ENABLE_ADMIN=false`
- [ ] admin login works only with configured credentials when enabled
- [ ] Alembic migration history and SQL generation are valid

## 8) Troubleshooting

- `ModuleNotFoundError`: use `.venv/bin/python` and `.venv/bin/pytest`.
- admin startup errors: verify `ENABLE_ADMIN`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`.
- Redis errors on admin login: ensure `REDIS_URL` is reachable.
- migration connection errors: verify `DATABASE_URL` and DB service availability.