# PWA Offline Functionality Testing Guide

## Overview

This guide covers testing the Progressive Web App (PWA) features and offline functionality of Pantry.

## Prerequisites

- Development server running (`npm run dev` in the `app/` directory)
- Modern browser (Chrome, Edge, Safari, or Firefox)
- Browser DevTools access

## Test Categories

### 1. PWA Manifest & Installation

#### Test 1.1: Manifest Validation
1. Open browser DevTools → Application tab
2. Navigate to "Manifest" section
3. **Expected Results:**
   - ✅ Manifest loads without errors
   - ✅ App name: "Pantry - Smart Inventory Manager"
   - ✅ Short name: "Pantry"
   - ✅ Theme color: #10b981 (emerald)
   - ✅ All icons (192x192, 512x512, maskable) present
   - ✅ Display mode: standalone
   - ✅ No manifest warnings

#### Test 1.2: Install Prompt
1. Wait 3 seconds after page load
2. **Expected Results:**
   - ✅ Install prompt card appears (bottom-right on desktop, bottom on mobile)
   - ✅ Shows app icon and "Install Pantry" title
   - ✅ "Install" button is clickable
   - ✅ "Not now" dismisses the prompt
   - ✅ Close (X) button dismisses the prompt

#### Test 1.3: Manual Installation from Settings
1. Navigate to Settings → App tab
2. **Expected Results:**
   - ✅ Shows "Install App" button
   - ✅ Clicking installs the app
   - ✅ After install, shows "App is installed" status
   - ✅ Storage usage displayed with progress bar

#### Test 1.4: Platform-Specific Instructions
1. View Settings → App tab on device without beforeinstallprompt support
2. **Expected Results:**
   - ✅ Shows iOS installation instructions (if on iOS)
   - ✅ Shows Android installation instructions (if on Android)
   - ✅ Instructions are clear and accurate

### 2. Service Worker

#### Test 2.1: Service Worker Registration
1. Open DevTools → Application → Service Workers
2. **Expected Results:**
   - ✅ Service worker registered
   - ✅ Status: "activated and running"
   - ✅ No registration errors
   - ✅ Update on reload enabled

#### Test 2.2: Cache Storage
1. Open DevTools → Application → Cache Storage
2. Navigate through the app (Home, Scan, Settings)
3. **Expected Results:**
   - ✅ Multiple cache buckets created:
     - workbox-precache (app shell)
     - supabase-rest-api
     - supabase-storage
     - product-images (if products viewed)
     - google-fonts-stylesheets
     - google-fonts-webfonts
   - ✅ App shell assets cached (JS, CSS, HTML)
   - ✅ Icons and images cached

#### Test 2.3: Update Behavior
1. Make a code change
2. Rebuild the app
3. Refresh the page
4. **Expected Results:**
   - ✅ Service worker updates in background
   - ✅ New version activates automatically (skipWaiting)
   - ✅ No manual refresh required for future visits

### 3. Offline Functionality

#### Test 3.1: Complete Offline Mode
1. Load the app while online
2. Navigate to all pages (Home, Scan, Settings)
3. Open DevTools → Network tab
4. Enable "Offline" mode
5. Try navigating the app
6. **Expected Results:**
   - ✅ App continues to function
   - ✅ Previously visited pages load instantly
   - ✅ Offline banner appears at top
   - ✅ Banner shows "You're currently offline" message
   - ✅ Navigation between cached pages works
   - ✅ No white screens or errors

#### Test 3.2: Offline Fallback Page
1. Go offline (DevTools Network → Offline)
2. Try navigating to a non-cached page (e.g., type random URL)
3. **Expected Results:**
   - ✅ Redirects to /offline page
   - ✅ Shows WiFi icon and helpful message
   - ✅ Lists what you can do offline
   - ✅ "Try Again" button present
   - ✅ Auto-redirects when back online

#### Test 3.3: Online Status Detection
1. Start online, go offline, come back online
2. **Expected Results:**
   - ✅ Offline banner appears when offline
   - ✅ "Back online!" banner shows when reconnected (green)
   - ✅ Banner auto-hides after 3 seconds
   - ✅ No false positives

#### Test 3.4: API Request Caching (Supabase)
1. While online, view some inventory items (once implemented)
2. Go offline
3. Navigate to the items page
4. **Expected Results:**
   - ✅ Previously loaded items still visible
   - ✅ Network requests fail gracefully
   - ✅ Cached data is served
   - ✅ No crashes or white screens

#### Test 3.5: Image Caching (Product Images)
1. While online, view products with images
2. Go offline
3. View the same products again
4. **Expected Results:**
   - ✅ Product images load from cache
   - ✅ No broken image placeholders
   - ✅ Images from Open Food Facts cached

### 4. Background Sync (Future Enhancement)

**Note:** Background sync not yet implemented. This section is reserved for future testing.

### 5. Cross-Platform Testing

#### Test 5.1: Desktop Browsers
Test on:
- [ ] Chrome/Edge (Windows/Mac/Linux)
- [ ] Firefox (Windows/Mac/Linux)
- [ ] Safari (Mac only)

#### Test 5.2: Mobile Browsers
Test on:
- [ ] Chrome (Android)
- [ ] Safari (iOS)
- [ ] Firefox (Android)
- [ ] Samsung Internet (Android)

#### Test 5.3: Installed App vs Browser
Compare behavior when:
- [ ] Running in browser tab
- [ ] Running as installed PWA (standalone mode)

**Expected Results:**
- ✅ Identical functionality
- ✅ Installed app shows in app switcher
- ✅ Installed app has no browser chrome
- ✅ Installed app survives system restart

### 6. Performance Testing

#### Test 6.1: First Load Performance
1. Clear all caches
2. Load the app (online)
3. Check DevTools → Lighthouse
4. Run PWA audit
5. **Expected Results:**
   - ✅ PWA score: 90+ / 100
   - ✅ Performance score: 80+ / 100
   - ✅ "Installable" badge present
   - ✅ No PWA warnings

#### Test 6.2: Repeat Visit Performance
1. Visit the app
2. Navigate around
3. Close tab
4. Reopen the app
5. **Expected Results:**
   - ✅ Instant load from cache
   - ✅ No flash of white screen
   - ✅ Content visible immediately

### 7. Storage Management

#### Test 7.1: Storage Quota
1. Open Settings → App tab
2. **Expected Results:**
   - ✅ Storage usage displayed
   - ✅ Storage quota displayed
   - ✅ Usage percentage shown visually
   - ✅ Numbers update as cache grows

#### Test 7.2: Cache Eviction
1. Fill cache with many images/data
2. Exceed storage quota
3. **Expected Results:**
   - ✅ Oldest cache entries evicted automatically
   - ✅ No app crashes
   - ✅ App continues to function

## Automated Testing (Future)

### Playwright E2E Tests (Planned)

```typescript
// Example test structure
test('PWA installs correctly', async ({ page }) => {
  // Test installation flow
})

test('App works offline', async ({ page, context }) => {
  // Load app, go offline, verify functionality
})
```

## Known Issues & Limitations

1. **iOS Safari:**
   - No beforeinstallprompt event (use manual Add to Home Screen)
   - Service worker has storage limits
   - Background sync not supported

2. **Firefox:**
   - Install prompt may not show (desktop only)
   - Use "Add to Home Screen" on mobile

3. **Development Mode:**
   - Service worker may behave differently
   - Always test in production build

## Troubleshooting

### Service Worker Not Updating
- Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
- DevTools → Application → Service Workers → Unregister
- Clear cache and reload

### Install Prompt Not Showing
- Check if already installed
- Check localStorage for `pwa-install-dismissed`
- Wait 7 days or clear localStorage
- Ensure criteria met (HTTPS, manifest, service worker)

### Offline Mode Not Working
- Verify service worker is active
- Check cache storage has content
- Ensure you visited pages while online first

## Success Criteria

All tests must pass before marking issue #36 complete:

- [x] PWA manifest loads correctly
- [x] Install prompt works
- [x] Service worker registers and activates
- [x] App works offline
- [x] Cached content loads
- [x] Offline banner shows/hides correctly
- [x] Online status detected accurately
- [x] Install instructions provided for unsupported browsers
- [x] Storage usage displayed
- [x] No console errors during offline usage

## Sign-off

**Tested by:** [Name]  
**Date:** [Date]  
**Browsers tested:** [List]  
**Issues found:** [List or "None"]  
**Status:** ✅ Pass / ❌ Fail

---

**Next Steps:** After testing passes, proceed to Week 6 (Deployment & Testing).