tests/integration/PROFILE_TESTING_GUIDE.md

Profile Management Testing Guide

Complete guide for testing the hierarchical profile management system.

🎯 Test Scenarios

Scenario 1: Platform Admin Manages Field Agent Profiles

Actors:

• Lewis Kamau (Platform Admin) - lewis.kamau421@gmail.com
• Lesley Wanjiru (Field Agent) - lesley@example.com
• Irene (Field Agent) - irene@example.com (if invited)

Flow:

1. Lewis logs in as platform admin
2. Lewis finds Lesley's user account
3. Lewis views Lesley's profile and completion status
4. Lewis updates Lesley's:
   • Basic info (emergency contacts)
   • Health info (blood type, allergies)
   • PPE sizes (shirt, helmet, shoes)
5. Lewis validates Lesley's profile is complete
6. All changes are logged in audit trail

📋 Prerequisites

1. Lesley Must Accept Invitation First

# Run invitation acceptance test
node tests/integration/test_accept_invitation.js <invitation_token>

This creates Lesley's user account and returns her user_id.

2. Get Lesley's User ID

After acceptance, note the user_id from the response:

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "lesley@example.com",
    "full_name": "Lesley Wanjiru"
  }
}

🧪 Running the Tests

Test 1: Admin Authentication

node tests/integration/test_admin_edit_profiles.js

This test:

• ✅ Logs in as Lewis (platform admin)
• ✅ Finds Lesley's account
• ✅ Shows available profile endpoints
• ✅ Demonstrates the workflow

Test 2: Manual Profile Management

Once you have Lesley's user_id, use these curl commands:

Get Lesley's Complete Profile

curl -X GET https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id} \
  -H "Authorization: Bearer {admin_token}"

Check Edit Permissions

curl -X GET https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id}/permissions \
  -H "Authorization: Bearer {admin_token}"

Expected response:

{
  "can_edit_basic_info": true,
  "can_edit_health_info": true,
  "can_edit_ppe_sizes": true,
  "can_edit_location": true,
  "can_edit_financial_accounts": true,
  "can_upload_documents": true,
  "can_edit_role": true,
  "can_edit_status": true,
  "can_assign_assets": true
}

Update Basic Info

curl -X PUT https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id}/basic \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "emergency_contact_name": "Jane Wanjiru",
    "emergency_contact_phone": "+254723456789",
    "phone_alternate": "+254798765432"
  }'

Update Health Info

curl -X PUT https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id}/health \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "blood_type": "O+",
    "allergies": "None",
    "chronic_conditions": "None",
    "medications": "None",
    "last_medical_check": "2024-01-15",
    "medical_notes": "Fit for field work"
  }'

Update PPE Sizes

curl -X PUT https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id}/ppe \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "height": "165cm",
    "weight": "60kg",
    "shirt_size": "M",
    "pants_size": "30",
    "shoe_size": "38",
    "helmet_size": "M",
    "glove_size": "M",
    "vest_size": "M"
  }'

Validate Profile Completion

curl -X GET https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id}/validation \
  -H "Authorization: Bearer {admin_token}"

Expected response:

{
  "is_valid": true,
  "missing_fields": [],
  "invalid_fields": {},
  "warnings": []
}

🔍 Verification Steps

1. Check Profile Completion

curl -X GET https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id} \
  -H "Authorization: Bearer {admin_token}"

Look for:

{
  "completion_status": {
    "basic_info": true,
    "health_info": true,
    "ppe_sizes": true,
    "financial_accounts": false,
    "documents": false,
    "location": true,
    "completion_percentage": 67
  }
}

2. Verify Audit Logs

Check database:

SELECT 
  action,
  description,
  user_email,
  changes,
  created_at
FROM audit_logs
WHERE entity_type = 'user'
  AND entity_id = '{user_id}'
ORDER BY created_at DESC
LIMIT 10;

Expected logs:

• update - User updated their basic profile
• update - Manager updated user's health information
• update - Manager updated user's PPE sizes

🎭 Test Different Permission Levels

Test 1: Platform Admin (Lewis)

✅ Can edit ALL fields for ANY user

# Lewis can edit Lesley's profile
PUT /api/v1/profile/{lesley_id}/basic
PUT /api/v1/profile/{lesley_id}/health
PUT /api/v1/profile/{lesley_id}/ppe

Test 2: Field Agent (Lesley) - Self Edit

✅ Can edit OWN profile (limited fields)

# Lesley can edit her own profile
PUT /api/v1/profile/me/basic  # Only phone_alternate, display_name
PUT /api/v1/profile/me/health  # All fields
PUT /api/v1/profile/me/ppe  # All fields

Test 3: Field Agent (Lesley) - Edit Others

❌ CANNOT edit other users' profiles

# Lesley CANNOT edit Irene's profile
PUT /api/v1/profile/{irene_id}/basic  # 403 Forbidden

Test 4: Project Manager - Edit Team Members

✅ Can edit field agents in their projects

# Manager can edit their team's profiles
PUT /api/v1/profile/{field_agent_id}/basic
PUT /api/v1/profile/{field_agent_id}/ppe

📊 Expected Results

Profile Completion Progression

Initial State (After Invitation Acceptance):

{
  "completion_percentage": 17,
  "basic_info": true,  // Name, phone from invitation
  "health_info": false,
  "ppe_sizes": false,
  "financial_accounts": false,
  "documents": false,
  "location": false
}

After Admin Updates:

{
  "completion_percentage": 67,
  "basic_info": true,  // ✅ Emergency contacts added
  "health_info": true,  // ✅ Blood type, allergies added
  "ppe_sizes": true,  // ✅ All sizes added
  "financial_accounts": false,  // ⏳ Lesley needs to add
  "documents": false,  // ⏳ Lesley needs to upload
  "location": true  // ✅ From invitation
}

Fully Complete:

{
  "completion_percentage": 100,
  "basic_info": true,
  "health_info": true,
  "ppe_sizes": true,
  "financial_accounts": true,  // ✅ Lesley added payout details
  "documents": true,  // ✅ Lesley uploaded ID
  "location": true
}

🐛 Troubleshooting

Issue: "User not found"

Solution: Ensure Lesley accepted the invitation first

node tests/integration/test_accept_invitation.js <token>

Issue: "403 Forbidden"

Solution: Check you're using admin token, not field agent token

# Get fresh admin token
node tests/integration/test_admin_edit_profiles.js

Issue: "422 Validation Error"

Solution: Check field formats:

• Phone: Must start with + (e.g., +254712345678)
• Blood type: Must be one of: A+, A-, B+, B-, AB+, AB-, O+, O-
• Sizes: Must be: XS, S, M, L, XL, XXL, XXXL

Issue: Cannot find user_id

Solution: Implement user search endpoint

# Add to src/app/api/v1/users.py
@router.get("/users")
async def search_users(
    email: Optional[str] = None,
    current_user: User = Depends(get_current_active_user),
    db: Session = Depends(get_db)
):
    query = db.query(User).filter(User.deleted_at == None)
    if email:
        query = query.filter(User.email == email)
    return query.all()

🎯 Success Criteria

✅ Admin can login successfully ✅ Admin can find field agent's account ✅ Admin can view field agent's profile ✅ Admin can check edit permissions (all should be true) ✅ Admin can update basic info ✅ Admin can update health info ✅ Admin can update PPE sizes ✅ Profile completion percentage increases ✅ Profile validation shows no errors ✅ All changes appear in audit logs ✅ Field agent can see updated profile when they login

📝 Next Steps

After completing profile management tests:

1. Financial Accounts - Test adding payout details
2. Document Upload - Test uploading ID, license
3. Asset Assignment - Test assigning equipment to field agents
4. Project Creation - Create projects and assign team members
5. Ticket Management - Create and assign tickets to field agents

🔗 Related Tests

• test_invitation_flow.js - Create and send invitations
• test_accept_invitation.js - Accept invitation and create account
• test_auth_api.js - Basic authentication tests
• test_profile_management.py - Python unit tests for profile service

📚 Documentation

• docs/agent/PROFILE_MANAGEMENT_IMPLEMENTATION.md - Implementation details
• src/app/schemas/profile.py - Profile schemas and validation
• src/app/services/profile_service.py - Business logic and permissions
• src/app/api/v1/profile.py - API endpoints