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

```bash
# 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:
```json
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "lesley@example.com",
    "full_name": "Lesley Wanjiru"
  }
}
```

## 🧪 Running the Tests

### Test 1: Admin Authentication
```bash
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
```bash
curl -X GET https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id} \
  -H "Authorization: Bearer {admin_token}"
```

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

Expected response:
```json
{
  "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
```bash
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
```bash
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
```bash
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
```bash
curl -X GET https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id}/validation \
  -H "Authorization: Bearer {admin_token}"
```

Expected response:
```json
{
  "is_valid": true,
  "missing_fields": [],
  "invalid_fields": {},
  "warnings": []
}
```

## 🔍 Verification Steps

### 1. Check Profile Completion
```bash
curl -X GET https://kamau1-swiftops-backend.hf.space/api/v1/profile/{user_id} \
  -H "Authorization: Bearer {admin_token}"
```

Look for:
```json
{
  "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:
```sql
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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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):**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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
```bash
node tests/integration/test_accept_invitation.js <token>
```

### Issue: "403 Forbidden"
**Solution:** Check you're using admin token, not field agent token
```bash
# 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
```python
# 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