# NextGen School Portal: QA, Automated Testing, and UAT Plan

This plan defines the quality assurance (QA) pipeline, automated testing framework stack, and User Acceptance Testing (UAT) guidelines for deploying the NextGen school portal. It addresses the lack of automated test coverage and details testing guidelines for offline-first replication.

---

## 1. Quality Assurance (QA) Strategy

Before running any test suite, the project must pass strict static analysis checks to maintain code style and catch compilation errors early.

### A. Static Code Analysis
1. **TypeScript Checks**: Implement clean typescript type-checking on the client before code commits.
   * Add to `client/package.json`: `"typecheck": "tsc --noEmit"`
2. **ESLint Audits**: Configure standard ESLint rules for React and Node to prevent unused variables, floating promises, and direct console leakages in production.

### B. Manual QA Matrix
A structured manual verification sheet must be maintained for each role before promotions to the `main` branch.

| Role | Verification Target | Expected Result |
| :--- | :--- | :--- |
| **All Users** | Session Expiry & Logout | Clears Zustand store, redirects to `/login` immediately. |
| **Bursar** | Payment Reconciliation | Settle fee outstanding via Paynow (or mock gateway); balance updates live. |
| **Teacher** | Grade Entry & Publish | Grades entered offline are saved, calculated, and sync when online. |
| **Parent** | Multi-Student Roster | Parent portal displays separate profiles and alerts for linked students. |
| **Sys Admin** | Sync Diagnostic Logs | Shows real-time synchronization latency and database status logs. |

---

## 2. Automated Testing Strategy

Due to the system's offline-first architecture, automated tests must validate both normal online states and simulated network outages.

### A. Unit & Integration Testing (Backend & Database)
* **Stack**: **Vitest** + **Supertest**
* **Scope**:
  1. **Controllers**: Mock the `auth` middleware and query endpoints directly using Supertest to assert payload shapes (e.g., verifying that `/api/reports/summary` strips financial data for teachers).
  2. **SQLite Database Seeding**: Write unit tests to check that `server/src/database/init.js` populates all check constraints, tables, and default settings cleanly.
  3. **Sync Engine**: Mock Supabase network requests and test the conflict resolution loops (`SyncEngine.js`) against known local SQLite modifications.

### B. End-to-End (E2E) Testing (Frontend & Offline Flow)
* **Stack**: **Playwright**
* **Scope**: Playwright is required to simulate offline client state using Chrome developer tools network throttling:
  1. **Online Write**: Log in, create an event, verify it writes to SQLite with `sync_status = 'pending'`, and verify it is pushed to Supabase.
  2. **Offline Intercept**: Disconnect the browser network in Playwright (`context.setOffline(true)`). Create an event, verify the WASM SQLite intercept in `api.ts` handles the write locally and returns a success status.
  3. **Reconnect & Sync**: Re-enable connection (`context.setOffline(false)`). Wait 30 seconds, and assert that the sync status flips to `synced` and the records match the backend.

---

## 3. User Acceptance Testing (UAT) Plan

The UAT phase will run for **two weeks** at the pilot Zimbabwean school to ensure administrative staff, teachers, and parents are satisfied before rolling it out full-time.

### A. UAT Roles & Participants
* **1 Principal / Headmaster**: To evaluate executive reports, calendar updates, and announcements.
* **1 Bursar**: To evaluate fees, billing list uploads, and Paynow transaction logs.
* **2 Teachers**: To evaluate taking attendance, publishing homework, and grading.
* **5 Parents**: To evaluate reading report cards, notices, and making fee payments on mobile devices.

### B. UAT Test Scenarios & Scripts

#### Scenario 1: Intake & Class Allocation (Admin/Bursar)
* **Action**: Admin creates a new class "Grade 2 Gold", allocates a teacher, and enrolls a new student. Bursar generates the term's tuition invoice ($200.00).
* **Success Criteria**: Student card appears in the teacher's student roster immediately, and a pending fee invoice appears in the parent's portal.

#### Scenario 2: Offline Marks Entry & Online Reconciliation (Teacher)
* **Action**: Teacher takes their tablet to a classroom with no network. Logs daily attendance and uploads a quiz mark. Later, the teacher walks back to the staff room where Wi-Fi is active.
* **Success Criteria**: Data is captured instantly in the classroom. Once in range of Wi-Fi, the sys logs panel confirms a successful upload background batch, and the parent can see the quiz mark on their phone.

#### Scenario 3: Fee Payment (Parent)
* **Action**: Parent logs in, sees the tuition invoice, and selects "Pay Fees". Settle the balance via the Paynow payment drawer.
* **Success Criteria**: Parent is redirected back to the portal showing a green confirmation page. The Bursar dashboard reports the balance is updated, and a paid receipt is generated in the SQLite database.

### C. Feedback Collection & Bug Triaging
1. **Feedback Capture**: Deploy a simple "Support/Feedback" floating button on the UAT build that writes directly to a `system_feedback` table in the database.
2. **Triage Severity Classifications**:
   * **P0 (Blocker)**: Severe data loss, failed payments, or offline writing errors. Requires hotfix within 24 hours.
   * **P1 (High)**: Sync engine delay exceeding 5 minutes or RBAC page gating leaks.
   * **P2 (Normal)**: Layout shifts on mobile views, slow loading graphs, or minor spelling bugs.
