pwa-install-flow-reference

Overview

The PWA install flow is a four-stage test surface: installability gate → install prompt handshake → platform-specific install path → post-install runtime signal. Each stage has a documented contract the test suite can assert against. This skill is the reference the per-stage builders (add-to-homescreen-flow-test, web-push-test) and the audit reader (lighthouse-pwa-audit) consult.

This is a pure reference - no execution steps. The body is tables + verbatim spec quotes. Builders consume it to emit tests without re-fetching the source pages.

When to use

• Bootstrapping a PWA test plan and need the gate fields up-front before writing a single assertion.
• A beforeinstallprompt test is flaking - consult the contract to separate "gate not met" from "test setup wrong".
• A team wants per-platform expectations (Chromium vs iOS Safari vs Android Chrome vs Edge) without re-reading three vendor docs.
• An auditor (PR reviewer, accessibility reviewer) needs a one-screen summary of what "installable" actually means.

Stage 1 - Installability gate

Per install-criteria, a page becomes installable on Chromium when every cell below is satisfied. Failures are silent: the beforeinstallprompt event simply never fires. Tests must assert each cell independently to localize gate failures.

Per install-criteria, when every cell passes "Chrome fires the beforeinstallprompt event and displays an install promotion in the browser UI (address bar button or overflow menu)."

Per learn-pwa: "As a minimum requirement for installability, most browsers that support it use the Web App Manifest file and certain properties such as the name of the app, and configuration of the installed experience." Edge, Samsung Internet, and Opera follow the Chromium criteria; Firefox desktop does not implement beforeinstallprompt; Safari uses a manual flow (Stage 3 below).

Stage 2 - The beforeinstallprompt handshake

Per customize-install, the canonical four-call lifecycle:

The BeforeInstallPromptEvent instance also exposes a platforms property - the array of install targets the browser would offer (typically ['web'] on desktop Chromium); tests can assert against this to detect WebView vs full Chromium environments.

Stage 3 - Per-platform install path

The install path itself diverges by platform. Tests must branch:

Per learn-pwa: iOS install "requires apple-touch-icon tag" - a test that omits this assertion misses a class of icon-missing install regressions that are otherwise invisible until a user files a bug.

Stage 4 - Post-install runtime signal

After install, the running PWA can detect its installed state via the display-mode media query. The query matches standalone, minimal-ui, fullscreen, or window-controls-overlay per the manifest's display field - the same values Stage 1 enumerates.

Tests use this signal to:

• Hide the in-app "Install" button (the prompt won't fire when already installed per Stage 1's "Not pre-installed" cell).
• Branch analytics: a session in display-mode: standalone is a PWA-launch session.
• Assert that a --app= launched Chromium instance reports standalone (a common test pattern; see add-to-homescreen-flow-test).

The signal can be polled (matchMedia('(display-mode: standalone)').matches) or observed (mql.addEventListener('change', ...)); both are fair-game in tests.

The full event timeline

For a single user who installs and launches the PWA, the event sequence is:

1. Page loads.                                  (page load)
2. Service worker registers.                    (Stage 1 prerequisite)
3. User engagement reaches the threshold.       (Stage 1 prerequisite)
4. Manifest gate passes.                        (Stage 1)
5. browser fires beforeinstallprompt.           (Stage 2)
6. App calls event.preventDefault() + stashes.  (Stage 2)
7. User clicks the app's "Install" button.      (Stage 2 — user gesture)
8. App calls stashedEvent.prompt().             (Stage 2)
9. User accepts → userChoice resolves accepted. (Stage 2)
10. Browser installs (WebAPK / shortcut / desktop bundle).  (Stage 3)
11. Browser fires appinstalled.                 (Stage 2)
12. Next session: PWA launches in display-mode standalone.  (Stage 4)

A test plan covers each step with an assertion or a documented gap ("step 10 not assertable in headless").

Common test-setup anti-patterns

Limitations

• The 30-second engagement timer is browser-internal. Tests cannot directly query the timer; they can only assert that beforeinstallprompt did fire after sufficient engagement, not the precise threshold.
• WebAPK minting completion is opaque. Per learn-pwa Android Chrome mints a WebAPK on install, but the test surface ends at appinstalled - the minting is a background-service-worker operation, not a DOM-observable event.
• iOS Safari has no programmatic install API. Stage 3 iOS cells must be tested with manual smoke or device-farm Appium drivers; no headless path exists.
• prefer_related_applications: true suppresses install entirely. Per install-criteria, it gates Stage 1; tests that miss this field on a manifest that also defines a native counterpart will assert installability incorrectly.
• display-mode MQ does not survive deep-link launches in all browsers. Some launchers open the URL in the system browser rather than the installed PWA; the MQ then reports browser, which is correct but easy to misread as "install regressed."

References

• web.dev - Install criteria (the Stage 1 gate cells and the Chromium-side engagement requirement) - install-criteria.
• web.dev - Learn PWA: Installation (per-platform install paths, WebAPK, iOS Share-menu flow, apple-touch-icon requirement) - learn-pwa.
• web.dev - Customize the install experience (Stage 2 handshake: preventDefault / prompt() / userChoice / appinstalled) - customize-install.
• Consumed by: add-to-homescreen-flow-test, web-push-test, lighthouse-pwa-audit.
• Differentiation: qa-modern-web/pwa-install-flow-tests authors the install-flow Playwright tests; this skill is the reference shape those tests consume. Read this first when triaging a flaky install assertion.