PWA Testing Checklist: Step-by-Step Guide

This guide walks you through a practical, step-by-step checklist for testing a Progressive Web App (PWA) across all the key areas: installability, offline behavior, performance, and security. You’ll start with a basic setup and end with a fully verified PWA that meets the core requirements for both users and app stores. Before you begin, ensure you have a running PWA with a manifest and a service worker, and a browser with DevTools (Chrome or Edge recommended).

What You’ll Need

A PWA that is already deployed to a secure (HTTPS) URL.
Chrome or Edge browser with DevTools (for Lighthouse and application panel).
Optional: An Android device or emulator to test install prompts and home screen behavior.
A text editor or the browser’s DevTools to inspect manifest and service worker files.

Step-by-Step

Verify HTTPS and Valid Manifest: Open your PWA in a new tab. In DevTools (F12), go to the Application panel, then Manifest. Check that the name, short_name, start_url, display (standalone or minimal-ui), and icons (at least 192×192 and 512×512) are all present and valid. The browser will show errors if any required fields are missing.
Test Installability: In the same Application panel, look for the ‘Installability’ section. It should show ‘Yes’ or list issues. Then, click the browser’s install icon (usually a plus sign in the address bar) and follow the prompts to install the PWA. On desktop, confirm it opens in a standalone window without browser UI. On mobile, check it appears on the home screen with the correct icon and name.
Check Offline Functionality: With the PWA open, go to the Network tab in DevTools and set the throttling to ‘Offline’. Reload the page. The app should still load (from cache) and show a valid page, not a browser error. If you have dynamic content, ensure it shows a fallback message or cached data. Also test offline navigation: click through a few pages to ensure they work or show a friendly offline page.
Test Service Worker Lifecycle: In the Application panel, under Service Workers, check that the service worker is activated and running. Update the service worker file (e.g., change a version number) and reload the page. The new worker should install, then wait, then activate. Verify that the ‘Update on reload’ checkbox works as expected. Also test the ‘Unregister’ button to see how the app behaves without a service worker (should still load, but offline won’t work).
Run Lighthouse Audit: Open DevTools, go to the Lighthouse tab (or use the ‘Audits’ tab in older versions). Select ‘Progressive Web App’ as the category, and run the audit. Review the scores for each PWA check (installable, offline, etc.). Fix any failing audits—common ones include missing icons, incorrect start_url, or no 404 page for offline.
Test Performance and Responsiveness: Use Lighthouse’s ‘Performance’ audit to check load time, time to interactive, and other metrics. Also, resize the browser window to mobile sizes (e.g., 375×667) and ensure the layout is responsive. Check that touch targets are large enough (at least 48px) and that the app is usable on a touch screen.
Verify Security (HTTPS and Mixed Content): Ensure your PWA is served over HTTPS. In DevTools, check the Console for any mixed content warnings (e.g., loading images or scripts over HTTP). Also, in the Security panel, confirm that the page has no security issues. If you use any third-party services, ensure they are HTTPS as well.
Test with Different Browsers: While Chrome is the primary test environment, check your PWA in Firefox, Safari (on iOS), and Edge. Note that Safari has specific requirements for installability (e.g., manifest and service worker support). Use the browser’s DevTools to simulate mobile and test basic functionality.
Test on a Real Device: If possible, open your PWA on an Android phone or tablet. Try to install it, add it to the home screen, and use it offline. Check that the splash screen appears correctly and that the app behaves like a native app (e.g., no browser URL bar). For iOS, use the ‘Add to Home Screen’ option in Safari.
Check App Shell and Update Flow: Ensure that the app shell (the core UI) loads quickly and is cached. When you release a new version, test that the service worker updates the cache and that users see the new version after the next load (or after a prompt if you implement one). Use the ‘Update’ button in the Application panel to force an update and verify the new content appears.

Common Mistakes

Forgetting to include a 192×192 and 512×512 icon in the manifest. Without these, the PWA won’t be installable.
Using a start_url that doesn’t match the actual root of the app, causing the installed app to open the wrong page.
Not handling offline navigation correctly—users get a browser error instead of a friendly offline page.
Over-caching dynamic content, leading to stale data being shown even when online.
Ignoring the ‘display’ property in the manifest—if it’s set to ‘browser’, the app won’t open in a standalone window.

Tips

Use the Application panel’s ‘Service Workers’ section to simulate offline and test updates without leaving DevTools.
Run Lighthouse in an incognito window to avoid interference from extensions.
Keep your service worker scope in mind—it should cover all pages you want to be offline.
Test on a low-end Android device to ensure performance is acceptable for real-world users.
Use the ‘Network Throttling’ feature to simulate slow connections and see how your PWA behaves.

Troubleshooting

If the PWA doesn’t install, check the console for errors about the manifest or service worker. Ensure the manifest is linked correctly in the HTML head. If offline fails, inspect the service worker’s cache names and the fetch event handler—make sure you’re responding with the correct cached assets. If the install prompt doesn’t appear, verify that the PWA meets all install criteria (HTTPS, manifest with required fields, and a service worker with a fetch handler). If the app doesn’t update, check that the service worker file itself changes (e.g., bump a version number) and that the browser is not using a cached worker—use the ‘Update’ button in DevTools.

Frequently Asked Questions

Q: What is the minimum icon size for a PWA?
A: You need at least a 192×192 icon for the install prompt, but 512×512 is recommended for high-resolution screens. Both sizes should be included in the manifest.

Q: Can a PWA work on iOS?
A: Yes, but with limitations. iOS Safari supports service workers and manifests, but you must use the ‘Add to Home Screen’ option. The install prompt is not supported, and some features like push notifications are not available.

Q: How do I test a PWA on a real device?
A: You can use a tool like ngrok to expose your local server to the internet, then open the URL on your device. Alternatively, deploy to a staging server and access it from the device.

Q: Why does my PWA not update immediately after I deploy a new version?
A: The service worker controls when updates are applied. By default, the new worker waits until all tabs are closed. You can use self.skipWaiting() and clients.claim() to force an update, but do so carefully to avoid breaking the user’s session.

Q: What is the difference between a service worker and a web worker?
A: A service worker is a specific type of web worker that acts as a network proxy, enabling offline support and push notifications. Web workers are general-purpose background scripts for heavy computation.

Q: Can I use a service worker on HTTP?
A: No, service workers require HTTPS (or localhost for development). This is a security measure to prevent malicious code from intercepting network requests.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →