soundwave/docs/PWA_TESTING_GUIDE.md

🎵 SoundWave PWA - Setup & Testing Guide

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.10+
• Docker & Docker Compose (optional)

Installation

1. Clone and Install

   cd soundwave/frontend
   npm install
   

2. Generate PWA Icons (Optional for testing)

   # If you have ImageMagick installed:
   ../scripts/generate-pwa-icons.sh
   
   # Otherwise, use online tools:
   # - https://www.pwabuilder.com/imageGenerator
   # - https://realfavicongenerator.net/
   

3. Start Development Server

   npm run dev
   

   Visit: http://localhost:3000

4. Build for Production

   npm run build
   npm run preview
   

   Visit: http://localhost:4173

📱 Testing PWA Features

1. Test Service Worker

1. Open Chrome DevTools (F12)
2. Go to Application tab
3. Click Service Workers in sidebar
4. Verify:
   • ✅ Service worker is registered
   • ✅ Status shows "activated and is running"
   • ✅ Source: /service-worker.js

2. Test Manifest

1. In DevTools > Application tab
2. Click Manifest in sidebar
3. Verify:
   • ✅ Name: "SoundWave"
   • ✅ Short name: "SoundWave"
   • ✅ Start URL: "/"
   • ✅ Display: "standalone"
   • ✅ Icons: 8 icons (72px to 512px)
   • ✅ Theme color: "#1976d2"

3. Test Offline Mode

1. In DevTools > Application > Service Workers
2. Check Offline checkbox
3. Reload the page (Ctrl+R)
4. Verify:
   • ✅ Page loads successfully
   • ✅ Cached content is displayed
   • ✅ Offline indicator shows in UI
   • ✅ "You're offline" alert appears

4. Test Cache Storage

1. In DevTools > Application > Cache Storage
2. Verify caches:
   • ✅ soundwave-v1 (static assets)
   • ✅ soundwave-api-v1 (API responses)
   • ✅ soundwave-audio-v1 (audio files)
   • ✅ soundwave-images-v1 (images)
3. Click on each cache to view cached items

5. Test Install Prompt

Desktop (Chrome/Edge):

1. Visit http://localhost:4173 (must be preview mode)
2. Look for install icon in address bar
3. Click to install
4. Or wait 3 seconds for install prompt

Mobile (Chrome):

1. Visit site in Chrome mobile
2. Wait for "Add to Home Screen" prompt
3. Tap "Add" to install

Mobile (Safari iOS):

1. Visit site in Safari
2. Tap Share button
3. Scroll and tap "Add to Home Screen"
4. Confirm

6. Run Lighthouse Audit

1. Open Chrome DevTools
2. Go to Lighthouse tab
3. Select:
   • ✅ Progressive Web App
   • ✅ Performance
   • ✅ Accessibility
   • ✅ Best Practices
   • ✅ SEO
4. Click Generate report
5. Target scores:
   • PWA: 100/100
   • Performance: 90+/100
   • Accessibility: 95+/100
   • Best Practices: 100/100
   • SEO: 100/100

7. Test Media Session API

1. Play an audio file
2. Check notification tray (desktop/mobile)
3. Verify:
   • ✅ Song title displayed
   • ✅ Artist name displayed
   • ✅ Album art shown (if available)
   • ✅ Play/pause button works
   • ✅ Seek buttons work (10s forward/back)

Lock Screen (Mobile):

1. Play audio
2. Lock device
3. Check lock screen controls

8. Test Notifications

1. Go to Settings page
2. Find PWA section
3. Toggle Enable push notifications
4. Accept permission prompt
5. Verify:
   • ✅ Permission granted
   • ✅ Toggle stays enabled
   • ✅ Success message shown

9. Test Cache Management

1. Go to Settings > PWA section
2. Check cache size display
3. Click Clear Cache button
4. Verify:
   • ✅ Cache cleared successfully
   • ✅ Cache size resets
   • ✅ Success message shown
5. Reload page to rebuild cache

10. Test Update Flow

1. Make a change to code
2. Build new version: npm run build
3. In running app, wait ~30 seconds
4. Verify:
   • ✅ Update notification appears
   • ✅ "Update" button shown
5. Click "Update"
6. Verify:
   • ✅ Page reloads
   • ✅ New version active

🧪 Testing Checklist

Installation

• Desktop Chrome install prompt appears
• Desktop Edge install prompt appears
• Android Chrome "Add to Home Screen" works
• iOS Safari "Add to Home Screen" works
• Installed app opens in standalone mode
• App has correct icon and name

Offline Functionality

• Service worker registers successfully
• Page loads offline
• Previously viewed content accessible offline
• Offline indicator shows when offline
• Online indicator shows when back online
• Cached audio plays offline
• Images load from cache offline

Performance

• First page load < 3 seconds
• Subsequent loads < 1 second
• Smooth scrolling on mobile
• No layout shift
• Touch targets ≥ 44px
• No zoom on input focus

Media Controls

• Media session metadata shows correctly
• Play/pause from notification tray works
• Lock screen controls work (mobile)
• Seek forward/backward works
• Position state updates on system controls
• Controls disappear when audio ends

UI/UX

• Install prompt shows after 3 seconds
• Update prompt shows when available
• Offline alert persistent when offline
• Online notification shows briefly
• Cache size displays correctly
• Clear cache works
• All buttons have proper touch feedback
• Loading states show appropriately

Responsive Design

• Works on mobile (320px width)
• Works on tablet (768px width)
• Works on desktop (1920px width)
• Safe areas respected on notched devices
• Landscape mode works correctly

Accessibility

• Keyboard navigation works
• Focus indicators visible
• Screen reader compatible
• Color contrast sufficient
• Reduced motion respected

Cross-Browser

• Chrome Desktop
• Chrome Android
• Edge Desktop
• Safari Desktop
• Safari iOS
• Firefox Desktop
• Samsung Internet

🐛 Troubleshooting

Service Worker Not Registering

Issue: Console shows service worker registration failed

Solutions:

1. Serve over HTTPS or localhost
2. Check service worker file path is correct
3. Clear browser cache (Ctrl+Shift+Delete)
4. Check console for detailed error
5. Verify vite.config.ts has correct publicDir

# Force rebuild
rm -rf frontend/dist
npm run build

Install Prompt Not Showing

Issue: No install button or prompt appears

Checklist:

• Using HTTPS or localhost
• Manifest.json loads without errors
• Service worker registered and active
• All manifest icons exist
• User hasn't dismissed recently (wait 90 days)
• User hasn't already installed
• Using Chrome/Edge (not Firefox/Safari)

Test:

// In console
window.addEventListener('beforeinstallprompt', (e) => {
  console.log('Install prompt available!', e);
});

Offline Mode Not Working

Issue: Page doesn't load offline

Solutions:

1. Visit pages while online first (to cache them)
2. Check service worker is active:

   navigator.serviceWorker.getRegistration().then(reg => {
     console.log('Active:', reg?.active);
   });
   

3. Check cache storage has content:
   • DevTools > Application > Cache Storage
4. Verify fetch handler in service worker

Media Session Not Working

Issue: No controls in notification tray

Browser Support:

• ✅ Chrome Desktop/Android
• ✅ Edge Desktop
• ⚠️ Safari (limited)
• ❌ Firefox Desktop (partial)

Solutions:

1. Check if API supported:

   if ('mediaSession' in navigator) {
     console.log('Media Session API supported');
   }
   

2. Verify metadata is set correctly
3. Check action handlers are defined
4. Test in Chrome first

Cache Not Clearing

Issue: Old content still showing after clear

Solutions:

1. Hard refresh (Ctrl+Shift+R)
2. Clear browser cache:
   • DevTools > Application > Clear storage > Clear site data
3. Unregister service worker:

   navigator.serviceWorker.getRegistrations().then(registrations => {
     registrations.forEach(reg => reg.unregister());
   });
   

4. Reload page

Icons Not Loading

Issue: Icons show broken or default

Solutions:

1. Generate icons:

   ../scripts/generate-pwa-icons.sh
   

2. Or use online tools and place in frontend/public/img/
3. Required sizes: 72, 96, 128, 144, 152, 192, 384, 512
4. Update manifest.json paths if needed
5. Clear cache and rebuild

📊 Performance Optimization

Check Bundle Size

npm run build -- --report

Analyze Cache Usage

// In console
async function checkCacheSize() {
  const estimate = await navigator.storage.estimate();
  const usage = estimate.usage / (1024 * 1024); // MB
  const quota = estimate.quota / (1024 * 1024); // MB
  console.log(`Cache: ${usage.toFixed(2)} MB / ${quota.toFixed(2)} MB`);
}
checkCacheSize();

Monitor Service Worker

// In console
navigator.serviceWorker.addEventListener('message', (event) => {
  console.log('SW Message:', event.data);
});

📚 Additional Resources

• Full Documentation: PWA_IMPLEMENTATION.md
• Complete Summary: COMPLETE_PWA_SUMMARY.md
• Developer Guide: PWA_DEVELOPER_GUIDE.md
• Icon Generator: https://www.pwabuilder.com/imageGenerator
• PWA Checklist: https://web.dev/pwa-checklist/
• Lighthouse: https://developers.google.com/web/tools/lighthouse

🎉 Success Criteria

Your PWA is ready when:

• ✅ Lighthouse PWA score: 100/100
• ✅ Installs successfully on all platforms
• ✅ Works offline with cached content
• ✅ Service worker registers and caches content
• ✅ Media controls work in notification tray
• ✅ Update flow works correctly
• ✅ All touch targets ≥ 44px
• ✅ Responsive on all screen sizes
• ✅ Accessible via keyboard
• ✅ No console errors

---

Ready to Deploy? Check the production deployment guide in PWA_IMPLEMENTATION.md!