User Story

As a registered user
I want to update my profile information (name, email, and avatar photo)
So that I can keep my account information current and personalize my profile

Acceptance Criteria

Scenario 1: Successful Profile Update (Happy Path)

Given I am logged into my account
And I navigate to the profile edit page
When I update my first name to “Jane”
And I update my last name to “Smith”
And I update my email to “jane.smith@example.com”
And I upload a new avatar photo (JPEG, < 2MB)
And I click “Save Changes”
Then I see a success message “Profile updated successfully”
And my name displays as “Jane Smith” throughout the application
And my new email is saved and visible on my profile
And my new avatar photo appears on my profile and in navigation
And I remain logged in with my current session

Scenario 2: Update Name Only

Given I am on the profile edit page
When I change my first name from “John” to “Jonathan”
And I leave email and avatar unchanged
And I click “Save Changes”
Then my name updates to “Jonathan”
And my email and avatar remain unchanged
And I see confirmation “Profile updated successfully”

Scenario 3: Update Email Only

Given I am on the profile edit page
When I change my email from “old@example.com” to “new@example.com”
And I leave name and avatar unchanged
And I click “Save Changes”
Then my email updates to “new@example.com”
And my name and avatar remain unchanged
And I see confirmation “Profile updated successfully”

Scenario 4: Update Avatar Only

Given I am on the profile edit page
When I upload a new avatar photo (PNG, 500KB)
And I leave name and email unchanged
And I click “Save Changes”
Then my avatar updates to the new photo
And my name and email remain unchanged
And I see confirmation “Profile updated successfully”
And the new avatar appears immediately in the UI

Scenario 5: Required Field Validation - First Name

Given I am on the profile edit page
When I delete the contents of the “First Name” field (leaving it empty)
And I click “Save Changes”
Then the form does not submit
And I see an error message “First name is required”
And the first name field is highlighted with an error state
And focus is moved to the first name field

Scenario 6: Required Field Validation - Last Name

Given I am on the profile edit page
When I delete the contents of the “Last Name” field (leaving it empty)
And I click “Save Changes”
Then the form does not submit
And I see an error message “Last name is required”
And the last name field is highlighted with an error state

Scenario 7: Required Field Validation - Email

Given I am on the profile edit page
When I delete the contents of the “Email” field (leaving it empty)
And I click “Save Changes”
Then the form does not submit
And I see an error message “Email is required”
And the email field is highlighted with an error state

Scenario 8: Email Format Validation

Given I am on the profile edit page
When I enter an invalid email format “notanemail”
And I click “Save Changes”
Then the form does not submit
And I see an error message “Please enter a valid email address”
And the email field is highlighted with an error state

Scenario 9: Email Already Exists (Duplicate)

Given I am on the profile edit page
When I change my email to “existing@example.com” (already used by another account)
And I click “Save Changes”
Then the form does not submit
And I see an error message “This email address is already in use”
And my email remains unchanged

Scenario 10: Name Length Validation - Too Long

Given I am on the profile edit page
When I enter a first name longer than 50 characters
And I click “Save Changes”
Then the form does not submit
And I see an error message “First name must be 50 characters or less”

Scenario 11: Name Length Validation - Too Short

Given I am on the profile edit page
When I enter a first name with only 1 character
And I click “Save Changes”
Then the form does not submit
And I see an error message “First name must be at least 2 characters”

Scenario 12: Avatar File Type Validation

Given I am on the profile edit page
When I attempt to upload a file that is not an image (e.g., .pdf, .txt)
Then the upload is rejected before submission
And I see an error message “Avatar must be an image file (JPG, PNG, GIF, WEBP)”
And the file is not uploaded

Scenario 13: Avatar File Size Validation

Given I am on the profile edit page
When I attempt to upload an image larger than 2MB
Then the upload is rejected
And I see an error message “Avatar file size must be under 2MB. Your file is [X]MB.”
And the file is not uploaded

Scenario 14: Avatar Image Dimensions

Given I am uploading an avatar image
When the image is extremely large (e.g., 10000x10000 pixels)
Then the system accepts the file (within 2MB limit)
And automatically resizes/crops the image to appropriate dimensions (e.g., 400x400)
And displays a preview of the resized image before saving

Scenario 15: Remove Avatar Photo

Given I am on the profile edit page
And I currently have an avatar photo
When I click “Remove Photo” button
And I click “Save Changes”
Then my avatar is removed
And a default avatar placeholder is displayed
And I see confirmation “Profile updated successfully”

Scenario 16: Upload Progress Indicator

Given I am uploading a large avatar image (close to 2MB)
When the upload is in progress
Then I see a progress indicator showing upload percentage
And the “Save Changes” button is disabled during upload
And I see text “Uploading…” or similar

Scenario 17: Avatar Preview Before Save

Given I am on the profile edit page
When I select a new avatar image
Then I see an immediate preview of the new avatar
And the preview shows the cropped/resized version
And I can see how it will appear before saving

Scenario 18: Cancel Changes

Given I have made changes to my name, email, and avatar
And I have not clicked “Save Changes”
When I click “Cancel” or navigate away
Then I see a confirmation dialog “You have unsaved changes. Are you sure you want to leave?”
And if I confirm, all changes are discarded
And my profile remains unchanged

Scenario 19: Server Error Handling

Given I am saving profile changes
When the server returns a 500 error
Then the save operation fails gracefully
And I see error message “Unable to save changes. Please try again.”
And I am provided a “Retry” button
And my form data is preserved

Scenario 20: Network Error Handling

Given I am saving profile changes
When my network connection is interrupted
Then I see error message “Network error. Please check your connection and try again.”
And my form data is preserved
And I can retry when connection is restored

Scenario 21: Email Verification After Email Change

Given I have successfully changed my email address
When the save completes
Then I receive a verification email at my new address
And I see message “Verification email sent to [new email]. Please verify your new email address.”
And my email is marked as “unverified” until confirmed
And I remain logged in

Scenario 22: Special Characters in Name

Given I am on the profile edit page
When I enter a name with special characters (e.g., “O’Brien”, “José”, “Jean-Paul”)
Then the system accepts valid special characters (apostrophes, hyphens, accented characters)
And saves the name correctly with proper encoding
And displays the name correctly throughout the application

Scenario 23: XSS Protection in Name Fields

Given I am on the profile edit page
When I attempt to enter HTML or script tags in name fields (e.g., “”)
Then the input is sanitized server-side
And dangerous characters are escaped or stripped
And the name is saved safely

Scenario 24: Avatar Upload Virus Scan

Given I am uploading an avatar image
When the file is uploaded to the server
Then the file is scanned for malware/viruses
And if malicious content is detected, the upload is rejected
And I see error message “File upload failed security scan”

Scenario 25: Concurrent Edit Conflict

Given I am editing my profile in one browser tab
And I also edit my profile in another browser tab/device
When I save changes in the first tab (updating name)
And I save changes in the second tab (updating email) shortly after
Then the system uses last-write-wins strategy
And the second save overwrites the first
And I see a warning “Your profile was updated from another location. Your changes have been saved.”

Scenario 26: Session Timeout During Edit

Given I am on the profile edit page
And my session has expired (idle for 2 hours)
When I click “Save Changes”
Then I am redirected to the login page
And I see message “Your session has expired. Please log in to continue.”
And after logging in, I am returned to the profile edit page (form data preserved if possible)

Scenario 27: Profile Data Pre-populated

Given I navigate to the profile edit page
When the page loads
Then the form is pre-populated with my current profile information
And my current name is displayed in the name fields
And my current email is displayed in the email field
And my current avatar is displayed as a preview

Scenario 28: Loading State on Page Load

Given I am navigating to the profile edit page
When the page is loading profile data
Then I see a loading indicator
And form fields are disabled or show skeleton loaders
And the page does not display stale or empty data

Scenario 29: Loading State During Save

Given I have clicked “Save Changes”
When the save operation is in progress
Then I see a loading indicator on the “Save Changes” button
And the button is disabled to prevent double-submission
And I cannot edit form fields during save

Scenario 30: Whitespace Trimming

Given I am on the profile edit page
When I enter “ John “ (with leading and trailing spaces) in the first name field
And I click “Save Changes”
Then the system trims whitespace
And my name is saved as “John” (without extra spaces)
And the field displays “John” after save

Non-Functional Requirements

Performance

Profile page loads within 2 seconds
Form submission and save completes within 3 seconds
Avatar upload (up to 2MB) completes within 10 seconds
Avatar preview displays within 500ms of file selection
Image resizing/processing happens server-side without blocking UI

Security

Email addresses validated server-side using RFC 5322 standards
All inputs sanitized to prevent XSS attacks
Avatar files validated by file type and MIME type server-side
Uploaded images scanned for malware
File uploads use secure temporary storage before processing
CSRF protection on form submission
Email change triggers verification workflow
Passwords required to confirm sensitive changes (optional enhancement)

Accessibility

Full keyboard navigation support
All form fields have proper labels and ARIA attributes
Error messages announced by screen readers
Focus moved to first error field on validation failure
Color is not the only indicator of errors (text + icons)
Avatar upload accessible via keyboard
Form follows WCAG 2.1 AA standards

Browser Compatibility

Supports Chrome, Firefox, Safari, Edge (latest 2 versions)
Mobile browsers: iOS Safari, Chrome Android
Progressive enhancement: basic form works without JavaScript

Data Integrity

All changes are atomic (either all fields update or none)
Email uniqueness validated at database level
Avatar files stored with unique identifiers to prevent overwrites
Old avatar files deleted when new avatar uploaded
UTF-8 encoding for all text fields
Transaction rollback on save failure

Edge Cases to Consider

User changes email to their current email - Should succeed without validation error
Multiple rapid saves - Prevent double-submission with button disabling and debouncing
Very long email addresses (max 254 characters per RFC) - Validate max length
International characters in names (Chinese, Arabic, emoji) - Ensure proper UTF-8 support
Avatar file is corrupt or unreadable - Graceful error handling
User uploads GIF avatar - Support animated vs static handling
Browser autofill populates form - Detect changes properly
User closes browser during upload - Handle gracefully on next session
Email domain doesn’t exist (e.g., @fakeinvaliddomain.xyz) - Consider validation enhancement
Case sensitivity in email (john@example.com vs JOHN@example.com) - Normalize to lowercase
Name with only numbers (e.g., “123”) - Should be allowed or rejected based on business rules
Avatar with transparent background (PNG) - Preserve transparency or add background
User updates to same data as current - Should succeed with no backend changes
Profile viewed by other users while editing - They see old data until refresh

Definition of Done

User can update first name, last name, and email
User can upload and update avatar photo (JPG, PNG, GIF, WEBP)
User can remove avatar photo
All required field validations working (name, email)
Email format validation working
Email uniqueness validation working
Name length validations (min 2, max 50 characters)
Avatar file type validation (images only)
Avatar file size validation (max 2MB)
Avatar auto-resize/crop to standard dimensions
Avatar preview shown before save
Avatar upload progress indicator
Form pre-populated with current profile data
Success confirmation message displayed
Unsaved changes warning on navigation
Server error handling with retry option
Network error handling
Loading states during page load and save
Email verification flow triggered on email change
Input sanitization and XSS protection
Avatar file malware scanning
Whitespace trimming on text fields
Full keyboard navigation support
Screen reader compatibility tested
Unit tests for all validation logic
Integration tests for save workflow
Accessibility audit passed (WCAG 2.1 AA)
Cross-browser testing completed
Mobile responsive design verified

Technical Notes

Suggested Implementation:

Backend

API Endpoint: PATCH /api/user/profile

Request Body:

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "avatar": "base64_encoded_image_or_file_upload"
}

Validation: Server-side validation for all fields, email uniqueness check, file type/size validation
Image Processing: Use image processing library (ImageMagick, Pillow) to resize/crop to 400x400
Storage: Store avatars in cloud storage (S3, Cloudinary) with CDN for fast delivery
Email Verification: Send verification email when email changes, mark as unverified until confirmed

Frontend

Form Library: Use controlled components with validation state
File Upload: Use FormData or file upload library with progress tracking
Image Preview: Use FileReader API for client-side preview
Validation: Client-side validation for immediate feedback, server-side for security
State Management: Track form dirty state for unsaved changes warning
Error Handling: Display inline errors and global error messages

Database Schema

users table with columns: first_name, last_name, email (unique), avatar_url, email_verified
Index on email for fast uniqueness checks
Store avatar URLs, not binary data

User Profile Edit Feature

Input

Output