Skip to content

Test a PWA

Published Updated

Chrome DevTools lets you check why a page is installable, control a service worker through install and waiting, then activation. You can simulate offline without disconnecting the machine and confirm installation on a real Android device. Use the Application panel for most of these checks, with the Console drawer for install and lifecycle messages. Lighthouse’s PWA category is deprecated.

You need the app served over HTTPS or localhost and Chrome with DevTools. For the last step, you also need an Android phone with USB debugging enabled. The controls use the English DevTools labels.

These DevTools steps use Chrome. Chrome’s remote-debugging guide documents desktop hosts on Windows, macOS, and Linux connected to Chrome on Android. Device Mode does not reproduce the mobile installation flow.

The registration check uses the Service Worker API. The compatibility dataset records support from Chrome 40, Edge 17, Firefox 44, Safari 11.1 on macOS, Safari 11.3 on iOS, Samsung Internet 4.0, and Android WebView 40 (BCD api.ServiceWorker).

1. Read the manifest and its Installability section

Section titled “1. Read the manifest and its Installability section”

Open DevTools, select Application, then Manifest. The Identity and Presentation sections show the manifest fields in readable form, Icons lists each declared icon (the Show only the minimum safe area for maskable icons checkbox previews the cropped safe area), and Shortcut #N and Screenshot #N sections follow. When an icon fails to load or a required field is missing, an Installability section appears with the reason. Keep the Console drawer open while you click the address bar’s Install button: it logs manifest problems and the install lifecycle.

A manifest that passes has at least this:

{
"name": "Example PWA",
"short_name": "Example",
"start_url": "/",
"scope": "/",
"display": "standalone",
"icons": [
{ "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
]
}

The full list of conditions is in Installability criteria: what makes a PWA installable.

2. Drive the worker from the Service workers pane

Section titled “2. Drive the worker from the Service workers pane”

Application > Service workers lists the registration for the open page with its Source and Status lines as well as Clients. Use its controls to test the worker:

  • Offline puts DevTools into offline mode, the same as the Network panel’s Offline throttling preset. Reload with it checked to see what the worker serves without a network.
  • Update on reload forces a service worker update on each page load. Use it while you edit sw.js, then turn it off before testing the normal update lifecycle.
  • Bypass for network sends requests straight to the network, which tells you whether a bug lives in the worker or in the page.
  • Push emulates a push notification without a payload, and Sync emulates a background sync event.
  • stop halts the running worker; the next event starts it with fresh global state, which surfaces code that assumed in-memory variables survive.
  • Unregister removes the registration; Update performs a one-time update check.

The Update Cycle table shows the worker’s activities and elapsed times, such as install and wait followed by activate; the Expand buttons reveal exact timestamps.

3. Detect a registration before asserting on it

Section titled “3. Detect a registration before asserting on it”

A test harness that assumes navigator.serviceWorker exists throws in browsers without the API, and getRegistration() resolves with undefined when nothing is registered for the scope. Check both so the harness reports a reason instead of a stack trace.

export async function serviceWorkerState() {
if (!('serviceWorker' in navigator)) {
return { ok: false, reason: 'Service workers are not supported in this browser.' };
}
const registration = await navigator.serviceWorker.getRegistration();
if (!registration) {
return { ok: false, reason: 'No service worker is registered for this page yet.' };
}
const worker = registration.active || registration.waiting || registration.installing;
return { ok: true, state: worker ? worker.state : 'unknown', scope: registration.scope };
}

Run it from the Console: (await serviceWorkerState()).state prints activated once the worker has finished activating. Before that it can print installing or installed, or it can print activating. Run the whole function when a failure is more useful than reading .state. With no registration for the document, the command returns the fallback object instead of trying to read .active from undefined:

await serviceWorkerState()
// { ok: false, reason: 'No service worker is registered for this page yet.' }

After registration and activation, the same command returns an object whose ok value is true, whose state value is activated, and whose scope value comes from the registration. MDN documents that getRegistration() resolves to undefined when no registration matches.

4. Install on a real phone over remote debugging

Section titled “4. Install on a real phone over remote debugging”

Chrome’s PWA debugging guide says Device Mode cannot simulate the mobile installation workflow. Connect an Android phone over USB, enable USB debugging, and open chrome://inspect#devices on the desktop. Enable Discover USB devices, select the page, and attach DevTools. In Chrome on the phone, open the menu and choose Install app (or Add to Home screen on some devices). The expected result is the installation flow on the connected device, while the attached DevTools instance lets you inspect that live page. Chrome’s remote debugging guide documents device discovery and inspection from Windows, macOS, or Linux.

Before the 2026-11-13 correction, Push was described as sending a typed payload, and Update on reload as reinstalling a byte-identical worker and skipping its waiting phase. Chrome’s documentation says that Push emulates a push notification without a payload and Update on reload forces a service worker update on each page load.

← Back to the Guides overview.