# StudyBuddy Testing Guide

## Test Accounts

All test accounts use the same password: **TestPass123!**

### Available Test Accounts

| Role | Email | Display Name | Grade Band | Access |
|------|-------|--------------|------------|--------|
| **Student** | student@studybuddy.test | Test Student | None | Full access to all areas |
| **K-8 Student** | k8student@studybuddy.test | K-8 Student | K-8 | Limited to Grade School hub |
| **Higher Learning Student** | higherstudent@studybuddy.test | Higher Learning Student | Higher Learning | Limited to Higher Learning hub |
| **Teacher** | teacher@studybuddy.test | Test Teacher | None | Full access to all areas |
| **Parent** | parent@studybuddy.test | Test Parent | None | Full access to all areas |
| **Admin** | admin@studybuddy.test | Test Admin | None | Full access to all areas |

---

## Grade Band Access Control

StudyBuddy supports **grade band restrictions** to provide age-appropriate learning environments:

### Grade Bands

1. **No Grade Band (Default)**
   - Full access to all areas (K-8 Hub, Higher Learning Hub, general study pages)
   - No restrictions on navigation
   - Suitable for teachers, parents, admins, and general students

2. **K-8 Grade Band**
   - Restricted to Grade School content (`/grade-school.html`)
   - Redirected if attempting to access Higher Learning pages
   - Age-appropriate interface and categories
   - Suitable for elementary and middle school students

3. **Higher Learning Grade Band**
   - Restricted to Higher Learning content (`/higher-learning.html`)
   - Redirected if attempting to access Grade School pages
   - Advanced topics and college-prep materials
   - Suitable for high school and college students

### How It Works

- When a user with a `grade_band` setting visits a page for a different band, they are automatically redirected to their appropriate hub
- The system displays a friendly message before redirecting
- Users without a grade band setting have full access to browse all areas
- Teachers, parents, and admins typically have no grade band restrictions
- **Category Filtering on Study Page:**
  - K-8 students only see Grade School categories in the study.html Categories tab
  - Higher Learning students only see Higher Learning categories in the study.html Categories tab
  - Users without grade_band restrictions see all categories organized by level

---

## Role Permissions Matrix

### 🎓 Student Role

**Can Do:**
- ✅ Create tests (AI-generated or manual)
- ✅ Take tests
- ✅ Print tests (without answer key)
- ✅ View their own tests in "My Tests"
- ✅ View test metrics and performance
- ✅ Rate and comment on public tests
- ✅ Browse and search public skills/categories
- ✅ View their account activity

**Cannot Do:**
- ❌ Print tests with answer key activated
- ❌ Create lesson plans
- ❌ Edit tests created by others
- ❌ Delete tests created by others
- ❌ Access admin features

---

### 👨‍🏫 Teacher Role

**Can Do:**
- ✅ Everything a student can do, PLUS:
- ✅ Create lesson plans
- ✅ Print tests with answer key (teacher copy)
- ✅ Delete their own tests
- ✅ Delete their own lesson plans
- ✅ View enhanced metrics
- ✅ Access teacher-specific features

**Cannot Do:**
- ❌ Edit tests created by other users (unless admin)
- ❌ Delete tests created by other users
- ❌ Access admin-only features

---

### 👪 Parent Role

**Can Do:**
- ✅ Everything a student can do, PLUS:
- ✅ Create lesson plans
- ✅ Print tests with answer key (parent copy)
- ✅ Delete their own tests
- ✅ Delete their own lesson plans
- ✅ Monitor child's progress (if linked accounts are implemented)

**Cannot Do:**
- ❌ Edit tests created by other users (unless admin)
- ❌ Delete tests created by other users
- ❌ Access admin-only features

---

### 🔧 Admin Role

**Can Do:**
- ✅ **EVERYTHING** - Full system access
- ✅ Edit ANY test (regardless of creator)
- ✅ Delete ANY test
- ✅ Delete ANY lesson plan
- ✅ View ALL user feedback
- ✅ Manage categories
- ✅ Access admin dashboard
- ✅ View all user activity
- ✅ Moderate comments
- ✅ Override permissions

**Special Admin Powers:**
- Can impersonate other roles for testing
- Full database access through admin endpoints
- Can modify user roles
- Can view system-wide metrics

---

## Test Ownership & Editing Rules

### Test Creation
- Any signed-in user can create a test
- The creator is automatically set as the `creator_user_id`
- Test activity is tracked in the database

### Test Editing
- **Only the original creator** can edit their test
- **Exception:** Admins can edit ANY test
- Edit access is verified via `creator_user_id` match

### Test Deletion
- **Students:** Can delete their own tests only
- **Teachers:** Can delete their own tests only
- **Parents:** Can delete their own tests only
- **Admins:** Can delete ANY test

### Lesson Plan Ownership
- Only **Teachers**, **Parents**, and **Admins** can create lesson plans
- Students attempting to create lesson plans will be blocked
- Users can only delete their own lesson plans
- Admins can delete any lesson plan

---

## Activity Tracking

All test activity is tracked and visible in the **Account Section**:

### Tracked Activities:
1. **Test Creation** - When a user creates a new test
2. **Test Attempts** - Each time a user takes a test
3. **Test Scores** - Performance metrics for each attempt
4. **Best Scores** - Highest score per test
5. **Test Prints** - When answer keys are printed (audited)
6. **Test Edits** - When tests are modified
7. **Test Deletions** - When tests are removed
8. **Ratings & Comments** - User feedback on tests

### Activity Data Stored:
- Timestamp of activity
- User ID
- Test code
- Activity type
- Results/scores (for attempts)
- IP address (for security)

---

## Testing Scenarios

### Scenario 1: Student Experience
1. Sign in as `student@studybuddy.test`
2. Create a new test (AI or manual)
3. Take the test
4. Print the test → **Verify answer key is NOT visible**
5. Try to create a lesson plan → **Should be blocked**
6. View "My Tests" → **Should only see own tests**
7. Try to edit another user's test → **Should fail**
8. Check account activity → **Should show all personal activity**

### Scenario 2: Teacher Experience
1. Sign in as `teacher@studybuddy.test`
2. Create a test
3. Create a lesson plan → **Should succeed**
4. Print test → **Should have option for "Teacher Copy with Answers"**
5. Delete own test → **Should succeed**
6. Try to delete another user's test → **Should fail**
7. Try to edit another user's test → **Should fail (unless admin)**

### Scenario 3: Parent Experience
1. Sign in as `parent@studybuddy.test`
2. Create a test
3. Create a lesson plan → **Should succeed**
4. Print test with answer key → **Should work**
5. Delete own test → **Should succeed**
6. Access parent-specific features

### Scenario 4: Admin Powers
1. Sign in as `admin@studybuddy.test`
2. Create a test as admin
3. Edit ANY test (even created by others) → **Should succeed**
4. Delete ANY test → **Should succeed**
5. View feedback from all users
6. Access admin-only endpoints
7. Manage categories
8. Delete any lesson plan

### Scenario 5: Cross-Role Testing
1. **Student creates test** → Sign in as teacher → Try to edit → **Should fail**
2. **Teacher creates test** → Sign in as student → Try to delete → **Should fail**
3. **Any user creates test** → Sign in as admin → Edit/Delete → **Should succeed**
4. **Check activity logs** → Verify all actions are tracked

### Scenario 6: Grade Band Access Control
1. Sign in as `k8student@studybuddy.test`
2. Navigate to `/grade-school.html` → **Should work normally**
3. Try to navigate to `/higher-learning.html` → **Should redirect to grade-school.html with message**
4. Navigate to `/study.html` (Categories tab) → **Should only see Grade School categories, no Higher Learning section**
5. Sign out, sign in as `higherstudent@studybuddy.test`
6. Navigate to `/higher-learning.html` → **Should work normally**
7. Try to navigate to `/grade-school.html` → **Should redirect to higher-learning.html with message**
8. Navigate to `/study.html` (Categories tab) → **Should only see Higher Learning categories, no Grade School section**
9. Sign out, sign in as `student@studybuddy.test` (no grade band)
10. Navigate to both pages → **Should have full access to both**
11. Navigate to `/study.html` (Categories tab) → **Should see both Grade School and Higher Learning categories**

### Scenario 7: Grade Band Restrictions
1. **K-8 Student**
   - Can access Grade School categories on study page
   - Can only see Grade School section in Categories tab
   - Can create tests for K-8 topics only
   - Cannot see Higher Learning categories
   - Cannot access Higher Learning content
   - Automatically redirected if trying to access Higher Learning hub
2. **Higher Learning Student**
   - Can access Higher Learning categories on study page
   - Can only see Higher Learning section in Categories tab
   - Can create tests for advanced topics only
   - Cannot see Grade School categories
   - Cannot access Grade School content
   - Automatically redirected if trying to access Grade School hub
3. **General Student** (no grade band)
   - Full access to all hubs and categories
   - Can see both Grade School and Higher Learning sections
   - No restrictions on navigation or category access

---

## API Endpoints & Permissions

### Test Endpoints

#### `GET /api/tests/:code`
- **Public:** Anyone can view test metadata
- **Activity:** Not tracked for viewing

#### `POST /api/tests`
- **Permissions:** Any signed-in user
- **Tracks:** Creator ID, timestamp
- **Returns:** Test code

#### `PUT /api/tests/:code`
- **Permissions:** Creator only OR Admin
- **Verification:** Checks `creator_user_id` match
- **Tracks:** Edit timestamp, editor ID

#### `DELETE /api/tests/:code`
- **Student:** Own tests only
- **Teacher/Parent:** Own tests only
- **Admin:** Any test
- **Tracks:** Deletion timestamp, deleter ID

### Lesson Plan Endpoints

#### `POST /api/lessonplans`
- **Permissions:** Teacher, Parent, Admin only
- **Blocked:** Students
- **Returns:** 403 error for students

#### `DELETE /api/lessonplans/:id`
- **Permissions:** Creator only OR Admin
- **Tracks:** Deletion activity

### Activity Endpoints

#### `GET /api/users/me/activity`
- **Returns:** User's test history, attempts, scores
- **Includes:** Creation dates, attempt dates, best scores

#### `GET /api/tests/:code/attempts`
- **Permissions:** Creator or Admin
- **Returns:** All attempts for that test

---

## Setup Instructions for Testers

### 1. Create Test Accounts
Run the account creation script:
```bash
node scripts/create_test_accounts.js
```

### 2. Verify Database Tables
Ensure these tables exist:
- `StudyBuddy_users` - User accounts
- `StudyBuddy_test` - Test storage
- `StudyBuddy_attempts` - Test attempts
- `StudyBuddy_feedback` - User feedback
- `StudyBuddy_lessonplans` - Lesson plans

### 3. Test Each Role
- Sign in with each test account
- Follow the testing scenarios above
- Verify permissions work as expected
- Check activity tracking in account section

### 4. Verify Security
- Confirm students can't print answer keys
- Confirm users can't edit others' tests
- Confirm only creators (or admins) can delete
- Confirm lesson plan restrictions

---

## Common Issues & Troubleshooting

### Issue: Can't sign in
- Verify password is exactly: `TestPass123!`
- Check database connection
- Verify accounts were created successfully

### Issue: Permissions not working
- Check user role in database
- Verify JWT token includes correct role
- Check server logs for authorization errors

### Issue: Activity not tracking
- Verify database insert queries
- Check for errors in server console
- Ensure user is properly authenticated

### Issue: Can edit other user's test
- **This is expected for Admins**
- For non-admins, verify `creator_user_id` check
- Check authorization middleware

---

## Security Notes

### Password Requirements
- Minimum 8 characters
- Test accounts use: `TestPass123!`
- Production should enforce stronger passwords

### Session Management
- JWT tokens expire after 7 days
- Tokens stored in localStorage
- Role is embedded in JWT payload

### Authorization Checks
All protected routes verify:
1. Valid JWT token
2. User exists in database
3. User role has required permissions
4. Ownership (for edit/delete operations)
5. Grade band restrictions (client-side redirect for K-8 and Higher Learning hubs)

---

## Reporting Issues

When testing, please report:
1. **What you were trying to do**
2. **Which account you used**
3. **What happened vs. what should happen**
4. **Browser console errors** (F12 → Console tab)
5. **Steps to reproduce**

---

## Quick Reference

### Sign In URLs
- Production: `https://studybuddy.paynebrain.com`
- Local: `http://localhost:3001`

### Key Pages to Test
- `/study.html` - Create tests
- `/take.html` - Take tests  
- `/mytests.html` - View personal tests
- `/print.html` - Print tests
- `/account.html` - View activity
- `/lessonplans.html` - Create lesson plans (Teachers/Parents/Admins only)
- `/grade-school.html` - K-8 Grade School hub (restricted to K-8 students if grade_band set)
- `/higher-learning.html` - Higher Learning hub (restricted to Higher Learning students if grade_band set)

### Database Tables to Monitor
- `StudyBuddy_users` - User accounts and roles
  - Key fields: `id`, `email`, `role`, `grade_band`, `display_name`
  - `grade_band` values: NULL (no restriction), 'K-8', or 'Higher Learning'
- `StudyBuddy_test` - Tests and creator tracking
- `StudyBuddy_attempts` - Test attempts and scores
- `StudyBuddy_lessonplans` - Lesson plans

---

**Last Updated:** October 7, 2025  
**Version:** 1.0  
**Contact:** Report issues via Feedback button or GitHub Issues