# Manual Testing Plan - UI/UX Improvements

**Date**: 2026-01-20
**Testing Focus**: Onboarding Tour, Mobile Navigation, Dark Mode, Admin Routes
**Tester**: [Your Name]
**Environment**: Dev Container (`http://localhost:5173`)

---

## Pre-Testing Setup

### 1. Start Dev Server

```bash
podman exec -it flyer-crawler-dev npm run dev:container
```

**Expected**: Server starts at `http://localhost:5173`

### 2. Open Browser

- Primary browser: Chrome/Edge (DevTools required)
- Secondary: Firefox, Safari (for cross-browser testing)
- Enable DevTools: F12 or Ctrl+Shift+I

### 3. Prepare Test Environment

- Clear browser cache
- Clear all cookies for localhost
- Open DevTools → Application → Local Storage
- Note any existing keys

---

## Test Suite 1: Onboarding Tour

### Test 1.1: First-Time User Experience ⭐ CRITICAL

**Objective**: Verify tour starts automatically for new users

**Steps**:

1. Open DevTools → Application → Local Storage → `http://localhost:5173`
2. Delete key: `flyer_crawler_onboarding_completed` (if exists)
3. Refresh page (F5)
4. Observe page load

**Expected Results**:

- ✅ Tour modal appears automatically within 2 seconds
- ✅ First tooltip points to "Flyer Uploader" section
- ✅ Tooltip shows "Step 1 of 6"
- ✅ Tooltip contains text: "Upload grocery flyers here..."
- ✅ "Skip" button visible in top-right
- ✅ "Next" button visible at bottom

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 1.2: Tour Navigation

**Objective**: Verify all 6 tour steps are accessible and display correctly

**Steps**:

1. Ensure tour is active (from Test 1.1)
2. Click "Next" button
3. Repeat for all 6 steps, noting each tooltip

**Expected Results**:

| Step | Target Element       | Tooltip Text Snippet                   | Pass/Fail |
| ---- | -------------------- | -------------------------------------- | --------- |
| 1    | Flyer Uploader       | "Upload grocery flyers here..."        | [ ]       |
| 2    | Extracted Data Table | "View AI-extracted items..."           | [ ]       |
| 3    | Watch Button         | "Click + Watch to track items..."      | [ ]       |
| 4    | Watched Items List   | "Your watchlist appears here..."       | [ ]       |
| 5    | Price Chart          | "See active deals on watched items..." | [ ]       |
| 6    | Shopping List        | "Create shopping lists..."             | [ ]       |

**Additional Checks**:

- ✅ Progress indicator updates (1/6 → 2/6 → ... → 6/6)
- ✅ Each tooltip highlights correct element
- ✅ "Previous" button works (after step 2)
- ✅ No JavaScript errors in console

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 1.3: Tour Completion

**Objective**: Verify tour completion saves to localStorage

**Steps**:

1. Complete all 6 steps (click "Next" 5 times)
2. On step 6, click "Done" or "Finish"
3. Open DevTools → Application → Local Storage
4. Check for key: `flyer_crawler_onboarding_completed`

**Expected Results**:

- ✅ Tour closes after final step
- ✅ localStorage key `flyer_crawler_onboarding_completed` = `"true"`
- ✅ No tour modal visible
- ✅ Application fully functional

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 1.4: Tour Skip

**Objective**: Verify "Skip" button works and saves preference

**Steps**:

1. Delete localStorage key (reset)
2. Refresh page to start tour
3. Click "Skip" button on step 1
4. Check localStorage

**Expected Results**:

- ✅ Tour closes immediately
- ✅ localStorage key saved: `flyer_crawler_onboarding_completed` = `"true"`
- ✅ Application remains functional
- ✅ No errors in console

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 1.5: Tour Does Not Repeat

**Objective**: Verify tour doesn't show for returning users

**Steps**:

1. Ensure localStorage key exists from previous test
2. Refresh page multiple times
3. Navigate to different routes (/deals, /lists)
4. Return to home page

**Expected Results**:

- ✅ Tour modal never appears
- ✅ No tour-related elements visible
- ✅ Application loads normally

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Test Suite 2: Mobile Navigation

### Test 2.1: Responsive Breakpoints - Mobile (375px)

**Objective**: Verify mobile layout at iPhone SE width

**Setup**:

1. Open DevTools → Toggle Device Toolbar (Ctrl+Shift+M)
2. Select "iPhone SE" or set custom width to 375px
3. Refresh page

**Expected Results**:

| Element                   | Expected Behavior             | Pass/Fail |
| ------------------------- | ----------------------------- | --------- |
| Bottom Tab Bar            | ✅ Visible at bottom          | [ ]       |
| Left Sidebar (Flyer List) | ✅ Hidden                     | [ ]       |
| Right Sidebar (Widgets)   | ✅ Hidden                     | [ ]       |
| Main Content              | ✅ Full width, single column  | [ ]       |
| Bottom Padding            | ✅ 64px padding below content | [ ]       |

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.2: Responsive Breakpoints - Tablet (768px)

**Objective**: Verify mobile layout at iPad width

**Setup**:

1. Set device width to 768px (iPad)
2. Refresh page

**Expected Results**:

- ✅ Bottom tab bar still visible
- ✅ Sidebars still hidden
- ✅ Content uses full width
- ✅ Tab bar does NOT overlap content

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.3: Responsive Breakpoints - Desktop (1024px+)

**Objective**: Verify desktop layout unchanged

**Setup**:

1. Set device width to 1440px (desktop)
2. Refresh page

**Expected Results**:

- ✅ Bottom tab bar HIDDEN
- ✅ Left sidebar (flyer list) VISIBLE
- ✅ Right sidebar (widgets) VISIBLE
- ✅ 3-column grid layout intact
- ✅ No layout changes from before

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.4: Tab Navigation - Home

**Objective**: Verify Home tab navigation

**Setup**: Set width to 375px (mobile)

**Steps**:

1. Tap "Home" tab in bottom bar
2. Observe page content

**Expected Results**:

- ✅ Tab icon highlighted in teal (#14b8a6)
- ✅ Tab label highlighted
- ✅ URL changes to `/`
- ✅ HomePage component renders
- ✅ Shows flyer view and upload section

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.5: Tab Navigation - Deals

**Objective**: Verify Deals tab navigation

**Steps**:

1. Tap "Deals" tab (TagIcon)
2. Observe page content

**Expected Results**:

- ✅ Tab icon highlighted in teal
- ✅ URL changes to `/deals`
- ✅ DealsPage component renders
- ✅ Shows WatchedItemsList component
- ✅ Shows PriceChart component
- ✅ Shows PriceHistoryChart component
- ✅ Previous tab (Home) is unhighlighted

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.6: Tab Navigation - Lists

**Objective**: Verify Lists tab navigation

**Steps**:

1. Tap "Lists" tab (ListBulletIcon)
2. Observe page content

**Expected Results**:

- ✅ Tab icon highlighted in teal
- ✅ URL changes to `/lists`
- ✅ ShoppingListsPage component renders
- ✅ Shows ShoppingList component
- ✅ Can create/view shopping lists

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.7: Tab Navigation - Profile

**Objective**: Verify Profile tab navigation

**Steps**:

1. Tap "Profile" tab (UserIcon)
2. Observe page content

**Expected Results**:

- ✅ Tab icon highlighted in teal
- ✅ URL changes to `/profile`
- ✅ UserProfilePage component renders
- ✅ Shows user profile information
- ✅ Shows achievements (if logged in)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.8: Touch Target Size (Accessibility)

**Objective**: Verify touch targets meet 44x44px minimum (WCAG 2.5.5)

**Steps**:

1. Stay in mobile view (375px)
2. Open DevTools → Elements
3. Inspect each tab in bottom bar
4. Check computed dimensions

**Expected Results**:

- ✅ Each tab button: min-height: 44px
- ✅ Each tab button: min-width: 44px
- ✅ Icon is centered
- ✅ Label is readable below icon
- ✅ Adequate spacing between tabs

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 2.9: Tab Bar Visibility on Admin Routes

**Objective**: Verify tab bar hidden on admin pages

**Steps**:

1. Navigate to `/admin` (may need to log in as admin)
2. Check bottom of page
3. Navigate to `/admin/stats`
4. Navigate to `/admin/corrections`

**Expected Results**:

- ✅ Tab bar NOT visible on `/admin`
- ✅ Tab bar NOT visible on any `/admin/*` routes
- ✅ Admin pages function normally
- ✅ Footer visible as normal

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Test Suite 3: Dark Mode

### Test 3.1: Dark Mode Toggle

**Objective**: Verify dark mode toggle works for new components

**Steps**:

1. Ensure you're in light mode (check header toggle)
2. Click dark mode toggle in header
3. Observe all new components

**Expected Results - DealsPage**:

- ✅ Background changes to dark gray (#1f2937 or similar)
- ✅ Text changes to light colors
- ✅ WatchedItemsList: dark background, light text
- ✅ PriceChart: dark theme colors
- ✅ No white boxes remaining

**Expected Results - ShoppingListsPage**:

- ✅ Background changes to dark
- ✅ ShoppingList cards: dark background
- ✅ Input fields: dark background with light text
- ✅ Buttons maintain brand colors

**Expected Results - FlyersPage**:

- ✅ Background dark
- ✅ Flyer cards: dark theme
- ✅ FlyerUploader: dark background

**Expected Results - MobileTabBar**:

- ✅ Tab bar background: dark (#111827 or similar)
- ✅ Border top: dark border color
- ✅ Inactive tab icons: gray
- ✅ Active tab icon: teal (#14b8a6)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 3.2: Dark Mode Persistence

**Objective**: Verify dark mode preference persists across navigation

**Steps**:

1. Enable dark mode
2. Navigate between tabs: Home → Deals → Lists → Profile
3. Refresh page
4. Check mode

**Expected Results**:

- ✅ Dark mode stays enabled across all routes
- ✅ Dark mode persists after page refresh
- ✅ All pages render in dark mode consistently

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 3.3: Button Component in Dark Mode

**Objective**: Verify Button component variants in dark mode

**Setup**: Enable dark mode

**Check each variant**:

| Variant   | Expected Dark Mode Colors      | Pass/Fail |
| --------- | ------------------------------ | --------- |
| Primary   | bg-brand-secondary, text-white | [ ]       |
| Secondary | bg-gray-700, text-gray-200     | [ ]       |
| Danger    | bg-red-900/50, text-red-300    | [ ]       |
| Ghost     | hover: bg-gray-700/50          | [ ]       |

**Locations to check**:

- FlyerUploader: "Upload Another Flyer" (primary)
- ShoppingList: "New List" (secondary)
- ShoppingList: "Delete List" (danger)
- FlyerUploader: "Stop Watching" (ghost)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 3.4: Onboarding Tour in Dark Mode

**Objective**: Verify tour tooltips work in dark mode

**Steps**:

1. Enable dark mode
2. Delete localStorage key to reset tour
3. Refresh to start tour
4. Navigate through all 6 steps

**Expected Results**:

- ✅ Tooltip background visible (not too dark)
- ✅ Tooltip text readable (good contrast)
- ✅ Progress indicator visible
- ✅ Buttons clearly visible
- ✅ Highlighted elements stand out
- ✅ No visual glitches

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Test Suite 4: Admin Routes

### Test 4.1: Admin Access (Requires Admin User)

**Objective**: Verify admin routes still function correctly

**Prerequisites**: Need admin account credentials

**Steps**:

1. Log in as admin user
2. Click admin shield icon in header
3. Should navigate to `/admin`

**Expected Results**:

- ✅ Admin dashboard loads
- ✅ 4 links visible: Corrections, Stats, Flyer Review, Stores
- ✅ SystemCheck component shows health checks
- ✅ Layout looks correct (no mobile tab bar)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 4.2: Admin Subpages

**Objective**: Verify all admin subpages load

**Steps**:

1. From admin dashboard, click each link:
   - Corrections → `/admin/corrections`
   - Stats → `/admin/stats`
   - Flyer Review → `/admin/flyer-review`
   - Stores → `/admin/stores`

**Expected Results**:

- ✅ Each page loads without errors
- ✅ No mobile tab bar visible
- ✅ Desktop layout maintained
- ✅ All admin functionality works
- ✅ Can navigate back to `/admin`

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 4.3: Admin in Mobile View

**Objective**: Verify admin pages work in mobile view

**Steps**:

1. Set device width to 375px
2. Navigate to `/admin`
3. Check layout

**Expected Results**:

- ✅ Admin page renders correctly
- ✅ No mobile tab bar visible
- ✅ Content is readable (may scroll)
- ✅ All buttons/links clickable
- ✅ No layout breaking

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Test Suite 5: Integration Tests

### Test 5.1: Cross-Feature Navigation

**Objective**: Verify navigation between new and old features

**Scenario**: User journey through app

**Steps**:

1. Start on Home page (mobile view)
2. Upload a flyer (if possible)
3. Click "Deals" tab → should see deals page
4. Add item to watchlist (from deals page)
5. Click "Lists" tab → create shopping list
6. Add item to shopping list
7. Click "Profile" tab → view profile
8. Click "Home" tab → return to home

**Expected Results**:

- ✅ All navigation works smoothly
- ✅ No data loss between pages
- ✅ Active tab always correct
- ✅ Back button works (browser history)
- ✅ No JavaScript errors

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 5.2: Button Component Integration

**Objective**: Verify Button component works in all contexts

**Steps**:

1. Navigate to page with buttons (FlyerUploader, ShoppingList)
2. Click each button variant
3. Test loading states
4. Test disabled states

**Expected Results**:

- ✅ All buttons clickable
- ✅ Loading spinner appears when appropriate
- ✅ Disabled buttons prevent clicks
- ✅ Icons render correctly
- ✅ Hover states work

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 5.3: Brand Colors Visual Check

**Objective**: Verify brand colors display correctly throughout app

**Check these elements**:

- ✅ Active tab in tab bar: teal (#14b8a6)
- ✅ Primary buttons: teal background
- ✅ Links on hover: teal color
- ✅ Focus rings: teal color
- ✅ Watched item indicators: green (not brand color)
- ✅ All teal shades consistent

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Test Suite 6: Error Scenarios

### Test 6.1: Missing Data

**Objective**: Verify pages handle empty states gracefully

**Steps**:

1. Navigate to /deals (without watched items)
2. Navigate to /lists (without shopping lists)
3. Navigate to /flyers (without uploaded flyers)

**Expected Results**:

- ✅ Empty state messages shown
- ✅ No JavaScript errors
- ✅ Clear calls to action displayed
- ✅ Page structure intact

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 6.2: Network Errors (Simulated)

**Objective**: Verify app handles network failures

**Steps**:

1. Open DevTools → Network tab
2. Set throttling to "Offline"
3. Try to navigate between tabs
4. Try to load data

**Expected Results**:

- ✅ Error messages displayed
- ✅ App doesn't crash
- ✅ Can retry actions
- ✅ Navigation still works (cached)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Test Suite 7: Performance

### Test 7.1: Page Load Speed

**Objective**: Verify new features don't slow down app

**Steps**:

1. Open DevTools → Network tab
2. Disable cache
3. Refresh page
4. Note "Load" time in Network tab

**Expected Results**:

- ✅ Initial load: < 3 seconds
- ✅ Route changes: < 500ms
- ✅ No long-running scripts
- ✅ No memory leaks (use Performance Monitor)

**Pass/Fail**: [ ]

**Measurements**:

- Initial load: **\_\_\_** ms
- Home → Deals: **\_\_\_** ms
- Deals → Lists: **\_\_\_** ms

---

### Test 7.2: Bundle Size

**Objective**: Verify bundle size increase is acceptable

**Steps**:

1. Run: `npm run build`
2. Check `dist/` folder size
3. Compare to previous build (if available)

**Expected Results**:

- ✅ Bundle size increase: < 50KB
- ✅ No duplicate libraries loaded
- ✅ Tree-shaking working

**Pass/Fail**: [ ]

**Measurements**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Cross-Browser Testing

### Test 8.1: Chrome/Edge

**Browser Version**: **\*\***\_\_\_**\*\***

**Tests to Run**:

- [ ] All Test Suite 1 (Onboarding)
- [ ] All Test Suite 2 (Mobile Nav)
- [ ] Test 3.1-3.4 (Dark Mode)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 8.2: Firefox

**Browser Version**: **\*\***\_\_\_**\*\***

**Tests to Run**:

- [ ] Test 1.1, 1.2 (Onboarding basics)
- [ ] Test 2.4-2.7 (Tab navigation)
- [ ] Test 3.1 (Dark mode)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

### Test 8.3: Safari (macOS/iOS)

**Browser Version**: **\*\***\_\_\_**\*\***

**Tests to Run**:

- [ ] Test 1.1 (Tour starts)
- [ ] Test 2.1 (Mobile layout)
- [ ] Test 3.1 (Dark mode)

**Pass/Fail**: [ ]

**Notes**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***

---

## Test Summary

### Overall Results

| Test Suite           | Pass | Fail | Skipped | Total  |
| -------------------- | ---- | ---- | ------- | ------ |
| 1. Onboarding Tour   |      |      |         | 5      |
| 2. Mobile Navigation |      |      |         | 9      |
| 3. Dark Mode         |      |      |         | 4      |
| 4. Admin Routes      |      |      |         | 3      |
| 5. Integration       |      |      |         | 3      |
| 6. Error Scenarios   |      |      |         | 2      |
| 7. Performance       |      |      |         | 2      |
| 8. Cross-Browser     |      |      |         | 3      |
| **TOTAL**            |      |      |         | **31** |

### Critical Issues Found

1. ***
2. ***
3. ***

### Minor Issues Found

1. ***
2. ***
3. ***

### Recommendations

1. ***
2. ***
3. ***

---

## Sign-Off

**Tester Name**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***
**Date Completed**: \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***
**Overall Status**: [ ] PASS [ ] PASS WITH ISSUES [ ] FAIL

**Ready for Production**: [ ] YES [ ] NO [ ] WITH FIXES

**Additional Comments**:

---

---

---