yellow-bank-soal/TESTING_WALKTHROUGH.md

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:

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

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

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

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

Expected: no errors.

3.2 Model mapping smoke test

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

Expected output:

mappers_ok

3.3 Unit tests

.venv/bin/pytest -q

Expected: all tests pass.

4) Migration Checks

4.1 Confirm migration chain

.venv/bin/alembic history

Expected head:

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

4.2 Offline SQL generation (safe dry run)

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

.venv/bin/alembic upgrade head

Expected: upgrade completes without error.

5) API Smoke Test

Start app:

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

Then check:

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:

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.