pantry/docs/PWA_TESTING.md

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)

// 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:

• PWA manifest loads correctly
• Install prompt works
• Service worker registers and activates
• App works offline
• Cached content loads
• Offline banner shows/hides correctly
• Online status detected accurately
• Install instructions provided for unsupported browsers
• Storage usage displayed
• 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).