Skip to main content

STEMBlock.ai Testing Guide

Complete System Testing Instructions​

Date: December 13, 2025 Version: 1.0

🚀 Quick Start​

1. Setup Database​

cd stemblockai-backend

# Make sure PostgreSQL is running
# Then run the migration
npx prisma migrate deploy

# Or in development
npx prisma migrate dev

# Generate Prisma client
npx prisma generate

2. Start Backend Server​

cd stemblockai-backend
npm run dev

# Backend should be running on http://localhost:3001

3. Start Frontend Server​

cd stemblockai-frontend
npm run dev

# Frontend should be running on http://localhost:3000

📋 Testing Checklist​

Mobile Navigation Testing ✅​

Objective: Verify mobile-responsive navigation works correctly

Test Steps:

  1. Desktop View (>768px)

    • Open http://localhost:3000 and login
    • Verify navigation links are visible horizontally
    • Verify user info displayed in top-right
    • Click each navigation link to ensure routing works
    • Hover over links to see hover effects

  2. Mobile View (<768px)

    • Resize browser to < 768px or use device toolbar
    • Verify hamburger menu icon appears
    • Click hamburger icon - menu should slide in
    • Verify menu shows user info at top
    • Click navigation link - menu should close and navigate
    • Click hamburger again to close menu
    • Test on actual mobile device (iPhone/Android)

  3. Accessibility

    • Tab through navigation using keyboard
    • Press Enter on hamburger button to open menu
    • Press Escape to close menu
    • Verify screen reader announces navigation (if available)
    • Check ARIA labels are present in inspector

Expected Results:

  • ✅ Navigation works on all screen sizes
  • ✅ Smooth animations
  • ✅ Keyboard accessible
  • ✅ Touch-friendly on mobile

Invitation System Testing ✅​

Backend API Testing​

1. Create Invitation (Admin/Coach)

# Login as admin or coach first to get token
# Then create invitation

curl -X POST http://localhost:3001/api/v1/invitations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "inviteeEmail": "newstudent@example.com",
    "inviteeRole": "STUDENT",
    "metadata": {
      "message": "Welcome to our class!"
    }
  }'

Expected Response:

{
  "data": {
    "id": "uuid",
    "inviteeEmail": "newstudent@example.com",
    "inviteeRole": "STUDENT",
    "token": "secure_token_here",
    "status": "PENDING",
    "expiresAt": "2025-12-20T...",
    "invitationLink": "http://localhost:3000/register?token=secure_token_here"
  },
  "meta": {
    "message": "Invitation created successfully",
    "timestamp": "..."
  }
}

Test Cases:

  • Create invitation as Admin → Should work for all roles
  • Create invitation as Coach → Should work for Student/Parent only
  • Try creating invitation for existing email → Should fail
  • Try creating duplicate pending invitation → Should fail
  • Verify invitation link is generated correctly

2. List Invitations

curl -X GET http://localhost:3001/api/v1/invitations \
  -H "Authorization: Bearer YOUR_TOKEN"

# With filters
curl -X GET "http://localhost:3001/api/v1/invitations?status=PENDING&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Test Cases:

  • Admin sees all invitations
  • Coach sees only their own invitations
  • Pagination works correctly
  • Filters work (status, role)

3. Get Invitation by Token (Public)

curl -X GET http://localhost:3001/api/v1/invitations/TOKEN_HERE

Test Cases:

  • Valid token returns invitation details
  • Invalid token returns 404
  • Expired token returns error and marks as expired
  • Accepted token returns error

4. Accept Invitation

curl -X POST http://localhost:3001/api/v1/invitations/TOKEN_HERE/accept \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Student",
    "password": "SecurePass123"
  }'

Expected Response:

{
  "data": {
    "id": "user_uuid",
    "email": "newstudent@example.com",
    "role": "STUDENT",
    "firstName": "Alex",
    "lastName": "Student",
    "accessToken": "jwt_token_here"
  },
  "meta": {
    "message": "Account created successfully",
    "timestamp": "..."
  }
}

Test Cases:

  • Valid invitation creates user account
  • User can login with created credentials
  • Student auto-enrolled in class (if metadata.classId provided)
  • Invitation marked as ACCEPTED
  • Cannot accept same invitation twice

5. Revoke Invitation

curl -X DELETE http://localhost:3001/api/v1/invitations/INVITATION_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Test Cases:

  • Inviter can revoke their own invitation
  • Admin can revoke any invitation
  • Other users cannot revoke
  • Only pending invitations can be revoked
  • Revoked invitation cannot be accepted

Frontend UI Testing​

1. Invitations List Page

Access: http://localhost:3000/admin/invitations (as Admin or Coach)

Test Steps:

  • Page loads without errors
  • "Invite User" button is visible
  • Invitations list displays correctly
  • Status badges show correct colors
  • Role badges show correct colors
  • Filter buttons work (All, Pending, Accepted, Expired)
  • Pagination appears if >20 invitations
  • "Copy Link" button copies invitation URL
  • "Revoke" button shows confirmation dialog
  • After revoke, list refreshes

2. Create Invitation Modal

Test Steps:

  • Click "Invite User" button
  • Modal appears with form
  • Close button (×) closes modal
  • Email field validates email format
  • Role dropdown has all options (Student, Coach, Parent, Admin)
  • Message field is optional
  • Submit with invalid email shows error
  • Submit with valid data shows success
  • Success view shows invitation link
  • "Copy" button copies link to clipboard
  • "Done" button closes modal and refreshes list

3. Register Page with Invitation

Test Steps:

  1. Without Invitation (Normal Registration)

    • Go to http://localhost:3000/register
    • Page shows "Join the adventure! 🚀"
    • Role selection buttons work
    • Google sign-in button visible
    • Form validates all fields
    • Student registration requires age/grade
    • Coach/Parent registration skips age/grade
    • Successful registration redirects to dashboard

  2. With Invitation Token

    • Go to http://localhost:3000/register?token=VALID_TOKEN
    • Shows loading state while fetching invitation
    • Page changes to "Complete your invitation! 🎉"
    • Blue info box shows "You've been invited as..."
    • Email field is hidden (pre-filled)
    • Role selection is hidden (pre-set)
    • Google sign-in button is hidden
    • Only shows: First Name, Last Name, Password
    • Form validation works
    • Submit creates account and logs in
    • Redirects to appropriate dashboard

  3. With Invalid/Expired Token

Loading States Testing ✅​

Objective: Verify consistent loading states across the app

Test Locations:

  1. Login page while logging in
  2. Dashboard while loading assignments
  3. Invitation page while loading invitations
  4. Register page while loading invitation

Test Steps:

  • Trigger loading state (slow network if needed)
  • Verify LoadingState component displays
  • Verify spinner animation works
  • Verify message is displayed
  • Verify screen reader compatibility (role="status")

Component Variations:

// Spinner (default)
<LoadingState message="Loading..." />

// Skeleton loader
<LoadingState type="skeleton" />

// Dots animation
<LoadingState type="dots" message="Processing..." />

🔍 Integration Testing​

End-to-End Invitation Flow​

Complete flow from invitation to login:

  1. Admin Creates Invitation

    • Login as admin
    • Go to /admin/invitations
    • Click "Invite User"
    • Fill form: email, role (STUDENT), message
    • Click "Send Invitation"
    • Copy invitation link

  2. Student Accepts Invitation

    • Open invitation link in incognito/private window
    • Verify invitation details display correctly
    • Fill form: First Name, Last Name, Password
    • Click "Accept Invitation"
    • Verify account created
    • Verify redirected to student dashboard
    • Verify can navigate using mobile menu (if on mobile)

  3. Verify in Admin Panel

    • Return to admin panel
    • Go to /admin/invitations
    • Find invitation in list
    • Verify status changed to "ACCEPTED"
    • Go to /admin/users
    • Verify new user appears in list

  4. Student Logs Out and In

    • Click logout
    • Go to /login
    • Enter created credentials
    • Verify successful login
    • Verify student dashboard loads

🐛 Error Scenarios Testing​

Edge Cases & Error Handling​

  1. Duplicate Email

    • Try creating invitation for existing user email
    • Should show error: "A user with this email already exists"

  2. Duplicate Invitation

    • Create invitation for email
    • Try creating another pending invitation for same email
    • Should show error: "A pending invitation already exists"

  3. Expired Invitation

    • Create invitation
    • Manually update expiresAt in database to past date
    • Try accessing invitation token
    • Should show error and mark as EXPIRED

  4. Already Accepted Invitation

    • Accept an invitation
    • Try accessing same token again
    • Should show error: "This invitation has been accepted"

  5. Permission Testing

    • Try creating Admin invitation as Coach
    • Should show error: "You do not have permission"
    • Try revoking other user's invitation
    • Should show error: "You do not have permission"

  6. Invalid Token

    • Go to /register?token=INVALID_TOKEN
    • Should show error: "Invalid or expired invitation link"
    • Falls back to normal registration

📱 Responsive Design Testing​

Test on Multiple Devices​

Breakpoints to Test:

  • 320px (Small phone)
  • 375px (iPhone)
  • 768px (Tablet)
  • 1024px (Desktop)
  • 1440px (Large desktop)

Pages to Test:

  • Login page
  • Register page
  • Register page with invitation
  • Admin invitations list
  • Student/Coach/Admin dashboards
  • Create invitation modal

What to Check:

  • Navigation adapts correctly
  • Forms remain usable
  • Buttons are touch-friendly (44px min)
  • Text is readable (not too small)
  • No horizontal scrolling
  • Images/cards stack on mobile
  • Modals fit on screen

♿ Accessibility Testing​

WCAG 2.1 AA Compliance​

Tools:

  • Chrome Lighthouse
  • axe DevTools
  • WAVE browser extension

Test Steps:

  1. Run Lighthouse Audit

    # In Chrome DevTools
    Lighthouse → Accessibility → Generate Report
    • Score ≥ 90
    • Fix any warnings/errors

  2. Keyboard Navigation

    • Tab through all interactive elements
    • Enter/Space activates buttons
    • Escape closes modals
    • Focus indicators visible
    • No keyboard traps

  3. Screen Reader Testing (if available)

    • Navigation announced correctly
    • Form labels read properly
    • Error messages announced
    • Loading states announced
    • Button purposes clear

  4. Color Contrast

    • All text meets 4.5:1 ratio
    • Interactive elements meet 3:1 ratio
    • Use axe DevTools to verify

  5. ARIA Labels

    • All buttons have labels
    • All form inputs have labels
    • All icons have labels
    • Live regions properly marked

🎯 Performance Testing​

Metrics to Monitor​

Target Metrics:

  • First Contentful Paint: < 1.5s
  • Time to Interactive: < 3.5s
  • Cumulative Layout Shift: < 0.1
  • Largest Contentful Paint: < 2.5s

Test Steps:

  1. Run Lighthouse Performance Audit

    • Score ≥ 90
    • Check Core Web Vitals
    • Review opportunities

  2. Network Testing

    • Test on Fast 3G network
    • Test on Slow 3G network
    • Verify loading states show immediately

  3. Bundle Size

    npm run build
    # Check .next/static size
    • Initial load < 250KB
    • No unnecessary dependencies

✅ Testing Sign-Off​

Before Production Deployment​

Critical Path Testing:

  • User can register (normal flow)
  • User can register via invitation
  • User can login
  • Navigation works on mobile
  • Navigation works on desktop
  • Admin can create invitations
  • Coach can create invitations
  • Student/Parent cannot create invitations
  • Invitations can be accepted
  • Invitations can be revoked
  • All CRUD operations work

Cross-Browser Testing:

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)
  • Mobile Safari (iOS)
  • Mobile Chrome (Android)

Security Testing:

  • SQL injection attempts blocked
  • XSS attempts blocked
  • CSRF protection in place
  • Passwords hashed (never stored plaintext)
  • JWT tokens expire correctly
  • Role-based access enforced

📊 Test Results Template​

## Test Run: [Date]

**Tester:** [Name]
**Environment:** [Dev/Staging/Prod]
**Browser:** [Chrome/Firefox/etc]
**Device:** [Desktop/Mobile/Tablet]

### Results:

| Feature | Status | Notes |
|---------|--------|-------|
| Mobile Navigation | ✅ Pass | - |
| Create Invitation | ✅ Pass | - |
| Accept Invitation | ✅ Pass | - |
| Revoke Invitation | ✅ Pass | - |
| Loading States | ✅ Pass | - |
| Accessibility | ⚠️ Warning | Color contrast issue on one button |

### Issues Found:

1. [Issue description]
   - Severity: High/Medium/Low
   - Steps to reproduce
   - Expected vs Actual behavior

### Recommendations:

- [Improvement suggestion 1]
- [Improvement suggestion 2]

🆘 Troubleshooting​

Common Issues​

1. Database Connection Error

Error: P1001: Can't reach database server

Solution: Make sure PostgreSQL is running:

# macOS
brew services start postgresql

# Linux
sudo systemctl start postgresql

# Check if running
psql -U postgres -c "SELECT version();"

2. Prisma Client Not Generated

Error: @prisma/client did not initialize yet

Solution:

cd stemblockai-backend
npx prisma generate

3. Port Already in Use

Error: Port 3000 is already in use

Solution:

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
PORT=3001 npm run dev

4. CORS Error in Browser

Access to XMLHttpRequest blocked by CORS policy

Solution: Check backend CORS configuration allows frontend origin

📝 Next Steps After Testing​

  1. Document All Issues

    • Create GitHub issues for bugs
    • Tag with severity levels
    • Assign to appropriate team members

  2. Performance Optimization

    • Address Lighthouse recommendations
    • Optimize images
    • Implement code splitting

  3. Accessibility Fixes

    • Fix all WCAG violations
    • Add missing ARIA labels
    • Improve keyboard navigation

  4. User Acceptance Testing

    • Get real users to test
    • Collect feedback
    • Iterate on design

  5. Production Deployment

    • Create deployment checklist
    • Set up monitoring (Sentry, LogRocket)
    • Configure analytics (Google Analytics, Mixpanel)
    • Set up error tracking

Testing completed and signed off by: _________________ Date: _________________ Ready for Production: ☐ Yes ☐ No