fitaiProto/docs/TESTING_GUIDE.md

FitAI Report Generation System - Testing Guide

Overview

This document provides comprehensive testing procedures for the FitAI Report Generation System, covering:

• API endpoints
• Access control
• PDF generation
• Mobile-to-admin data flow
• Edge cases

Prerequisites

1. Admin App Running

   cd apps/admin
   npm run dev
   # Should be running on http://localhost:3000
   

2. Database Populated

   • Ensure test users exist with different roles
   • Ensure attendance, nutrition, and hydration data exists

1. API Endpoint Testing

1.1 Trainer-Client Assignment API

Test: Create Assignment

# As Admin
curl -X POST http://localhost:3000/api/trainer-client \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -d '{
    "trainerId": "user_trainer_123",
    "clientId": "user_client_456"
  }'

Expected Response (201):

{
  "assignment": {
    "id": "assignment_...",
    "trainerId": "user_trainer_123",
    "clientId": "user_client_456",
    "assignedAt": "2024-01-15T...",
    "isActive": true
  }
}

Test: Get Assignments

# Get all assignments
curl http://localhost:3000/api/trainer-client \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

# Filter by trainer
curl "http://localhost:3000/api/trainer-client?trainerId=user_trainer_123" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

Test: Delete Assignment

curl -X DELETE http://localhost:3000/api/trainer-client/<ASSIGNMENT_ID> \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

Expected Response (200):

{
  "success": true,
  "message": "Assignment deactivated successfully"
}

1.2 Report Generation API

Test: Get JSON Report

curl "http://localhost:3000/api/reports/user/<USER_ID>?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer <TOKEN>"

Expected Response (200):

{
  "userId": "...",
  "user": { ... },
  "weeklyCheckIns": [ ... ],
  "nutrition": { ... },
  "hydration": { ... },
  "goals": { ... },
  "recommendations": { ... },
  "generatedAt": "..."
}

Test: Get PDF Report

curl "http://localhost:3000/api/reports/user/<USER_ID>?startDate=2024-01-01&endDate=2024-01-31&format=pdf" \
  -H "Authorization: Bearer <TOKEN>" \
  --output report.pdf

Validation:

• File should download as FitAI_Report_<Name>_<Dates>.pdf
• File should be valid PDF (starts with %PDF)
• File should contain all sections

Test: Access Control

As Client (own report only):

# Should succeed - own report
curl "http://localhost:3000/api/reports/user/<CLIENT_ID>" \
  -H "Authorization: Bearer <CLIENT_TOKEN>"

# Should fail - other's report
curl "http://localhost:3000/api/reports/user/<OTHER_ID>" \
  -H "Authorization: Bearer <CLIENT_TOKEN>"

Expected: 403 Forbidden

As Trainer (assigned clients only):

# Should succeed - assigned client
curl "http://localhost:3000/api/reports/user/<ASSIGNED_CLIENT_ID>" \
  -H "Authorization: Bearer <TRAINER_TOKEN>"

# Should fail - non-assigned client
curl "http://localhost:3000/api/reports/user/<NON_ASSIGNED_CLIENT_ID>" \
  -H "Authorization: Bearer <TRAINER_TOKEN>"

Expected: 403 Forbidden

As Admin (gym users only):

# Should succeed - same gym
curl "http://localhost:3000/api/reports/user/<SAME_GYM_CLIENT_ID>" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

# Should fail - different gym
curl "http://localhost:3000/api/reports/user/<DIFFERENT_GYM_CLIENT_ID>" \
  -H "Authorization: Bearer <ADMIN_TOKEN>"

Expected: 403 Forbidden

1.3 Nutrition API

Test: Save Daily Nutrition

curl -X POST http://localhost:3000/api/nutrition \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "date": "2024-01-15",
    "totalCalories": 2100,
    "calorieGoal": 2000,
    "meals": [
      { "type": "breakfast", "name": "Oatmeal", "calories": 300 },
      { "type": "lunch", "name": "Salad", "calories": 500 }
    ]
  }'

Expected Response (200):

{
  "id": "nutrition_...",
  "userId": "...",
  "date": "2024-01-15",
  "totalCalories": 2100,
  "calorieGoal": 2000
}

Test: Get Nutrition by Date

curl "http://localhost:3000/api/nutrition?date=2024-01-15" \
  -H "Authorization: Bearer <TOKEN>"

Test: Get Nutrition Range

curl "http://localhost:3000/api/nutrition?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer <TOKEN>"

1.4 Hydration API

Test: Save Daily Hydration

curl -X POST http://localhost:3000/api/hydration \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "date": "2024-01-15",
    "totalWater": 2500,
    "waterGoal": 2000,
    "entries": [
      { "amount": 250, "time": "08:00" },
      { "amount": 500, "time": "10:30" }
    ]
  }'

Test: Get Hydration

curl "http://localhost:3000/api/hydration?date=2024-01-15" \
  -H "Authorization: Bearer <TOKEN>"

2. Web UI Testing

2.1 Reports Page

URL: http://localhost:3000/reports

Test Scenarios:

1. Admin View

   • Should see all clients in dropdown
   • Should be able to select any client
   • Should see all report sections
   • Should see "Export PDF" button

2. Trainer View

   • Should only see assigned clients in dropdown
   • Should see message if no clients assigned
   • Should be able to generate reports for assigned clients

3. Client View

   • Should only see own name in dropdown
   • Should be auto-selected
   • Should be able to view own report

2.2 Trainer-Client Assignments Page

URL: http://localhost:3000/trainer-clients

Test Scenarios:

1. Create Assignment

   • Select trainer from dropdown
   • Select client from dropdown
   • Click "Assign"
   • Should see new assignment in Active list

2. Remove Assignment

   • Click remove button on assignment
   • Confirm deletion
   • Assignment should move to Inactive list

3. Validation

   • Cannot assign trainer to non-trainer
   • Cannot assign client to non-client
   • Cannot create duplicate active assignments

3. ISO Week Calculations

Test Week Boundaries

Date	Monday	Sunday
2024-01-01 (Mon)	2024-01-01	2024-01-07
2024-01-02 (Tue)	2024-01-01	2024-01-07
2024-01-07 (Sun)	2024-01-01	2024-01-07
2024-01-08 (Mon)	2024-01-08	2024-01-14

Test Weekly Stats Calculation

Test Data:

• Monday: 2 check-ins, 120 minutes total
• Tuesday: 1 check-in, 60 minutes
• Wednesday: 0 check-ins
• Thursday: 3 check-ins, 180 minutes
• Friday: 2 check-ins, 100 minutes
• Saturday: 0 check-ins
• Sunday: 1 check-in, 45 minutes

Expected Results:

{
  weekStart: "2024-01-01",
  weekEnd: "2024-01-07",
  totalCheckIns: 9,
  totalTimeMinutes: 505,
  averageDurationMinutes: 63 // 505 / 8 (only completed sessions)
}

4. PDF Generation Testing

Test: Generate PDF with All Sections

1. Navigate to Reports page
2. Select user with:
   • At least 1 week of attendance data
   • At least 3 days of nutrition data
   • At least 3 days of hydration data
   • At least 1 active goal
   • At least 1 recommendation
3. Set date range to 30 days
4. Click "Export PDF"
5. Validate PDF contains:
   • Header with "FitAI User Report"
   • User information section
   • Report period section
   • Weekly check-ins table
   • Nutrition summary with daily breakdown
   • Hydration summary with daily breakdown
   • Active goals with progress
   • Completed goals
   • Profile changes (if any)
   • Recommendations
   • Footer with page numbers

Test: Generate PDF with No Data

1. Select user with no activity
2. Set date range to 30 days
3. Export PDF
4. Validate:
   • All sections show "No data available"
   • Charts/tables are empty
   • PDF still generates successfully

Test: Generate PDF with Large Date Range

1. Set date range to 90 days
2. Export PDF
3. Validate:
   • PDF contains summary data (not all 90 days)
   • Charts are readable
   • No performance issues

5. Mobile-to-Admin Data Flow

Test: Nutrition Data Flow

1. Mobile App:

   // Add nutrition data
   await saveDailyNutrition({
     date: "2024-01-15",
     totalCalories: 2200,
     calorieGoal: 2000,
     meals: [...]
   });
   

2. Verify in Database:

   SELECT * FROM daily_nutrition
   WHERE user_id = '<USER_ID>'
   AND date = '2024-01-15';
   

3. Verify in Admin Reports:

   • Navigate to Reports page
   • Select same user
   • Set date range to include 2024-01-15
   • Check Nutrition Summary section
   • Should show 2200 calories, 2000 goal

Test: Hydration Data Flow

1. Mobile App:

   await saveDailyHydration({
     date: "2024-01-15",
     totalWater: 2500,
     waterGoal: 2000,
     entries: [...]
   });
   

2. Verify in Admin Reports:

   • Check Hydration Summary section
   • Should show 2500ml, 2000ml goal

6. Edge Cases

6.1 Empty Data

• User with no attendance
• User with no nutrition
• User with no hydration
• User with no goals
• User with no recommendations

6.2 Invalid Inputs

• Invalid date format → 400 Bad Request
• Future dates → Should work (no validation)
• Date range > 1 year → Should work
• Missing userId → 400 Bad Request
• Non-existent userId → 404 Not Found

6.3 Access Control

• Expired token → 401 Unauthorized
• Invalid token → 401 Unauthorized
• User accessing another user → 403 Forbidden
• Deleted user → 404 Not Found

6.4 Performance

• 100 days of data → Should load < 5 seconds
• PDF with 100 days → Should generate < 10 seconds
• Multiple concurrent requests → Should handle gracefully

7. Automated Tests

Run automated tests:

cd apps/admin

# Run all tests
npm test

# Run specific test file
npx jest src/app/api/reports/__tests__/report-generation.test.ts

# Run with coverage
npm test -- --coverage

8. Troubleshooting

Common Issues

1. "Unauthorized" Error

   • Ensure Clerk authentication is working
   • Check token is being passed correctly
   • Verify user exists in database

2. "Forbidden" Error

   • Check user role permissions
   • For trainers: ensure assignment exists
   • For admins: ensure same gym

3. Empty Report Data

   • Check data exists in database
   • Verify date range includes data dates
   • Check API endpoints return data

4. PDF Not Downloading

   • Check browser console for errors
   • Ensure PDF generation completes
   • Try different browser

9. Test Users

Create test users for manual testing:

const testUsers = {
  superAdmin: {
    id: "user_test_superadmin",
    email: "superadmin@test.com",
    role: "superAdmin",
  },
  admin: {
    id: "user_test_admin",
    email: "admin@test.com",
    role: "admin",
    gymId: "gym_test",
  },
  trainer: {
    id: "user_test_trainer",
    email: "trainer@test.com",
    role: "trainer",
    gymId: "gym_test",
  },
  client: {
    id: "user_test_client",
    email: "client@test.com",
    role: "client",
    gymId: "gym_test",
  },
};

10. Success Criteria

All tests should pass:

• Trainer-client CRUD operations work
• Role-based access control enforced
• Reports generate with all sections
• PDF export works correctly
• Mobile data syncs to admin
• ISO week calculations correct
• Edge cases handled gracefully
• Performance acceptable