Add required test suite and websocket fixes

app/room.py

@@ -594,28 +594,36 @@ class RoomManager:
 
     async def broadcast_question_closed(self, sid: str, question_idx: int) -> None:
         for websocket, identity in list(self.student_clients[sid].items()):
-            await self._safe_send(websocket, await self.question_closed_message(sid, question_idx, identity))
+            self._queue_send(websocket, await self.question_closed_message(sid, question_idx, identity))
         await self.broadcast_instructors(sid, await self.question_closed_message(sid, question_idx))
         await self.broadcast_instructors(sid, await self.full_leaderboard_message(sid))
+        await asyncio.sleep(0)
 
     async def broadcast_between_questions(self, sid: str, next_idx: int) -> None:
         for websocket, identity in list(self.student_clients[sid].items()):
-            await self._safe_send(websocket, await self.between_message(sid, next_idx, identity))
+            self._queue_send(websocket, await self.between_message(sid, next_idx, identity))
         await self.broadcast_instructors(sid, await self.between_message(sid, next_idx))
         await self.broadcast_instructors(sid, await self.full_leaderboard_message(sid))
+        await asyncio.sleep(0)
 
     async def broadcast_session_ended(self, sid: str) -> None:
         for websocket, identity in list(self.student_clients[sid].items()):
-            await self._safe_send(websocket, await self.ended_message(sid, identity))
+            self._queue_send(websocket, await self.ended_message(sid, identity))
         await self.broadcast_instructors(sid, await self.ended_message(sid))
+        await asyncio.sleep(0)
 
     async def broadcast_students(self, sid: str, message: dict[str, Any]) -> None:
         for websocket in list(self.student_clients[sid]):
-            await self._safe_send(websocket, message)
+            self._queue_send(websocket, message)
+        await asyncio.sleep(0)
 
     async def broadcast_instructors(self, sid: str, message: dict[str, Any]) -> None:
         for websocket in list(self.instructor_clients[sid]):
-            await self._safe_send(websocket, message)
+            self._queue_send(websocket, message)
+        await asyncio.sleep(0)
+
+    def _queue_send(self, websocket: WebSocket, message: dict[str, Any]) -> None:
+        asyncio.create_task(self._safe_send(websocket, message))
 
     async def _safe_send(self, websocket: WebSocket, message: dict[str, Any]) -> None:
         try:

tests/conftest.py

@@ -1 +1,94 @@
 """Test fixtures."""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.config import Settings
+from app.main import create_app
+
+
+@pytest.fixture
+def sample_pool():
+    return {
+        "title": "Sample Quiz",
+        "score_fn": "linear_decay",
+        "time_limit_default": 2,
+        "questions": [
+            {
+                "id": "q1",
+                "text": "First question?",
+                "options": {"A": "Alpha", "B": "Beta", "C": "Gamma", "D": "Delta"},
+                "correct": "B",
+                "time_limit": 2,
+                "explanation": "B is correct.",
+            },
+            {
+                "id": "q2",
+                "text": "Second question?",
+                "options": {"A": "One", "B": "Two", "C": "Three", "D": "Four"},
+                "correct": "C",
+                "time_limit": 2,
+            },
+            {
+                "id": "q3",
+                "text": "Third question?",
+                "options": {"A": "Red", "B": "Blue", "C": "Green", "D": "Gold"},
+                "correct": "A",
+                "time_limit": 2,
+            },
+            {
+                "id": "q4",
+                "text": "Fourth question?",
+                "options": {"A": "North", "B": "South", "C": "East", "D": "West"},
+                "correct": "D",
+                "time_limit": 2,
+            },
+            {
+                "id": "q5",
+                "text": "Fifth question?",
+                "options": {"A": "Fetch", "B": "Decode", "C": "Execute", "D": "Write"},
+                "correct": "A",
+                "time_limit": 1,
+            },
+        ],
+    }
+
+
+@pytest.fixture
+def client(tmp_path):
+    settings = Settings(
+        db_path=str(tmp_path / "quiz.db"),
+        secret_key="test-secret",
+        admin_password="admin-pass",
+        public_url="http://testserver",
+    )
+    app = create_app(settings)
+    with TestClient(app) as test_client:
+        yield test_client
+
+
+def admin_login(client: TestClient) -> None:
+    response = client.post("/admin/login", json={"password": "admin-pass"})
+    assert response.status_code == 200
+
+
+def create_quiz(client: TestClient, pool: dict) -> int:
+    admin_login(client)
+    response = client.post("/admin/api/quizzes", json={"pool_json": pool})
+    assert response.status_code == 200, response.text
+    return response.json()["quiz_id"]
+
+
+def create_session(client: TestClient, pool: dict) -> str:
+    quiz_id = create_quiz(client, pool)
+    response = client.post("/admin/api/sessions", json={"quiz_id": quiz_id})
+    assert response.status_code == 200, response.text
+    return response.json()["sid"]
+
+
+def join_student(client: TestClient, sid: str, student_id: str = "s1", name: str = "Student One") -> dict:
+    response = client.post(f"/api/session/{sid}/join", json={"student_id": student_id, "name": name})
+    assert response.status_code == 200, response.text
+    return response.json()

tests/test_api_admin.py

@@ -1,2 +1,42 @@
-def test_placeholder_api_admin():
+from conftest import admin_login, create_quiz, create_session, join_student
-    assert True
+
+
+def test_admin_login_required_and_quiz_session_crud(client, sample_pool):
+    assert client.get("/admin/").status_code == 401
+    assert client.post("/admin/login", json={"password": "wrong"}).status_code == 401
+
+    admin_login(client)
+    assert client.get("/admin/").status_code == 200
+    quiz_id = create_quiz(client, sample_pool)
+    quizzes = client.get("/admin/api/quizzes").json()["quizzes"]
+    assert any(item["id"] == quiz_id for item in quizzes)
+
+    response = client.post("/admin/api/sessions", json={"quiz_id": quiz_id})
+    assert response.status_code == 200
+    payload = response.json()
+    assert len(payload["sid"]) == 6
+    assert payload["join_url"].endswith(f"?sid={payload['sid']}")
+    assert payload["qr_url"].startswith("data:image/svg+xml;base64,")
+
+    sessions = client.get("/admin/api/sessions").json()["sessions"]
+    assert sessions[0]["sid"] == payload["sid"]
+
+
+def test_quiz_upload_and_csv_export(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    join_student(client, sid, "s1", "Student One")
+    csv_response = client.get(f"/admin/api/sessions/{sid}/csv")
+    assert csv_response.status_code == 200
+    assert "student_id,name,question_idx" in csv_response.text
+
+    upload = client.post(
+        "/admin/api/quizzes/upload",
+        files={"file": ("pool.json", __import__("json").dumps(sample_pool), "application/json")},
+    )
+    assert upload.status_code == 200
+
+
+def test_invalid_quiz_and_session_errors(client):
+    admin_login(client)
+    assert client.post("/admin/api/quizzes", json={"pool_json": {"title": "bad", "questions": []}}).status_code == 400
+    assert client.post("/admin/api/sessions", json={"quiz_id": 999}).status_code == 404

tests/test_api_student.py

@@ -1,2 +1,29 @@
-def test_placeholder_api_student():
+from conftest import create_session, join_student
-    assert True
+
+
+def test_session_metadata_join_me_and_stats(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    metadata = client.get(f"/api/session/{sid}").json()
+    assert metadata["title"] == "Sample Quiz"
+    assert metadata["state"] == "lobby"
+    assert metadata["current_question_idx"] is None
+
+    join = join_student(client, sid, "s1", "First Name")
+    assert join["ok"] is True
+    assert "qz_student" in client.cookies
+
+    join_student(client, sid, "s1", "Updated Name")
+    me = client.get(f"/api/session/{sid}/me")
+    assert me.status_code == 200
+    assert me.json()["name"] == "Updated Name"
+
+    stats = client.get(f"/api/session/{sid}/stats").json()
+    assert stats["question_idx"] is None
+    assert stats["top5"][0]["name"] == "Updated Name"
+
+
+def test_invalid_session_and_missing_cookie_paths(client):
+    assert client.get("/?sid=BAD").status_code == 200
+    assert "Ask your instructor" in client.get("/?sid=BAD").text
+    assert client.get("/api/session/BAD").status_code == 404
+    assert client.get("/api/session/BAD/me").status_code == 401

tests/test_auth.py

@@ -1,2 +1,33 @@
-def test_placeholder_auth():
+from fastapi import HTTPException
-    assert True
+
+from app import auth
+from app.config import Settings
+
+
+def test_student_cookie_signing_roundtrip():
+    settings = Settings(secret_key="secret", public_url="http://testserver")
+    token = auth.sign_student(settings, "ABC123", "s1", "Ada", "cookie-id")
+    payload = auth.loads_cookie(settings, token)
+    assert payload == {"sid": "ABC123", "student_id": "s1", "name": "Ada", "cookie_id": "cookie-id"}
+
+
+def test_tampered_cookie_rejected():
+    settings = Settings(secret_key="secret")
+    token = auth.sign_admin(settings)
+    assert auth.loads_cookie(settings, token + "tamper") is None
+
+
+def test_admin_password_success_and_failure():
+    settings = Settings(secret_key="secret", admin_password="pw")
+    assert auth.verify_admin_password(settings, "pw")
+    assert not auth.verify_admin_password(settings, "wrong")
+    assert not auth.verify_admin_password(Settings(secret_key="secret"), "pw")
+
+
+def test_serializer_requires_secret():
+    try:
+        auth.sign_admin(Settings(secret_key=None))
+    except HTTPException as exc:
+        assert exc.status_code == 500
+    else:
+        raise AssertionError("Expected missing secret to fail")

tests/test_csv_export.py

@@ -1,2 +1,17 @@
-def test_placeholder_csv_export():
+from conftest import create_session, join_student
-    assert True
+
+
+def test_csv_export_contains_one_row_per_submission(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    join_student(client, sid, "s1", "Student One")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 2)
+    ack = client.portal.call(rooms.submit_answer, sid, "s1", 0, "B")
+    assert ack["type"] == "submit_ack"
+    client.portal.call(rooms.close_question, sid)
+
+    response = client.get(f"/admin/api/sessions/{sid}/csv")
+    lines = response.text.strip().splitlines()
+    assert lines[0] == "sid,student_id,name,question_idx,answer,elapsed_ms,score,status"
+    assert len(lines) == 2
+    assert ",s1,Student One,0,B," in lines[1]

tests/test_late_join.py

@@ -1,2 +1,35 @@
-def test_placeholder_late_join():
+from fastapi.testclient import TestClient
-    assert True
+
+from conftest import create_session, join_student
+
+
+def test_late_join_during_open_gets_reduced_remaining_and_can_score(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 2)
+
+    late = TestClient(client.app)
+    with late:
+        join_student(late, sid, "late", "Late Student")
+        with late.websocket_connect(f"/ws/student/{sid}") as ws:
+            assert ws.receive_json()["state"] == "question_open"
+            opened = ws.receive_json()
+            assert opened["type"] == "question_open"
+            assert 0 < opened["remaining_ms"] <= 2000
+            ws.send_json({"type": "submit", "question_idx": 0, "answer": "B"})
+            assert ws.receive_json()["score"] > 0
+
+
+def test_join_after_closed_gets_missed_row(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 1)
+    client.portal.call(rooms.close_question, sid)
+
+    late = TestClient(client.app)
+    with late:
+        join_student(late, sid, "late", "Late Student")
+        me = late.get(f"/api/session/{sid}/me").json()
+        assert me["submissions"][0]["question_idx"] == 0
+        assert me["submissions"][0]["status"] == "missed"
+        assert me["submissions"][0]["score"] == 0

tests/test_load_simulation.py

@@ -1,2 +1,49 @@
-def test_placeholder_load_simulation():
+import time
-    assert True
+
+from conftest import create_session, join_student
+
+
+def test_load_simulation_50_students_full_quiz_and_autoclose(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    rooms = client.app.state.rooms
+    sockets = []
+    try:
+        for idx in range(50):
+            join_student(client, sid, f"s{idx:02d}", f"Student {idx:02d}")
+            ws = client.websocket_connect(f"/ws/student/{sid}").__enter__()
+            sockets.append(ws)
+            assert ws.receive_json()["type"] == "state"
+
+        for question_idx in range(5):
+            client.portal.call(rooms.open_question, sid, question_idx, 1)
+            for ws in sockets:
+                assert ws.receive_json()["type"] == "question_open"
+            for idx, ws in enumerate(sockets):
+                answer = sample_pool["questions"][question_idx]["correct"] if idx % 3 else "A"
+                ws.send_json({"type": "submit", "question_idx": question_idx, "answer": answer})
+                assert ws.receive_json()["type"] == "submit_ack"
+            if question_idx == 4:
+                started = time.monotonic()
+                for ws in sockets:
+                    message = ws.receive_json()
+                    assert message["type"] == "question_closed"
+                assert time.monotonic() - started < 2
+            else:
+                client.portal.call(rooms.close_question, sid)
+                for ws in sockets:
+                    assert ws.receive_json()["type"] == "question_closed"
+                client.portal.call(rooms.next_question, sid)
+                for ws in sockets:
+                    assert ws.receive_json()["type"] == "between_questions"
+
+        client.portal.call(rooms.end_session, sid)
+        for ws in sockets:
+            assert ws.receive_json()["type"] == "session_ended"
+
+        csv_lines = client.get(f"/admin/api/sessions/{sid}/csv").text.strip().splitlines()
+        assert len(csv_lines) == 1 + 50 * 5
+        stats = client.get(f"/api/session/{sid}/stats?question_idx=4").json()
+        assert stats["top5"]
+    finally:
+        for ws in sockets:
+            ws.__exit__(None, None, None)

tests/test_pool.py

@@ -1,2 +1,37 @@
-def test_placeholder_pool():
+import pytest
-    assert True
+
+from app.pool import PoolValidationError, get_question, parse_pool_json, public_question_payload, question_time_limit
+
+
+def test_pool_validation_accepts_well_formed_pool(sample_pool):
+    pool = parse_pool_json(sample_pool)
+    assert pool["title"] == "Sample Quiz"
+    assert pool["score_fn"] == "linear_decay"
+    assert question_time_limit(pool, 0) == 2
+    assert get_question(pool, 0)["correct"] == "B"
+    public = public_question_payload(pool, 0)
+    assert "correct" not in public
+    assert public["options"]["A"] == "Alpha"
+
+
+@pytest.mark.parametrize(
+    "mutator, message",
+    [
+        (lambda p: p.pop("title"), "title"),
+        (lambda p: p.update({"questions": []}), "at least one"),
+        (lambda p: p["questions"][0].pop("text"), "text"),
+        (lambda p: p["questions"][0].update({"options": {"A": "x"}}), "options"),
+        (lambda p: p["questions"][0].update({"correct": "E"}), "correct"),
+        (lambda p: p.update({"score_fn": "missing"}), "Unknown"),
+        (lambda p: p.update({"time_limit_default": 0}), "positive"),
+    ],
+)
+def test_pool_validation_rejects_invalid_shapes(sample_pool, mutator, message):
+    mutator(sample_pool)
+    with pytest.raises(PoolValidationError, match=message):
+        parse_pool_json(sample_pool)
+
+
+def test_pool_validation_rejects_invalid_json():
+    with pytest.raises(PoolValidationError, match="Invalid JSON"):
+        parse_pool_json("{bad")

tests/test_reconnect.py

@@ -1,2 +1,22 @@
-def test_placeholder_reconnect():
+from conftest import create_session, join_student
-    assert True
+
+
+def test_reconnect_replays_existing_submit_ack(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    join_student(client, sid, "s1", "Student One")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 2)
+
+    with client.websocket_connect(f"/ws/student/{sid}") as ws:
+        assert ws.receive_json()["type"] == "state"
+        assert ws.receive_json()["type"] == "question_open"
+        ws.send_json({"type": "submit", "question_idx": 0, "answer": "B"})
+        ack = ws.receive_json()
+        assert ack["type"] == "submit_ack"
+
+    with client.websocket_connect(f"/ws/student/{sid}") as ws:
+        assert ws.receive_json()["type"] == "state"
+        assert ws.receive_json()["type"] == "question_open"
+        replay = ws.receive_json()
+        assert replay["type"] == "submit_ack"
+        assert replay["score"] == ack["score"]

tests/test_scoring.py

@@ -1,2 +1,26 @@
-def test_placeholder_scoring():
+from app.scoring import SCORE_FNS
-    assert True
+
+
+def test_linear_decay_values():
+    fn = SCORE_FNS["linear_decay"]
+    assert fn(True, 0, 60_000) == 1000
+    assert fn(True, 30_000, 60_000) == 750
+    assert fn(True, 60_000, 60_000) == 500
+    assert fn(True, 90_000, 60_000) == 500
+    assert fn(False, 0, 60_000) == 0
+
+
+def test_flat_values():
+    fn = SCORE_FNS["flat"]
+    assert fn(True, 0, 60_000) == 1000
+    assert fn(True, 60_000, 60_000) == 1000
+    assert fn(True, 90_000, 60_000) == 1000
+    assert fn(False, 0, 60_000) == 0
+
+
+def test_exponential_decay_values():
+    fn = SCORE_FNS["exponential_decay"]
+    assert fn(True, 0, 60_000) == 1000
+    assert 560 < fn(True, 60_000, 60_000) < 570
+    assert fn(True, 90_000, 60_000) == fn(True, 60_000, 60_000)
+    assert fn(False, 0, 60_000) == 0

tests/test_state_machine.py

@@ -1,2 +1,45 @@
-def test_placeholder_state_machine():
+from conftest import create_session, join_student
-    assert True
+
+
+def test_full_lifecycle_with_three_students(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    rooms = client.app.state.rooms
+    sockets = []
+    for idx in range(3):
+        join_student(client, sid, f"s{idx}", f"Student {idx}")
+        ws = client.websocket_connect(f"/ws/student/{sid}").__enter__()
+        sockets.append(ws)
+        assert ws.receive_json()["state"] == "lobby"
+
+    try:
+        client.portal.call(rooms.open_question, sid, 0, 2)
+        for ws in sockets:
+            assert ws.receive_json()["type"] == "question_open"
+        for idx, ws in enumerate(sockets):
+            ws.send_json({"type": "submit", "question_idx": 0, "answer": "B" if idx < 2 else "A"})
+            assert ws.receive_json()["type"] == "submit_ack"
+
+        client.portal.call(rooms.close_question, sid)
+        for ws in sockets:
+            assert ws.receive_json()["type"] == "question_closed"
+        session = client.portal.call(rooms.get_session, sid)
+        assert session["state"] == "question_closed"
+
+        client.portal.call(rooms.next_question, sid)
+        for ws in sockets:
+            assert ws.receive_json()["type"] == "between_questions"
+        assert client.portal.call(rooms.get_session, sid)["state"] == "between_questions"
+
+        client.portal.call(rooms.open_question, sid, 1, 2)
+        for ws in sockets:
+            assert ws.receive_json()["type"] == "question_open"
+        client.portal.call(rooms.end_session, sid)
+        for ws in sockets:
+            message = ws.receive_json()
+            assert message["type"] in {"question_closed", "session_ended"}
+            if message["type"] == "question_closed":
+                assert ws.receive_json()["type"] == "session_ended"
+        assert client.portal.call(rooms.get_session, sid)["state"] == "finished"
+    finally:
+        for ws in locals().get("sockets", []):
+            ws.__exit__(None, None, None)

tests/test_ws_admin.py

@@ -1,2 +1,38 @@
-def test_placeholder_ws_admin():
+import pytest
-    assert True
+from starlette.websockets import WebSocketDisconnect
+
+from conftest import admin_login, create_session, join_student
+
+
+def test_instructor_ws_requires_admin_cookie(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    client.cookies.clear()
+    with pytest.raises(WebSocketDisconnect) as exc:
+        with client.websocket_connect(f"/ws/instructor/{sid}"):
+            pass
+    assert exc.value.code == 4001
+
+
+def test_instructor_controls_transition_and_broadcast(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    join_student(client, sid, "s1", "Student One")
+    admin_login(client)
+    with client.websocket_connect(f"/ws/student/{sid}") as student_ws:
+        assert student_ws.receive_json()["type"] == "state"
+        with client.websocket_connect(f"/ws/instructor/{sid}") as admin_ws:
+            assert admin_ws.receive_json()["type"] == "state"
+            assert admin_ws.receive_json()["type"] == "lobby_update"
+            admin_ws.send_json({"type": "open_question", "question_idx": 0, "time_limit": 2})
+            student_open = student_ws.receive_json()
+            assert student_open["type"] == "question_open"
+            admin_open = admin_ws.receive_json()
+            assert admin_open["type"] == "question_open"
+            assert admin_ws.receive_json()["type"] == "live_histogram"
+
+            admin_ws.send_json({"type": "close_question"})
+            assert student_ws.receive_json()["type"] == "question_closed"
+            messages = [admin_ws.receive_json(), admin_ws.receive_json()]
+            assert {msg["type"] for msg in messages} == {"question_closed", "full_leaderboard"}
+
+            admin_ws.send_json({"type": "next"})
+            assert student_ws.receive_json()["type"] == "between_questions"

tests/test_ws_student.py

@@ -1,2 +1,37 @@
-def test_placeholder_ws_student():
+import pytest
-    assert True
+from starlette.websockets import WebSocketDisconnect
+
+from conftest import create_session, join_student
+
+
+def test_student_ws_requires_cookie(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    with pytest.raises(WebSocketDisconnect) as exc:
+        with client.websocket_connect(f"/ws/student/{sid}"):
+            pass
+    assert exc.value.code == 4001
+
+
+def test_student_ws_initial_state_submit_and_closed_reject(client, sample_pool):
+    sid = create_session(client, sample_pool)
+    join_student(client, sid, "s1", "Student One")
+    with client.websocket_connect(f"/ws/student/{sid}") as ws:
+        state = ws.receive_json()
+        assert state["type"] == "state"
+        assert state["state"] == "lobby"
+
+        rooms = client.app.state.rooms
+        client.portal.call(rooms.open_question, sid, 0, 2)
+        opened = ws.receive_json()
+        assert opened["type"] == "question_open"
+        ws.send_json({"type": "submit", "question_idx": 0, "answer": "B"})
+        ack = ws.receive_json()
+        assert ack["type"] == "submit_ack"
+        assert ack["score"] > 0
+
+        client.portal.call(rooms.close_question, sid)
+        closed = ws.receive_json()
+        assert closed["type"] == "question_closed"
+        ws.send_json({"type": "submit", "question_idx": 0, "answer": "B"})
+        error = ws.receive_json()
+        assert error["code"] == "not_open"