Test Plan - AvengerDisassemble/KU-connect GitHub Wiki

KU-Connect Test Plan

Last updated: 2025-11-06

1. Purpose & Quality Goals

  • Guarantee that students, employers, professors, and admins can reliably complete their core flows (registration, profile/document management, job browsing, applications, moderation).
  • Catch regressions quickly as we iterate on the student browse-jobs experience and shared resume pipeline.
  • Provide a reusable testing playbook teammates can follow (tooling, environments, data, ownership).
  • Document current coverage so gaps are explicit and prioritized.

Key quality targets:

  • Functional correctness: Job listings, resume uploads, and application workflows never corrupt data or fail silently.
  • Security & compliance: Auth/session handling, role boundaries, and document access respect institutional policies.
  • Performance: Browse jobs and job filters respond within 1s on modern devices; heavy queries leverage pagination/caching.
  • UX polish & accessibility: Radix sheets/dialogs animate smoothly, remain accessible (focus management, ARIA), and render correctly on primary breakpoints.

2. System Under Test Overview

  • Backend (Express, Prisma, PostgreSQL/SQLite, AWS S3 adapters): Auth, document storage, job listings/applications, role dashboards, verification flows.
  • Frontend (Vite + React + TypeScript, Tailwind + shadcn/ui, TanStack Query): Student browse jobs, application dialog, registration flows, profile management.
  • Integrations: Google OAuth, AWS S3 (or local storage provider), Email notifications (currently queued), Redis cache (planned), WebSocket (future real-time updates).

3. Scope

In Scope

  • Authentication & authorization (local + OAuth) end-to-end.
  • Student registration with document verification (transcripts), profile edits, document lifecycle.
  • Student browse-jobs (search, quick filters, advanced sheet, saved jobs, detail view) and application submissions (profile resume vs upload).
  • Employer job posting, updates, application review (where implemented).
  • File storage flows (resume/profile docs, employer verification).
  • Regression of legacy flows covered by existing Jest suites (backend/tests/**/*).

Out of Scope (for now)

  • Professor/admin dashboards (pending implementation).
  • Real-time updates/WebSocket behavior (not yet built).
  • Load/stress benchmarks beyond smoke performance checks.
  • Mobile native clients (web responsive only).

4. Test Levels & Ownership

Level Goal Existing Coverage Gaps / Next Steps Owner
Unit Pure functions, validators, hooks Backend: Joi validators, services under backend/tests/src/services. Frontend: No unit/component tests yet. Add Vitest/RTL suites for browse-jobs utilities and hooks. Feature author
Integration Endpoints with DB + auth Backend: Supertest suites (backend/tests/src/routes, controllers). Add tests for job apply (POST /api/job/:id), saved jobs, resume upsert (POST /api/jobs/:jobId/resume). Backend team
Contract/API Schema drift detection None. Generate OpenAPI (via tooling or handcrafted schema) and contract tests for /api/job/list, /api/jobs/:id/resume. Backend + QA
Component (UI) UX states, interactions None automated. Add tests covering JobFilterBar, AdvancedFiltersSheet, JobApplicationDialog with React Testing Library + user-event. Frontend team
E2E / UI flows Critical user journeys None automated. Stand up Playwright smoke flows: registration -> profile, browse -> apply, resume upload, employer job creation. Shared
Accessibility WCAG compliance Ad-hoc manual. Integrate axe-core in component/E2E tests focused on sheets/dialogs. Frontend
Performance Response time, bundle size Informal (manual observation). Add CI check for bundle size (e.g., vite-bundle-visualizer) and backend k6 smoke for /api/job/list. DevOps
Security Auth boundaries Manual reviews. Add automated authorization tests (forbidden access scenarios) and static analysis (e.g., npm audit, eslint-plugin-security). All

5. Environments & Data

  • Local dev:
    • Backend uses SQLite (TEST_DATABASE_URL) with Prisma migrations. npm run test seeds isolated DB.
    • S3 interactions abstracted via storageFactory; tests already mock with local provider (backend/tests/__mocks__/).
    • Frontend runs against local API (VITE_API_URL=http://localhost:3000/api).
  • CI (to be formalized):
    • Stand up docker-compose with PostgreSQL (optional) + localstack for S3.
    • Node 20 LTS for both apps.
  • Staging/Preview: (to define) Mirror production config, anonymized seed data.

Test Data Strategy

  • Reuse Prisma seed fixtures for base entities (degree types, demo HR/student).
  • Create factory helpers for dynamic cases (job with/without resume, advanced filters). Consider using @faker-js/faker to generate data in Jest.
  • Document sample resume/transcript files under backend/tests/fixtures for consistent file upload tests.

6. Tooling & Automation

  • Backend: Jest + Supertest, Prisma test client, manual mocks for S3/email.
  • Frontend: Vitest + React Testing Library (planned), @testing-library/user-event for interactions, msw for API mocks.
  • E2E: Recommend Playwright (TypeScript) for deterministic multi-role flows; use test IDs via data-testid where necessary.
  • Accessibility: @axe-core/playwright or jest-axe in component tests.
  • Performance: k6 smoke script or Autocannon for /api/job/list and /api/job/:id routes.
  • CI Integration: GitHub Actions workflows per package; run lint + typecheck + tests in parallel, publish coverage summaries.

Execution Frequency

  • Unit & component suites: Run on every push/PR via GitHub Actions (blocking required check).
  • Integration/API suites: Nightly and on merges to protected branches against ephemeral databases.
  • E2E/Playwright flows: Nightly on staging-like environments; optional smoke subset on PR with mocked services.
  • Accessibility audits: Weekly scheduled run and on-demand for UI-heavy pull requests.
  • Performance smoke tests: Weekly baseline (k6/autocannon) plus pre-release verification.

7. Regression Strategy

  • Per PR:
    • Run affected unit/integration tests locally.
    • New feature PR must include automated coverage or explicit TODO in test debt backlog.
    • Manual sanity for relevant UI (advanced filters sheet interactions, resume dialog).
  • Daily/CI:
    • Executes full backend Jest suite.
    • Frontend lint + typecheck + (future) Vitest suites.
  • Pre-release (staging):
    • Smoke Playwright runs: student browse/apply, employer post job, admin view (when available).
    • Verify document upload/download using staging storage.
    • Regression checklist (auth flows, saved jobs, advanced filters).

8. Scenario Matrix & Priorities

ID Scenario Priority Current Coverage Plan
S1 Student registration + transcript upload High Manual + partial backend tests (documentsController.uploadTranscript) Add Playwright flow; ensure email stub asserted.
S2 Login (local + Google OAuth fallback) High Backend auth tests (tests/src/auth.test.js) Add negative cases (OAuth-only account login attempt).
S3 Student browse jobs (search + tabs + advanced filters) High Manual Add component tests for filter toggles + Playwright scenario verifying filter persistence.
S4 Resume selection dialog (profile vs upload) High Backend resume controller tests Add frontend component tests (mode switching, validation) + E2E verifying S3 upload success stub.
S5 Job application submit & duplicate prevention High Backend applyToJob service logic only Add integration test hitting /api/job/:id + Playwright verifying UI feedback.
S6 Saved jobs list Medium None Implement backend tests for /job/:id/save and /jobs/saved once endpoints exist.
S7 Employer job CRUD Medium Backend controller/service tests partially exist Add integration tests covering tag updates + Playwright employer flow.
S8 Profile updates + document replacement Medium Backend controllers tested Add frontend component tests for profile forms and manual regression for file replacement.
S9 Access control (student cannot hit HR routes) High Some tests in tests/src/routes Expand with table-driven auth tests across roles.
S10 Error handling (expired tokens, storage failures) Medium Partial Unit tests mocking storage/email to ensure graceful errors surfaced.
S11 Accessibility audits for dialogs/sheets Medium None Add jest-axe assertions for JobApplicationDialog, advanced filter sheet.
S12 Performance budgets for /api/job/list and initial browse render Low None Set k6 baseline, integrate into CI threshold alerts.

Requirements ↔ Test Scenarios Mapping

Requirement (SRS/SAD) Description Covered Scenarios
R1 Authenticate KU accounts (local credentials + Google OAuth) S2, S9
R2 Student identity verification with transcript upload S1, S8
R3 Discover, filter, and save job postings S3, S6, S12
R4 Submit job applications using profile or job-specific resumes S4, S5, S10
R5 Employers publish and maintain job listings S7
R6 Enforce role-based access across API and document downloads S8, S9, S10
R7 Maintain accessible, performant UI on supported breakpoints S3, S11, S12

9. Process & Ownership

  • Test Authoring: Feature authors own accompanying tests. Reviewers reject PRs lacking coverage or explicit backlog ticket.
  • Test Debt Backlog: Track missing scenarios in issue tracker (tag "test-gap"). Prioritize High items before release.
  • Code Review Checklist Additions:
    • Does the change break auth boundaries? Add/verify negative tests.
    • Are new API responses covered by contract tests/snapshots?
    • UI changes touching Radix components must have interaction tests or manual QA notes.
  • Defect Lifecycle:
    • Log in issue tracker with repro + environment + severity.
    • Add automated regression for fixed defects before closing.
  • Metrics:
    • Track test suite duration, failure rate, and code coverage; publish GitHub Actions status badges and Coveralls summaries on the repository README for visibility.
    • Target 70%+ backend service coverage, 60%+ frontend component coverage by end of Q1 2026.

10. Risks & Mitigations

Risk Impact Likelihood Mitigation
Frontend lacks automated tests for critical flows High (user-facing failures) Medium Prioritize Vitest/RTL setup, pair with QA to write first suites.
Storage layer differences (local vs S3) Medium (upload breakages) Medium Expand integration tests to run against localstack in CI.
OAuth flow hard to automate High (auth outages) Low Implement mocked Google provider in Playwright using MSW; rely on unit tests for token utils.
Performance regressions as job dataset grows High (slow UX) Medium Capture baseline metrics now, add API pagination/perf tests.
No contract tests for API consumers High (integration breaks) High Introduce OpenAPI schema generation, integrate spectral lint + contract tests.

11. Immediate Next Steps

  1. Bootstrap frontend unit/component testing (Vitest + RTL) and add coverage for JobFilterBar, AdvancedFiltersSheet, JobApplicationDialog.
  2. Add backend integration tests for job application and resume upsert endpoints using Supertest + fixtures.
  3. Adopt Playwright smoke suite covering end-to-end student application flow and employer job creation.
  4. Establish CI pipeline (GitHub Actions) running lint, typecheck, unit, integration, and (nightly) Playwright flows.
  5. Document test data fixtures (sample resumes, transcripts) and seed scripts for consistent local + CI setup.

This plan should be reviewed quarterly as features ship (saved jobs UI, admin moderation, WebSocket updates) so we keep coverage expectations aligned with the product roadmap.

12. Test Environment Playbook

  • Local Setup (developer machines)
    1. cp backend/.env.example backend/.env and set TEST_DATABASE_URL=sqlite:./tmp/test.db, STORAGE_DRIVER=local.
    2. cd backend && npm install && npx prisma migrate deploy && npm run test to verify migrations/tests.
    3. cd frontend && npm install && cp .env.example .env && set VITE_API_URL=http://localhost:3000/api.
    4. Run backend npm start, frontend npm run dev, seed data via node backend/prisma/seed.js if needed.
    5. For file upload testing, place sample PDFs in backend/tests/fixtures/ (see Section 13) and ensure /uploads folders are writable.
  • CI (GitHub Actions suggestion)
    1. Use node:20 container, cache ~/.npm.
    2. Spin up services: postgres:15 (if using prod parity), localstack for S3 emulation.
    3. Export env vars: DATABASE_URL, AWS_ENDPOINT, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, STORAGE_DRIVER=s3.
    4. Install deps for both apps, run lint/typecheck, npm run test (backend), npm run test -- --run (frontend once Vitest added), npx playwright test (nightly).
  • Staging/Preview
    • Mirror production infra (PostgreSQL + S3). Use anonymized seed data and rotate credentials per release.
    • Maintain staging-specific env documentation in /docs/environments/staging.md (TODO) including OAuth redirect URIs, email sandbox settings, and feature toggles.

13. Coverage & Test Data Snapshots

  • Current Coverage (Nov 2025)
    • Backend Jest: ~55% statements (services/controllers heavy), near 0% for new job resume endpoints.
    • Frontend: No automated coverage yet.
    • Track improvements via npx jest --coverage and future vitest --coverage. Publish reports to CI artifacts.
  • Fixtures & Factories
    • Sample resumes/transcripts: create under backend/tests/fixtures/{resume.pdf,transcript.pdf} (10MB max). Mark with license & anonymization notes.
    • Prisma data factories: add helpers in backend/tests/utils/factories.js to create users/jobs/resumes with default values.
    • Frontend mock data: centralize in frontend/src/pages/student/browse-jobs/__fixtures__/ for component tests; export TypeScript builders for reuse.
  • Data Refresh Cadence
    • Review fixtures quarterly or when schema changes. Ensure migrations include backward-compatible test data adjustments.
    • Document any manual steps (e.g., generating presigned URLs) in fixture README.
    • Anonymization & Rotation: Strip personal data from shared fixtures, prefer Faker-generated records, and rotate sample resumes/transcripts bi-annually with documented provenance to stay compliant with KU privacy policies.

14. Change Management & Onboarding Hooks

  • PR Integration Checklist Addendum
    • Does this change add/modify endpoints? Update contract tests/OpenAPI schema + test plan scenario table.
    • UI involving dialogs/sheets must include or update automated interaction tests or a documented manual QA plan.
    • New roles/permissions require negative tests confirming access is blocked for other roles.
  • Test Debt Tracking
    • Each missing test should create a ticket tagged test-gap with scenario ID from Section 8 and priority.
    • Revisit backlog during sprint planning; cap outstanding high-priority gaps (<3) before release.
  • Onboarding Guide for New QA/Devs
    1. Read README.md (root, backend, frontend) and this test plan.
    2. Follow Section 12 to configure environment; run baseline tests.
    3. Shadow current feature owner for 1 full sprint; co-author tests before independent work.
    4. Pair with DevOps to understand CI pipeline and release cadence.
  • Knowledge Transfer Resources
    • Maintain architecture diagrams under diagrams/ (update quarterly).
    • Record short walkthroughs (5–10 min) on setting up tests, accessible in shared drive/Confluence.
    • Track recurring manual test scripts in /docs/manual-checklists/ (future) to complement automation.