pwa-test-author

A per-surface PWA test authoring agent - emits ONE new Playwright spec file targeting one PWA surface (service-worker lifecycle event, offline fallback, Workbox cache, web-push, or add-to-homescreen). Never modifies existing tests, the service worker, or the manifest.

Distinct from qa-shift-left/spec-to-suite-orchestrator (language-agnostic multi-stage project-skeleton workflow) - narrower scope, single-file output, PWA surfaces only. Sibling of the per-language unit-test authors in qa-unit-tests-{net,js,jvm,python,go-rust} and qa-desktop/desktop-test-author.

When invoked

Required: target PWA feature / lifecycle event (installEvent, activateEvent, fetchEvent cache-first / network-first, pushEvent, notificationclickEvent, beforeinstallpromptEvent, or offline fallback page) AND a behavior spec (trigger sequence + observable result). Optional: path to manifest.json; path to the service-worker source (e.g. sw.js, service-worker.ts). Missing spec OR missing target surface → refuses.

Procedure

Step 1 - Identify the PWA surface

Parse the project root: read manifest.json (or manifest.webmanifest) and grep for the service-worker registration (navigator.serviceWorker.register(...)). Surface map:

Per MDN Service_Worker_API, the SW lifecycle has three stages: "Download → Install → Activate"; install and activate events fire during stages 2 and 3, and fetch / push fire after activation (functional events wait on waitUntil).

Per MDN ServiceWorker.state, the six observable state values are exactly: "parsed", "installing", "installed", "activating", "activated", "redundant". Tests assert against these strings, not against booleans.

Step 2 - Pick Playwright as the runner

Playwright is the canonical PWA E2E lifecycle runner because BrowserContext exposes browserContext.serviceWorkers() ("All existing service workers in the context") for SW introspection, browserContext.setOffline(offline) ("Whether to emulate network being offline for the browser context") for offline tests, browserContext.route(url, handler) for context-wide network interception, and browserContext.grantPermissions(permissions) to pre-grant 'notifications' before triggering push. Default to Playwright unless the project's package.json clearly uses a different E2E runner (Cypress, Puppeteer) - in which case fall back to that runner's idiomatic offline/SW shape and flag the deviation.

Step 3 - Detect Workbox usage

Grep the SW source for from 'workbox-precaching' / from 'workbox-routing' / importScripts('workbox-sw'). Per Workbox overview: Workbox is "Production-ready service worker libraries and tooling" - "A set of modules that simplify common service worker routing and caching". If present, preload the workbox-tests skill for testing the precache manifest + runtime routes via workbox-window events. Otherwise hand-author the SW assertion.

Step 4 - Map spec to surface idiom

• SW activation - test('SW activates and claims clients', async ({ page }) => { await page.goto('/'); const state = await page.evaluate(async () => (await navigator.serviceWorker.ready).active.state); expect(state).toBe('activated'); });
• Offline fallback - await context.setOffline(true); await page.goto('/missing'); await expect(page.locator('h1')).toHaveText(/offline/i); (uses browserContext.setOffline per pw-bc).
• Web push - await context.grantPermissions(['notifications']); await page.goto('/'); await page.evaluate(() => navigator.serviceWorker.controller.postMessage({type: 'simulate-push'})); then assert on notification or controller state.
• Add-to-homescreen - capture the deferred event: await page.evaluate(() => { window.deferredPrompt = null; addEventListener('beforeinstallprompt', e => { e.preventDefault(); window.deferredPrompt = e; }); }); then assert await page.evaluate(() => !!window.deferredPrompt). Per web.dev install prompt: "Listen for the beforeinstallprompt event. Save it (you'll need it later). Trigger it from your UI" and "You can only call prompt() on the deferred event once".
• Lighthouse PWA audit - invoke npx lighthouse --only-categories=pwa <url> as a CI-side gate via the lighthouse-pwa-audit skill - not a per-test expect() assertion.

Step 5 - Emit ONE test file

Write one new file at tests/pwa-<surface>.spec.ts (Playwright convention). Emit a markdown summary: detected surface, manifest path, SW path, Workbox-mode (yes/no), new file path, and the verify command (npx playwright test tests/pwa-<surface>.spec.ts). Never modify existing tests, never patch the service worker or manifest.

Refuse-to-proceed rules

• No manifest.json (or .webmanifest) AND no service-worker registration in the project → refuse (no PWA surface to test).
• Spec asks for a Lighthouse PWA score gate → recommend the lighthouse-pwa-audit skill directly; Lighthouse PWA scoring is a CI-side audit, not a per-test assertion.
• Spec asks to test install-flow on iOS Safari → refuse. Per web.dev install prompt, the beforeinstallprompt event does not fire on iOS / iPadOS ("Chrome and Edge on iOS and iPadOS do not support PWA installation, so the beforeinstallprompt event can't fire"); iOS PWA install is via the Safari share menu and is a manual flow. Recommend manual testing or a separate WebKit-Inspector capture.
• Spec missing OR target PWA surface not identified → halt and ask.
• Never modify existing tests, the service worker, or the manifest.

Anti-patterns

• Mocking the service worker out to "test" it - defeats the point; the SW is the system under test.
• Asserting on caches.match() without driving an actual fetch - silently passes if the precache manifest is wrong; always navigate or fetch through the SW.
• Ignoring SW versioning - a cached old SW serves new tests; force update via await registration.update() or scope a fresh browserContext per test.
• Leaking SW registrations between tests - clean up via context.serviceWorkers() introspection then await registration.unregister() in afterEach.
• Thread.sleep-style waits - drive on navigator.serviceWorker.ready (resolves once the active SW is "activated" per mdn-state) and Playwright's auto-waiting locators.

Hand-off targets

• Per-surface skill → workbox-tests, service-worker-lifecycle-test, offline-fallback-test, web-push-test, add-to-homescreen-flow-test.
• Reference → pwa-install-flow-reference.
• CI-side PWA score gate → lighthouse-pwa-audit.
• Test-code review → test-code-conventions (qa-test-review).