🧪 QA Test Cases

TC-AUTH-01 — Teacher registration: happy path

A fresh browser with no session.

Visit account.readingtester.com/register, fill name + valid email + password ≥8 chars, submit.

• HTTP 201 in browser Network tab
• "Check your email" confirmation screen shown
• users row: state=pending_verification, email_verified=false
• subscriptions row: state=trialing, trial_ends_at = ~14 days from now
• audit_log row: action=register
• Email received in inbox (VERIFY_EMAIL template)

TC-AUTH-02 — Teacher email verification

TC-AUTH-01 completed, verification email received.

Click the verification link in the email.

• users.email_verified=true, state=active
• Browser redirected to /onboarding
• uc_session cookie set (httpOnly, Secure)
• audit_log row: action=email_verified
• WELCOME_TEACHER email sent

TC-AUTH-03 — Teacher login and logout

Verified teacher account.

Submit correct email + password at account.readingtester.com/login.

• Redirect to Teacher Portal (teacher.readingtester.com)
• uc_session cookie present
• audit_log row: action=login

Click logout.

• uc_session cookie cleared
• Redirect to /login
• Attempting /dashboard → redirect to /login (no access without session)

TC-AUTH-04 — Child login: happy path

Teacher created student account (username: emma001, PIN: 1234), placement_test_completed=false.

Visit app.readingtester.com, enter username + PIN.

• device_sessions row created (learner_id mapped, policy_applied=shared)
• audit_log row: action=child_login
• Redirected to /placement-test (not library)

Login again after placement test done.

Redirect directly to /library — placement test NOT shown again.

TC-AUTH-05 — Child login: PIN lockout

Valid child account with PIN 1234.

Enter wrong PIN 5 times in a row.

• After 5th failure: HTTP 423
• students.locked=true
• teacher_notifications row inserted (type=pin_lockout)
• "Account locked — ask your teacher" shown to child
• Teacher Portal shows notification badge

TC-AUTH-06 — Device reuse / shared device session

Child A (emma001) logged in on a tablet, device_session_id=AAA.

Child B (james002) logs in on the same tablet.

• Previous device_sessions row for AAA: expired_at=NOW(), end_reason=device_reuse
• New device_sessions row created for james002
• Child A's session is invalid — navigating redirects to login

TC-AUTH-07 — Session inactivity timeout

Child logged in, shared_device_mode=true, child_inactivity_timeout_min=30.

No activity for 31 minutes.

• device_sessions.expired_at=NOW(), end_reason=timeout
• Child sees "Session ended — log in again"
• If ≥3 pages AND ≥50 words read: progress saved, miles credited
• If below threshold: session data discarded — no partial miles credited

TC-ROSTER-01 — Create a class

POST /api/v1/classes with {class_name: "Year3Blue", year_level: 3}

• HTTP 201
• classes row: teacher_id=session.user_id, state=active
• Class visible in Teacher Portal immediately
• audit_log row: action=create_class

TC-ROSTER-02 — Add a single student

POST /api/v1/classes/:class_id/students with {name: "Tommy Anderson", year_level: 3}

• HTTP 201
• students row: auto-generated username + 4-digit PIN, state=created, placement_test_completed=false
• class_memberships row inserted
• Response body contains username and pin (shown once — teacher must record)
• audit_log row: action=create_student

TC-ROSTER-03 — Bulk import students (CSV)

POST /api/students/import with CSV file (columns: name, year_level).

• HTTP 200 with array of {name, username, pin} for each row
• All students rows created, all class_memberships inserted
• Login cards renderable (name + username + PIN + QR code)

TC-ROSTER-04 — Class hard cap enforcement (33 students)

Class already has 33 active students.

Teacher attempts to add 1 more student.

• HTTP 422 {error: "CLASS_FULL"}
• No new class_memberships row
• Teacher Portal shows "Class is full (33/33)"

Teacher archives one student (students.archived_at=NOW()).

Cap slot freed immediately — next add succeeds.

TC-ROSTER-05 — Teacher invites a colleague

school_admin POSTs /api/v1/schools/:school_id/invites with colleague email + role teacher.

• invites row: token_hash stored, expires_at=NOW()+7d
• INVITE_EMAIL sent

• users row: role=teacher, school_id set, state=active
• subscriptions row: state=trialing

TC-ROSTER-06 — Parent linking via link code

Parent has a Pickatale account, teacher has generated a 6-char link code (e.g. PIP423) for the student from the Teacher Portal.

Parent logs in to parents.readingtester.com, clicks "Link Your Child's Account", enters child display name + link code.

• Client validates code against account.readingtester.com/api/public/link-code/PIP423
• Returns {valid: true, uuid: "..."} — UUID resolved
• parent_children row inserted: parentId, childName, learnerServiceId=uuid
• Child's reading progress visible to parent (read-only)

TC-READ-01 — Open a book and read (online)

Authenticated child (placement complete) taps a book on app.readingtester.com/library.

• reading_sessions row created: state=open, book_id, learner_id, started_at
• Telemetry event book_opened fired (POST /api/v1/events)
• Book content displayed (FK-leveled if applicable)

• Telemetry event page_turned fired per page: {device_session_id, learner_id, page_number, time_on_page_ms}

• session_ended event fired
• reading_sessions.state=completed, words_read, pages_read updated
• Miles incremented: floor(words_read / 100)

TC-READ-02 — Vocabulary tap

Child taps word "photosynthesis" in Finger-Follow mode.

• Telemetry event word_tapped fired: {word, page_number, device_session_id, learner_id}
• TTS pronounces the word
• Definition popup shown (if enabled)
• Word stored in Learner Bot vocabularyGaps after session ends

TC-READ-03 — Miles and token accumulation

Child has miles=9, reads a book with 150 words.

• floor(150/100)=1 new mile credited → students.miles=10
• 10 miles threshold crossed → students.tokens incremented by 1
• audit_log row: action=token_earned

TC-READ-04 — RSVP Speedread (age gate)

Child account with age=7.

Speedread button hidden or HTTP 403 — mode not accessible.

Child with age=9, fk_level ≥ 3.0.

• RSVP interface shown, starts at 60 WPM
• Max session: 10 minutes enforced
• RSVP time does NOT count toward book completion or miles

TC-READ-05 — Theme persistence

Child opens Aa button → selects "Sepia".

• Background changes to #F5E6C8
• localStorage["reader_bg_theme"]="sepia" written

Sepia theme restored from localStorage — no white flash on load.

TC-READ-06 — Offline reading and sync

Child goes offline (DevTools → Network → Offline) mid-session, turns pages, taps words.

• All events queued in IndexedDB (telemetry-queue tag)
• App continues — no error shown to child
• Miles NOT yet persisted to server

• Service Worker replays all queued events
• Server deduplicates by event_id — re-sending same events twice produces no duplicate rows
• reading_sessions.state=completed updated
• Miles credited to server DB

TC-TEL-01 — Event deduplication

Same event (identical event_id UUID) POSTed to /api/v1/events twice.

• First call: HTTP 200, row inserted
• Second call: HTTP 200 (idempotent), no duplicate row
• Only 1 row in events table for that event_id

TC-TEL-02 — Vocab-taps pipeline (Telemetry → Bot)

session_ended fires — Telemetry calls POST /api/v1/telemetry/vocab-taps.

• Learner Bot vocabularyGaps: word=magnificent, tap_count=2 (for 2 taps)
• Re-tap in next session: tap_count incremented via SQL (tap_count + N, not overwritten)
• Response to Telemetry: HTTP 200 within 5 seconds

TC-TEL-03 — Session summary (slow pages detection)

Session: 5 pages, time_on_page_ms=[30000, 45000, 120000, 40000, 35000] (avg=54s, page 3 = 120s = 2.2× avg).

• slow_pages=[3]
• Bot stores reading_pattern memory (confidence=0.60 if pages read < 80% of total)
• If slow_pages.length > 3: Bot stores engagement_signal={signal:"struggling"}

TC-TEL-04 — Event ordering guarantee

Three events from same device_session_id arrive out of server order (network jitter).

• Events ordered by client_ts, NOT created_at
• session_ended processing waits until all prior events for same device_session_id are processed

TC-BOT-01 — Placement test → bot memory

Child completes placement test → POST /api/placement-result {learner_id, fk_level: 3.5}

• placement_results row inserted
• students.placement_test_completed=true
• Bot stores reading_level memory with confidence=1.0
• Child redirected to /library

TC-BOT-02 — Nightly report generation

Learner has active subscription, read ≥1 book in past 7 days.

Nightly cron fires at 04:00 UTC.

• nightly_reports row: report_type=teacher_report, includes FK progression + reasoning
• nightly_reports row: report_type=parent_digest, warm tone
• Both portals display the new reports

TC-BOT-03 — Nightly bot: inactive learner alert

Learner has not read any book in 4+ days.

• teacher_notifications row: type=inactive
• Teacher Portal shows alert badge

TC-BOT-04 — Quiz result → bot feedback

Child completes comprehension quiz, score 55%.

POST /api/v1/bot/:learner_id/quiz-result {scorePct: 55, levelRecommendation: "hold", ...}

• Bot stores assessment_result memory: confidence=0.55
• Bot triggers re-run for this learner (setImmediate)
• If this is 2nd quiz with avg < 65%: teacher_notifications type=low_score

TC-BOT-05 — Bot: free-tier learner skipped

Child's teacher subscription has expired (state=expired).

Nightly cron runs.

• checkEntitlement → tier=free
• Bot SKIPS this learner — no nightly_reports row generated
• Teacher Portal shows "Upgrade to view reports"

TC-BOT-06 — Adaptive content leveling

POST /api/v1/level-page {bookId, pageNumber, text, targetFkLevel: 4.0}

• HTTP 200: {leveledText, actualFkScore, cached: false}
• Cache key stored: book_id + page_number + target_level_rounded + source_hash
• Identical second call: cached: true, no new GPT call
• Short text (<30 words): returned unchanged, no leveling attempted

TC-TEACH-01 — Dashboard: class overview

Visit teacher.readingtester.com/class/:id (class has 5 students).

• All 5 students listed with: name, reading level, books read this week, miles, latest bot report
• Attention list flags: placement_test_completed=false OR books_read=0 OR quiz avg < 65% (2+ quizzes)

TC-TEACH-02 — Learner profile view

Teacher clicks a student's name.

• GET /api/v1/bot/:learner_id/status called with X-Internal-Key
• Displays: reading_level, books_read, total_miles, readingLevelHistory, vocabGaps, latestReport

TC-TEACH-03 — PIN reset (teacher flow)

Student account locked after 5 failed PIN attempts.

Teacher clicks "Reset PIN".

• New 4-digit PIN generated, shown once to teacher
• students.locked=false, pin_hash=bcrypt(new_pin)
• audit_log row: action=pin_reset

TC-TEACH-04 — Print login cards

Teacher clicks "Print Login Cards" after bulk import.

• Printable cards shown: student name + username + PIN + QR code (app.readingtester.com?user=username) + school name + Pip logo

TC-TEACH-05 — DPA setup wizard

New teacher account, first login.

School details form submitted (School Name, Country, DPA checkbox ticked).

• school_dpa_agreements row: school_id, user_id, accepted_at=NOW(), ip_address
• Teacher redirected to dashboard

TC-BILL-01 — Trial period access

subscriptions.state=trialing, trial_ends_at=NOW()+14d

checkEntitlement → tier=full. All features accessible, no paywall.

checkEntitlement → tier=free. Full-tier features locked, upgrade prompt shown.

TC-BILL-02 — Stripe payment failure → grace period

Stripe webhook invoice.payment_failed received (valid Stripe-Signature).

• subscriptions.state=past_due, grace_ends_at=NOW()+7d
• RENEWAL_FAILED email sent (email_log INSERT)
• Teacher Portal: yellow banner "Payment failed. Update billing within 7 days."
• All features remain accessible (grace active)
• audit_log row: action=stripe_webhook
• HTTP 200 returned to Stripe

TC-BILL-03 — Grace period expiry

subscriptions.state=past_due, grace_ends_at=NOW()-1h.

Hourly expiry cron runs.

• subscriptions.state=expired
• All learners' full-tier features locked
• Learner Bot skips all learners on next nightly run
• Teacher Portal: red banner "Subscription expired"
• SCHOOL_SUBSCRIPTION_EXPIRED email sent
• audit_log row: action=subscription_expired

TC-BILL-04 — Entitlement resolution order

Teacher has expired subscriptions but platform_admin granted entitlement_grants row with expires_at=NULL.

entitlement_grants checked first → found → returns tier=full. subscriptions table NOT consulted.

Falls back to subscriptions → state=expired → tier=free. Features locked.

TC-BILL-05 — Entitlement cache (60s TTL)

Admin changes subscriptions.state=expired + broadcasts cache invalidation.

• Within 60 seconds: all service instances clear cache for this user_id
• Next checkEntitlement call fetches fresh from Account Center → tier=free

TC-BILL-06 — Enterprise entitlement (external grant)

School has no Stripe subscription; platform_admin inserted entitlement_grants row.

checkEntitlement finds grant → tier=full. No Stripe interaction. No upgrade prompt.

TC-BILL-07 — Child entitlement resolves from teacher

Child is in a class owned by teacher with active subscription.

Child opens book beyond free tier limit.

Entitlement chain: child → class_memberships → teacher → subscriptions.state=active → tier=full. Book accessible.

TC-ADMIN-01 — Impersonation: start

platform_admin POSTs /api/admin/users/:teacher_id/impersonate with reason.

• Target must NOT be a platform_admin — if admin: HTTP 403
• audit_log: action=impersonation_started, actor_id, target_id
• New session: expires in 1h, impersonator_id stored
• Orange "Impersonating [Name]" banner visible
• All actions during session logged with impersonator_id

TC-ADMIN-02 — Impersonation: end

Click "End Impersonation".

• Impersonated session invalidated
• audit_log: action=impersonation_ended
• Admin's own session restored, orange banner removed

TC-ADMIN-03 — Grant entitlement (admin)

POST /api/admin/entitlement/grant {school_id: 5, tier: "full", expires_at: null}

• entitlement_grants row inserted
• audit_log: action=entitlement_grant_created
• Cache invalidation broadcast to all services
• Within 60 seconds: school resolves tier=full

TC-ADMIN-04 — GDPR deletion

POST /api/gdpr/delete {learner_id: "uuid"}

• students.state=archived — child cannot log in
• gdpr_requests row: type=deletion, state=pending

• Telemetry events deleted
• Bot memories/reports deleted
• LRS statements deleted
• users.name="Deleted User", email="{uuid}@deleted.invalid"
• audit_log PII stripped (rows retained)
• gdpr_requests.state=complete

TC-ADMIN-05 — Audit log immutability

Attempt: DELETE FROM audit_log WHERE ...

DB trigger blocks DELETE — error raised. Rows remain intact.

TC-ADMIN-06 — Voice audio not stored

Fluency assessment in progress, child speaks into microphone.

• Audio processed in-memory only — no file written to disk
• No audio data in DB rows, queues, logs, or retry buffers
• audit_log row contains only text transcript + scores — never raw audio bytes

TC-PARENT-01 — Parent read-only access

Parent linked to child via 6-char link code.

• Child's progress visible: books read, miles, latest parent digest
• FK level NOT shown (parents see engagement metrics only)

TC-FLUENCY-01 — Recording and scoring

Child reads a passage aloud, recording submitted.

• WCPM calculated
• FK grade score returned
• CEFR level assigned (Pre-A1 → B2+) and stored in assessment_scores
• Multilingual learner (multilingual_flag=true): relaxed thresholds (40% accuracy vs 50%, WCPM ≥5 vs ≥10)
• No audio stored after processing

TC-FLUENCY-02 — Score storage and bot update

• assessment_scores row: FK grade + CEFR level
• POST to Learner Bot /api/v1/bot/:learner_id/quiz-result
• Bot updates curriculum_state memory

TC-CONTENT-01 — "Picked for You" recommendation

Child (fk_level=3.5) loads library page.

• Bot queried for recommendation record
• If Bot has recommendation: returned with permanentId, title, author, coverUrl, reason
• If no Bot recommendation: fallback to /api/catalog?fk_min=3.0&fk_max=4.0 — first result used
• LibraryPage renders "Picked for You" hero card

TC-CONTENT-02 — Book pre-warming cache

Pre-warming pipeline has run for a book.

Child with fk_level=3.5 opens any pre-warmed page.

cached: true returned from Adaptive Engine — no GPT call, sub-100ms response.

TC-SEC-01 — Tenant isolation

Teacher A calls GET /api/v1/students.

• Response contains ONLY Teacher A's students
• Teacher B's students NOT returned (not even partially)
• Teacher A requesting Teacher B's class_id directly → HTTP 403

TC-SEC-02 — No secrets in API responses

Any authenticated API call inspected.

• No pin_hash field in any response
• No password_hash field in any response
• No JWT secret or internal key visible
• No server file paths in error messages

TC-SEC-03 — X-Internal-Key required for internal routes

Call internal endpoint without X-Internal-Key header.

HTTP 401 — rejected.

TC-SEC-04 — Rate limiting

100 POST requests to /api/auth/login within 1 minute from same IP.

After threshold: HTTP 429 {error: "Too Many Requests", retryAfter: 60}. Legitimate logins resume after retry window.

TC-SEC-05 — No cross-service DB access

Inspect each service's DB connection string — service connects ONLY to its own schema. All cross-service data fetched via HTTP API with X-Internal-Key. No service has credentials to another service's DB.

TC-PWA-01 — Service Worker registered

Visit app.readingtester.com in a modern browser → DevTools → Application → Service Workers.

• sw.js registered and active (status: "running", not "waiting" or "redundant")
• GET /sw.js → HTTP 200

TC-PWA-02 — Background sync queue visible

Child goes offline, reads pages → DevTools → Application → IndexedDB → telemetry-queue.

Queued event rows visible with event_id, event_type, client_ts. Count matches events fired.

• IndexedDB telemetry-queue empty (all replayed)
• Server events table has all rows (verify by device_session_id)

TC-NOTIF-01 — Teacher notification triggers

• Student PIN locked (5 failed attempts)
• Quiz average < 65% (2+ quizzes)
• Student inactive 4+ days

• teacher_notifications row inserted with correct type
• Notification badge visible in Teacher Portal header
• Clears when teacher marks as read

TC-NOTIF-02 — Email log audit

Any platform email dispatched (welcome, invite, RENEWAL_FAILED, etc.).

email_log row inserted: recipient, template, sent_at — row present even if delivery fails (log the attempt, not just success).