Skip to content

MaarkssDN/Birthub-360 / .agents/skills/add-to-homescreen-flow-tests

add-to-homescreen-flow-tests

Verified

Use when a PWA's manifest, icons or install handler change, install conversions drop, or an install test is flaky. Builds Playwright tests for the install flow: installability criteria, the beforeinstallprompt and userChoice chain, the iOS Safari path and display-mode standalone after install.

references/install-flow-reference.md

View on GitHub
# PWA install flow - the reference contract

Companion reference for `add-to-homescreen-flow-tests`. Consult when a
`beforeinstallprompt` test is flaking and you need the contract to separate
"gate not met" from "test setup wrong", or when you need the gate fields, the
event contract, and the per-platform expectations in one place instead of
re-reading three vendor docs.

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; the SKILL.md workflow emits one verification cell per
contract row.

[install-criteria]: https://web.dev/articles/install-criteria
[learn-pwa]: https://web.dev/learn/pwa/installation
[customize-install]: https://web.dev/articles/customize-install

## 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.

| Cell | Requirement | Source |
|---|---|---|
| Manifest name | `"short_name" or "name"` present | [install-criteria] |
| Manifest icons | `"icons"` array must include both 192px and 512px icons | [install-criteria] |
| Manifest start | `"start_url"` present | [install-criteria] |
| Manifest display | `"display"` must be `fullscreen`, `standalone`, `minimal-ui`, or `window-controls-overlay` | [install-criteria] |
| Manifest related-apps gate | `"prefer_related_applications"` must not be present or be `false` | [install-criteria] |
| Transport | "Be served over HTTPS" | [install-criteria] |
| User engagement | "Users must click/tap the page at least once and spend minimum 30 seconds viewing it" | [install-criteria] |
| Not pre-installed | "The web app is not already installed" | [install-criteria] |

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).

## Stage 2 - The `beforeinstallprompt` handshake

Per [customize-install], the canonical lifecycle:

| Call | Purpose |
|---|---|
| `event.preventDefault()` | "Prevent the mini-infobar from appearing on mobile" |
| Stash `event` reference | Save the deferred prompt for the app's own "Install" button |
| `event.prompt()` | Show the prompt; must be called from a user-gesture handler. "You can only call `prompt()` on the deferred event once" |
| `await event.userChoice` | Resolves to `{ outcome: 'accepted' \| 'dismissed' }` |
| `appinstalled` event | Fires "whenever installation succeeds, regardless of the trigger mechanism" - covers both custom-button and browser-driven installs |

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 diverges by platform; tests must branch:

| Platform | Path | Trigger | Test posture |
|---|---|---|---|
| Chromium desktop (Chrome, Edge, Brave) | Install badge in URL bar; "Install" item in overflow menu | `beforeinstallprompt` fires when Stage 1 passes | Drive `prompt()` from a user-gesture click; assert `userChoice.outcome` and `appinstalled` |
| Android Chrome | WebAPK minting (a real APK signed by Google Play services and registered with the launcher) per [learn-pwa] | `beforeinstallprompt` fires; user accepts via mini-infobar or app-driven prompt | Smoke on a real device farm; Playwright on Android Chrome works for the prompt itself but cannot assert WebAPK minting completion |
| Android Chrome (alternate) | Shortcuts or QuickApp formats per [learn-pwa] | Same as WebAPK path | WebAPK is the canonical path; shortcut path is a fallback |
| iOS / iPadOS Safari | "Open the Share menu... Click Add to Home Screen... Confirm the name of the app... Click Add" per [learn-pwa] | Manual user gesture only; no `beforeinstallprompt` event | Test the metadata (`apple-touch-icon`, `apple-mobile-web-app-capable` meta) statically; assert installed runtime via the `display-mode` MQ; the actual install step is manual smoke |
| Desktop Safari | App-driven install on macOS Sonoma+ via the "Add to Dock" Share menu | Manual user gesture only | Same posture as iOS - static metadata + post-install MQ |
| Firefox desktop | Install UI not exposed | n/a | No `beforeinstallprompt`; no install assertion path |

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

Per-platform caveats:

- **WebAPK minting completion is opaque.** The test surface ends at
  `appinstalled`; the minting is a background operation, not a
  DOM-observable event.
- **iOS Safari has no programmatic install API.** iOS cells need manual
  smoke or device-farm Appium drivers; no headless path exists.

## Stage 4 - Post-install runtime signal

After install, the running PWA detects 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`.

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

## The full event timeline

```
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

| Anti-pattern | Why it fails | Better posture |
|---|---|---|
| Calling `prompt()` without user gesture | Browser blocks; Stage 2 contract violated per [customize-install] | Always tie to a user click handler |
| Calling `prompt()` twice on the same event | "You can only call `prompt()` on the deferred event once" per [customize-install] | Re-bind a fresh `beforeinstallprompt` listener for the next attempt |
| Asserting installability without 30s+ engagement | Stage 1 user-engagement cell fails silently per [install-criteria] | Simulate engagement (scroll, click) before asserting `beforeinstallprompt` |
| Asserting `appinstalled` then immediately closing the page | The event may fire post-close; race on visibility | Bind the listener at page load, not at click-time |
| Treating iOS the same as Chromium | Stage 2 doesn't apply on Safari; the install path is manual per [learn-pwa] | Branch test paths; assert metadata + `display-mode` only |
| Manifest in subdirectory without `scope` | `start_url` outside `scope` invalidates the manifest gate | Set `scope` to the parent path of `start_url` |

## Limitations

- **The 30-second engagement timer is browser-internal.** Tests can only
  assert that `beforeinstallprompt` *did* fire after sufficient engagement,
  not the precise threshold.
- **`prefer_related_applications: true` suppresses install entirely** per
  [install-criteria]; a manifest that also defines a native counterpart will
  assert installability incorrectly if this field is missed.
- **`display-mode` MQ does not survive deep-link launches in all
  browsers.** Some launchers open the URL in the system browser; the MQ
  then reports `browser`, which is correct but easy to misread as "install
  regressed."

## Sources

- web.dev - Install criteria (Stage 1 gate cells, engagement requirement) -
  [install-criteria].
- web.dev - Learn PWA: Installation (per-platform paths, WebAPK, iOS
  Share-menu flow, `apple-touch-icon` requirement) - [learn-pwa].
- web.dev - Customize the install experience (Stage 2 handshake) -
  [customize-install].
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall