Todo/PWA_TESTING_GUIDE.md

PWA Testing Guide - Ultimate Lists App

Overview

This guide helps you test the Progressive Web App (PWA) functionality of the Ultimate Lists app, with a focus on iOS Safari installation.

Prerequisites

Generate PNG Icons First

Before testing, you need to generate PNG versions of the icons:

Option 1: Browser-based Generator (Easiest)

1. Open scripts/generate-png-icons.html in your browser
2. Click "Download All Icons"
3. Save each PNG file to the public/ directory

Option 2: Using Sharp

npm install --save-dev sharp
node scripts/convert-with-sharp.js

Option 3: Using ImageMagick

brew install imagemagick  # macOS
convert public/icon-192.svg -resize 192x192 public/icon-192.png
convert public/icon-512.svg -resize 512x512 public/icon-512.png
convert public/apple-touch-icon.svg -resize 180x180 public/apple-touch-icon.png
convert public/favicon.svg -resize 32x32 public/favicon-32.png

Testing on iOS Safari

Step 1: Deploy or Use Local Network

The PWA must be served over HTTPS or localhost. For iOS testing:

Option A: Deploy to Vercel/Netlify

npm run build
# Deploy to your hosting provider

Option B: Local Network Testing

1. Find your local IP: ifconfig | grep "inet " | grep -v 127.0.0.1
2. Run dev server: npm run dev
3. Access from iPhone: http://YOUR_IP:3000
4. Note: Service workers require HTTPS in production

Step 2: Test Installation on iPhone/iPad

1. Open Safari on your iOS device

   • Navigate to your app URL
   • Ensure the app loads correctly

2. Add to Home Screen

   • Tap the Share button (square with arrow)
   • Scroll down and tap "Add to Home Screen"
   • Verify the icon preview looks correct
   • Verify the name is "Ultimate Lists"
   • Tap "Add"

3. Verify Home Screen Icon

   • Check that the icon appears on your home screen
   • Verify the icon is clear and not blurry
   • Verify the icon has the correct colors (blue background, white checkmark)

4. Launch the App

   • Tap the icon on your home screen
   • The app should open in standalone mode (no Safari UI)
   • Verify the status bar style (should be translucent)
   • Verify the app fills the screen properly

Step 3: Test PWA Features

Standalone Mode

• ✓ No Safari address bar visible
• ✓ No Safari toolbar at bottom
• ✓ App uses full screen (respecting safe areas)
• ✓ Status bar is styled correctly

Offline Functionality

• ✓ Enable Airplane Mode
• ✓ Open the app (should still load)
• ✓ Navigate between pages (should work)
• ✓ Create/edit tasks (should queue for sync)
• ✓ Disable Airplane Mode
• ✓ Verify changes sync to server

App Behavior

• ✓ App remembers state between launches
• ✓ Smooth navigation without page reloads
• ✓ Touch interactions work properly
• ✓ Forms and inputs work correctly

Testing on Android Chrome

Step 1: Access the App

1. Open Chrome on Android device
2. Navigate to your app URL
3. Ensure the app loads correctly

Step 2: Install the App

1. Look for the "Add to Home screen" prompt (may appear automatically)
2. Or tap the menu (⋮) → "Add to Home screen" or "Install app"
3. Verify the icon and name
4. Tap "Add" or "Install"

Step 3: Test PWA Features

• ✓ App opens in standalone mode
• ✓ Icon appears in app drawer
• ✓ Offline functionality works
• ✓ Can uninstall like a native app

Testing on Desktop

Chrome/Edge

1. Open the app in Chrome or Edge
2. Look for the install icon (⊕) in the address bar
3. Click to install
4. App opens in a standalone window
5. Test offline mode using DevTools (Network → Offline)

Safari (macOS)

1. Open the app in Safari
2. File → Add to Dock
3. App appears in Dock
4. Opens in standalone window

Verification Checklist

Icons

• Favicon appears in browser tab
• Home screen icon is clear and properly sized
• Icon has correct colors and design
• Icon is not blurry or pixelated
• Icon works on both light and dark backgrounds

Manifest

• App name displays correctly
• Theme color matches design (#3B82F6)
• Background color is white
• Display mode is "standalone"
• Orientation is set correctly

Meta Tags

• Apple touch icon loads correctly
• Status bar style is appropriate
• Viewport settings work on mobile
• Theme color appears in browser UI

Service Worker

• Service worker registers successfully
• Static assets are cached
• App works offline
• Updates are handled properly

User Experience

• App loads quickly
• Navigation is smooth
• Touch targets are appropriately sized
• Forms work correctly
• Data persists between sessions

Troubleshooting

Icon Not Showing on iOS

Problem: Default icon or no icon appears

Solutions:

1. Ensure PNG files exist (iOS doesn't support SVG for touch icons)
2. Check file paths in app/layout.tsx
3. Verify files are in public/ directory
4. Clear Safari cache: Settings → Safari → Clear History and Website Data
5. Remove and re-add to home screen

App Not Installing

Problem: No "Add to Home Screen" option

Solutions:

1. Ensure manifest.json is accessible at /manifest.json
2. Check browser console for errors
3. Verify HTTPS (required for service workers)
4. Check manifest.json syntax is valid
5. Ensure all required manifest fields are present

Service Worker Not Working

Problem: App doesn't work offline

Solutions:

1. Check browser console for service worker errors
2. Verify service worker file is at /sw.js
3. Ensure HTTPS (service workers require secure context)
4. Check service worker registration in DevTools
5. Try unregistering and re-registering service worker

Icon Blurry or Wrong Size

Problem: Icon appears pixelated or wrong dimensions

Solutions:

1. Regenerate PNG icons at correct sizes
2. Ensure PNG files are not compressed too much
3. Verify icon dimensions match manifest.json
4. Use higher resolution source images
5. Test on actual device (not just simulator)

App Not Opening in Standalone Mode

Problem: Safari UI still visible when opening from home screen

Solutions:

1. Check apple-mobile-web-app-capable meta tag is set to "yes"
2. Verify manifest.json has "display": "standalone"
3. Remove and re-add to home screen
4. Check for JavaScript errors preventing proper initialization

Testing Tools

Browser DevTools

• Chrome DevTools: Application → Manifest / Service Workers
• Safari DevTools: Develop → Show Web Inspector → Storage
• Lighthouse: Run PWA audit for comprehensive check

Online Tools

• PWA Builder - Test and validate PWA
• Manifest Validator - Validate manifest.json
• Web.dev PWA Checklist - Comprehensive checklist

Command Line

# Check if files exist
ls -la public/*.png public/*.svg public/manifest.json

# Validate manifest.json
cat public/manifest.json | jq .

# Check service worker
curl http://localhost:3000/sw.js

Best Practices

Icon Design

• Use simple, recognizable shapes
• Ensure good contrast
• Test on both light and dark backgrounds
• Keep important content in the center 80%
• Use consistent branding colors

Testing Workflow

1. Test on actual devices (not just simulators)
2. Test on multiple iOS versions
3. Test on different Android devices
4. Test offline functionality thoroughly
5. Test on slow network connections
6. Test with different screen sizes

Deployment

1. Always use HTTPS in production
2. Set appropriate cache headers
3. Version your service worker
4. Monitor service worker updates
5. Test after each deployment

Success Criteria

Your PWA is ready when:

• ✓ Installs successfully on iOS Safari
• ✓ Installs successfully on Android Chrome
• ✓ Icon appears correctly on all platforms
• ✓ Opens in standalone mode (no browser UI)
• ✓ Works offline for core functionality
• ✓ Passes Lighthouse PWA audit
• ✓ Provides native-like experience
• ✓ Handles updates gracefully

Additional Resources

• Apple PWA Documentation
• Google PWA Documentation
• MDN Web App Manifest
• Service Worker API