How to Test a Progressive Web App: A Practical Checklist

A progressive web app (PWA) is tested by checking the user tasks it promises across your supported browsers and devices: first as a normal website, then for installation, offline behavior, performance, accessibility, and any optional device APIs it uses. Use the checklist below to test those behaviors directly. A passing manifest audit or Lighthouse score alone does not prove the app works for users.

web.dev describes PWAs as web apps first: they need to work across browsers. Build your test matrix around your audience and the capabilities your product actually claims, rather than treating one score as certification. web.dev PWA checklist

1. Test the ordinary website experience

Start without installing the app. Open it as a website in the browsers you support, and complete the important tasks from a fresh visit. Progressive enhancement means essential tasks should still work when a browser does not support a particular PWA enhancement or web API.

Browsers: include Chrome, Edge, Firefox, and Safari in the baseline where they are relevant to your audience. Record the browser and operating system versions used.
Routes and tasks: open the home page, deep links, authenticated areas, forms, and other core routes. Complete real user flows instead of checking only that pages render.
Layouts and input: check narrow and wide viewports, touch input on touch devices, and keyboard input. Confirm that content and actions remain available as the layout changes.
Direct navigation: paste a deep link into the address bar and refresh it. Verify that server routing returns the right app route rather than a 404.
Enhancement fallback: where a browser lacks an optional capability, confirm users can still complete the underlying task or receive a clear explanation.

2. Check the manifest and installation on each platform

Inspect the manifest link on every page where installation is expected, load the manifest itself, and then try the real installation flow on each browser and operating system you support. The manifest is necessary for Chromium-based installability checks, but it is not sufficient to establish that installation works everywhere.

Manifest checklist

MDN lists these members for Chromium-based browsers: name or short_name; 192px and 512px icons; start_url; display and/or display_override; and prefer_related_applications set to false or omitted. Production should use HTTPS; localhost and 127.0.0.1 are allowed for local development. See MDN’s manifest installability guidance.

<link rel="manifest" href="/manifest.webmanifest">

Check that the manifest URL responds successfully, is served with an appropriate JSON content type, and contains valid JSON. Verify that icon URLs resolve and that the configured start URL is within the app’s intended scope.

Installation checklist

Try installation through the browser’s actual UI on every supported browser/OS combination.
Confirm the installed app’s name and icon are correct and recognizable.
Launch it and verify it opens the intended start route and uses the expected display mode.
Test an already-installed visit and a fresh visit separately; prompts and browser UI can differ.
Document platform-specific flows. There is no universal install prompt: Android may support WebAPK installation, while iOS uses its own installation flow. Chrome’s beforeinstallprompt event is not supported on iOS in the MDN guidance.

Do not treat a legacy Lighthouse manifest audit as proof of cross-platform installation. Chrome’s Lighthouse PWA documentation says PWA testing is deprecated and notes that a manifest is necessary but not sufficient. Chrome for Developers: Lighthouse PWA audits

3. Exercise service worker and offline behavior

Offline testing must include actual reloads and user tasks, not just checking that a service worker file exists. Begin with a clean online visit so the worker can install and cache the resources your app needs.

Load the app online and confirm the service worker registers and controls the expected pages.
Use browser developer tools to simulate offline mode or disconnect the device from the network.
Reload the manifest’s start_url. It should reach useful app content after the required resources have been cached.
Visit a route you know is cached, then try an uncached route. Confirm the latter shows a useful offline response rather than a blank screen or misleading stale content.
Repeat each task the product claims works offline, such as reading saved content or drafting a record.
Restore connectivity. If actions were queued, confirm the app shows pending work honestly, syncs according to its rules, handles conflicts, and does not submit duplicates.

Service worker Cache and FetchEvent APIs can store and return responses; background synchronization can defer work until connectivity is stable. These mechanisms do not define what your app should do with conflicts or duplicate actions: specify expected behavior from your product’s data rules and verify it. See MDN’s offline and background operation guide and MDN’s Service Worker API reference.

4. Measure performance and reliability

Check both cold loads and repeat visits. Try a slow connection and inspect large assets, loading states, and whether taps or other interactions respond promptly. A cache can improve repeat visits but can also serve stale data, so verify freshness and update behavior against the app’s requirements.

Separate lab measurements from real-user data; they answer different questions.
Use Lighthouse for general performance audits, and consider PageSpeed Insights and Chrome User Experience Report for field performance data, as described by web.dev.
Check that loading, retry, and error states are understandable under slow or interrupted connections.
Repeat critical flows after deployment and after service worker or caching changes.

web.dev reports that as page load time increases from one second to ten seconds, the probability of a user bouncing increases by 123%. This is a reported relationship, not a prediction for every individual PWA or user.

5. Include accessibility in release checks

Automated audits can find some issues, but manual checks remain necessary. Use the app with a keyboard and verify focus order, visible focus, semantic controls, form labels, and meaningful status messages. Test with screen readers on the platforms you support when applicable.

Can users reach every control without a pointer?
Is focus visible and does it move in a sensible order?
Do controls expose their purpose and state through native semantics or accessible names?
Are form errors and asynchronous updates communicated clearly?
Does zooming or a narrow viewport preserve access to content and actions?

Lighthouse accessibility audits, axe, and Accessibility Insights can help find some problems, but web.dev notes that most accessibility testing must be manual. Identify the applicable WCAG version for your jurisdiction and release requirements rather than assuming an audit score establishes conformance. web.dev PWA checklist

6. Test optional APIs only if the app uses them

Notifications, sharing, background sync, IndexedDB, badges, and window-controls overlays are optional capabilities, not universal PWA requirements. For each feature you ship, test the states below and confirm the core task remains usable without the API.

Capability	Cases to exercise
Notifications or other permissions	Not asked yet, granted, denied, and permission later revoked. Provide a useful in-app fallback when denied.
Sharing	Supported device and browser, unavailable API, and cancellation or failure of the share flow.
Background sync	Queued work, delayed connectivity, retry, conflict, and duplicate prevention according to product rules.
IndexedDB or local persistence	Fresh profile, existing data, upgrade path, storage failure, and recovery after data is cleared.
Badges or window controls	Supported and unsupported platforms, plus a clear fallback that does not hide essential information.

Use the relevant browser documentation and your declared support matrix; APIs and platform support vary. MDN’s PWA reference describes these capabilities and their intended roles.

7. Build a focused test matrix

Testing every possible combination can become wasteful. Select combinations that cover your audience, critical tasks, and advertised capabilities. Include representative cases from each dimension:

Dimension	Useful cases
Browser and OS	Supported desktop and mobile browser/OS combinations, including platform-specific install behavior.
Device and input	Phone, tablet, desktop; touch and keyboard where relevant.
Visit state	Fresh visit, returning visit, and installed launch.
Network	Online, slow, interrupted, and offline.
Route state	Start URL, cached route, uncached route, and deep link.
API support	Capability available, permission refused, and capability unavailable.

For each case, write the expected result and record pass/fail, environment, and any issue. This makes platform differences explicit and gives the team a repeatable release checklist.

8. Use screenshots to review rendered states

A screenshot is useful for reviewing layout differences across viewports and for keeping visual records of online, offline, installed, or error states. It does not verify keyboard behavior, screen-reader output, service worker control, or whether a task actually completes; pair visual review with the interaction checks above.

Capture a page with cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Capture a page with Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Capture a page with Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Replace the example target URL with a publicly reachable page you are authorized to capture. Keep the API key out of client-side code and source control. See the ScreenshotNeo API documentation for request options and response details.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-request API returns a screenshot or PDF:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Cookie banners are accepted and removed before the shot, along with known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use the take_screenshot, get_page_info, and capture_pdf tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Screenshot review complements the hands-on PWA checks above; it does not replace offline or accessibility testing.

Troubleshooting common PWA test failures

Symptom	Likely cause	What to check or fix
Install option does not appear	Manifest link or required manifest members are missing or invalid, icons do not load, or this platform uses a different installation flow.	Load and validate the manifest and icons, check HTTPS (or localhost during development), then try the platform’s documented installation UI. Do not expect the same prompt on every OS.
Installed app opens the wrong page	`start_url`, scope, or route handling does not match the intended launch behavior.	Check the manifest values and server fallback behavior; install again after changes and launch from the installed icon.
Offline reload is blank or errors	The start route or required assets were never cached, or the worker did not control the page.	Load online first, confirm registration and control, inspect cache behavior, then test start, cached, and uncached routes separately.
Old content remains after an update	A cache or service worker update strategy is serving stale resources.	Inspect versioning and cache cleanup behavior, and test both first visit and update from an already installed/returning state.
Queued action disappears or duplicates	Pending state, retry rules, or synchronization is unclear or not idempotent.	Define the expected pending and conflict states, then test interrupted connectivity, retry, and duplicate prevention against those rules.
A permission-based feature fails for some users	Permission is denied, not yet requested, revoked, or unsupported.	Exercise all permission states and provide an in-app fallback that preserves the core task.
Lighthouse shows no PWA badge or audit	Chrome has deprecated Lighthouse PWA testing.	Use Lighthouse for relevant performance/accessibility audits, and directly test manifest, installation, offline behavior, and user flows.

Performance, reliability, and cost considerations

Performance: large assets and slow networks affect first visits most; repeat visits can benefit from caching, provided freshness remains correct.
Reliability: offline support is a product promise. State which routes and actions work offline, what remains pending, and how users know when synchronization finishes.
Test effort: prioritize combinations by audience and risk. Cover each claimed capability and important platform variation without blindly testing every permutation.
Screenshot review: automated captures can make visual comparisons repeatable, while API usage has a direct per-plan allowance. ScreenshotNeo offers 1,000 free shots monthly; paid plans are $5 for 3,000, $15 for 15,000, $39 for 60,000, $99 for 250,000, and $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan.

FAQ

Does a PWA have to work offline?

Only if the product claims offline support. Define exactly which pages and tasks remain available without a connection, then test those claims directly.

Does Lighthouse still test PWAs?

Chrome’s Lighthouse PWA testing is deprecated. Lighthouse remains useful for other audits, but its old PWA badge should not be presented as current comprehensive certification.

Is a service worker enough to make an app installable?

No. Installation depends on manifest and platform behavior as well as the browser and operating system; test the real install and launch flow on each supported combination.

Can I test installation on localhost?

Local development on localhost or 127.0.0.1 is allowed for the manifest installability requirements described by MDN. Verify production behavior over HTTPS as well.

Should every optional web API be tested?

Test the APIs your app actually uses. For each one, include unsupported and denied states so the core experience remains understandable.