service-worker-lifecycle-tests

Overview

A service worker moves through six formal states per the W3C spec sw-spec: "parsed, installing, installed, activating, activated, redundant". Most "PWA broke after deploy" bugs are lifecycle bugs - a v2 SW stuck in installed (waiting) behind a v1 that won't release control; a skipWaiting() that activates v2 but leaves v1's caches alive; a Clients.claim() race against a hot- reload that flips the navigator.serviceWorker.controller mid-fetch.

This skill produces the per-extension lifecycle spec - a Playwright file with one test per transition cell plus a worked v1 → v2 upgrade-path test. It is distinct from service-worker-tests, which covers general context.serviceWorkers() Playwright patterns and per-cache-strategy assertions. This builder is laser-focused on the state machine.

Composes with:

• pwa-install-flow-reference - the Stage 1 service-worker-registered prerequisite, which this builder takes as input (assumes registration already works).
• workbox-tests - the workbox-window event vocabulary (installed, waiting, controlling, activated, redundant) is the page-side observable for the same state machine asserted here from the SW side.

When to use

• New PWA - author the baseline lifecycle spec before the team ships any SW logic that mutates state.
• Upgrade-path regression - a deploy left users on v1 because v2's skipWaiting() was missing; emit the per-transition test cells to catch it next time.
• "Stale UI after deploy" reports - the test cells localize whether the bug is skipWaiting, Clients.claim, or cache invalidation.
• Migrating from Workbox workbox-window to a hand-rolled registration helper - assert the same five events still fire.

Workflow

Step 1 - Capture the SW under test

Read the SW file the team ships and record three facts:

# Inventory
grep -E "skipWaiting|clients\.claim" src/sw.ts > sw-lifecycle-inventory.txt

Per mdn-sw, skipWaiting() activates sooner and Clients.claim() claims existing pages. The combination matters - skipWaiting without claim activates the new SW but leaves current tabs uncontrolled until reload.

Step 2 - Test: state machine entry - fresh install

On first access to a SW-controlled page the worker downloads and installs immediately per mdn-sw. The first-install test:

import { test, expect } from '@playwright/test';

test('first install transitions parsed → installing → installed → activating → activated', async ({ context, page }) => {
  await page.goto('https://localhost:3000/');

  // Capture statechange events as soon as the SW is reachable
  const observed = await page.evaluate(() => new Promise<string[]>((resolve) => {
    const states: string[] = [];
    navigator.serviceWorker.register('/sw.js').then(reg => {
      const w = reg.installing ?? reg.waiting ?? reg.active;
      if (!w) { resolve(states); return; }
      states.push(w.state);
      w.addEventListener('statechange', () => {
        states.push(w.state);
        if (w.state === 'activated' || w.state === 'redundant') resolve(states);
      });
    });
    // Hard timeout
    setTimeout(() => resolve(states), 10_000);
  }));

  // Per sw-spec, the formal enum is parsed / installing / installed / activating / activated / redundant.
  // Expect at minimum installed and activated in the trace.
  expect(observed).toContain('installed');
  expect(observed).toContain('activated');
});

statechange fires on the corresponding ServiceWorker object whenever its state attribute changes per sw-spec.

Step 3 - Test: event.waitUntil extends the install phase

Per mdn-sw, waitUntil() on an install / activate event holds functional events (fetch, push) until its promise resolves - so a slow precache keeps the SW in installing.

test('SW install with slow precache stays in installing until waitUntil resolves', async ({ page, context }) => {
  await page.goto('https://localhost:3000/');

  const phase = await page.evaluate(() => new Promise<string>((resolve) => {
    navigator.serviceWorker.register('/sw-slow-install.js').then(reg => {
      const w = reg.installing;
      if (!w) { resolve('no installing'); return; }
      // Sample state at ~500ms - the slow install should still be 'installing'
      setTimeout(() => resolve(w.state), 500);
    });
  }));

  expect(['installing', 'installed']).toContain(phase);
});

This requires a slow-install SW fixture under tests/fixtures/sw-slow-install.js that calls event.waitUntil(new Promise(r => setTimeout(r, 2000))) inside its install handler.

Step 4 - Test: skipWaiting() collapses the waiting phase

Per mdn-skipwaiting, skipWaiting() "causes the waiting service worker to become the active service worker." Test the transition:

test('skipWaiting() makes v2 active without page reload', async ({ context, page }) => {
  // Load v1
  await page.goto('https://localhost:3000/?sw-version=1');
  await page.waitForFunction(() => navigator.serviceWorker.controller !== null);

  // Deploy v2 (the test server flips the SW response based on a query param header)
  await page.evaluate(async () => {
    const reg = await navigator.serviceWorker.getRegistration();
    await reg!.update();
  });

  const waitingThenActive = await page.evaluate(() => new Promise<string>(async (resolve) => {
    const reg = await navigator.serviceWorker.getRegistration();
    // v2 should land in waiting…
    if (reg!.waiting) {
      // …then transition to activating when skipWaiting() fires
      reg!.waiting.addEventListener('statechange', e => {
        resolve((e.target as ServiceWorker).state);
      });
    } else {
      resolve(reg!.active?.state ?? 'unknown');
    }
  }));

  // After skipWaiting(), v2 reaches activated without manual reload
  expect(['activating', 'activated']).toContain(waitingThenActive);
});

If the SW under test does not call skipWaiting(), this test must assert v2 stays in installed/waiting until all v1-controlled tabs close - flip the expectation accordingly.

Step 5 - Test: Clients.claim() flips the controller

Per mdn-claim, Clients.claim() lets an active SW set itself as the controller for all in-scope clients.

test('clients.claim() makes v2 control the page mid-session', async ({ page, context }) => {
  // v1 is active and controlling
  await page.goto('https://localhost:3000/?sw-version=1');
  const v1ScriptURL = await page.evaluate(() => navigator.serviceWorker.controller?.scriptURL);
  expect(v1ScriptURL).toMatch(/sw-v1/);

  // Trigger v2 deploy + claim
  await page.evaluate(async () => {
    const reg = await navigator.serviceWorker.getRegistration();
    await reg!.update();
  });

  // After claim() in v2's activate handler, controller flips
  const v2ScriptURL = await page.waitForFunction(() => {
    const c = navigator.serviceWorker.controller;
    return c && c.scriptURL.includes('sw-v2') ? c.scriptURL : null;
  });
  expect(await v2ScriptURL.jsonValue()).toMatch(/sw-v2/);
});

Per mdn-sw, skipWaiting() and claim() together force-activate the new SW; one without the other leaves a gap (see Step 1).

Step 6 - Test: old SW transitions to redundant

Per sw-spec, redundant is the terminal state - the old SW enters it when superseded. The transition is the cleanup signal the activate handler typically uses to drop old caches:

test('old SW transitions to redundant after v2 activates', async ({ context, page }) => {
  await page.goto('https://localhost:3000/?sw-version=1');

  const v1 = await page.evaluate(async () => {
    const reg = await navigator.serviceWorker.getRegistration();
    return reg!.active;
  });

  const finalState = await page.evaluate(() => new Promise<string>(async (resolve) => {
    const reg = await navigator.serviceWorker.getRegistration();
    const oldSW = reg!.active;
    if (!oldSW) { resolve('no old'); return; }
    oldSW.addEventListener('statechange', () => {
      if (oldSW.state === 'redundant') resolve('redundant');
    });
    // Trigger v2 update path
    await reg!.update();
    setTimeout(() => resolve(oldSW.state), 8_000);
  }));

  expect(finalState).toBe('redundant');
});

Step 7 - Test: navigator.serviceWorker.controller semantics

Per mdn-sw, navigator.serviceWorker.controller returns the SW controlling the current page, or null if no SW controls it (e.g. hard-reload, force-bypass, or fresh first load before activation). Test the boundary cases:

test('controller is null on first hard-reload, set after activation', async ({ page, context }) => {
  await page.goto('https://localhost:3000/');

  // First load: controller may be null until claim() runs (or until next navigation)
  const initialController = await page.evaluate(() => navigator.serviceWorker.controller?.scriptURL ?? null);
  // Either null (no claim) or set (claim called in activate)

  // After a reload, the SW must be controlling
  await page.reload();
  const reloadedController = await page.evaluate(() => navigator.serviceWorker.controller?.scriptURL);
  expect(reloadedController).toBeTruthy();
});

Per mdn-sw: a hard-reload (Ctrl+Shift+R) bypasses the SW - controller is null for that page even if an SW is registered. Playwright's page.reload({ waitUntil: 'networkidle' }) is a soft reload; the SW controls it.

Step 8 - Test: updatefound event on registration

Per mdn-sw, the registration object fires updatefound when a new SW is in the installing state. This is the canonical "deploy detected" event for "Update available" banners:

test('updatefound fires when a new SW is found', async ({ page, context }) => {
  await page.goto('https://localhost:3000/?sw-version=1');

  const found = await page.evaluate(() => new Promise<boolean>(async (resolve) => {
    const reg = await navigator.serviceWorker.getRegistration();
    reg!.addEventListener('updatefound', () => resolve(true));
    await reg!.update();
    setTimeout(() => resolve(false), 5_000);
  }));

  expect(found).toBe(true);
});

Step 9 - Emit the lifecycle spec artifact

Write tests/sw-lifecycle.spec.ts with all eight test cells above, paired with a tests/sw-lifecycle-coverage.yaml matrix mapping each spec to its state-machine cell and reference. The full matrix and the worked v1 -> v2 upgrade-path spec are in references/upgrade-path.md:

# tests/sw-lifecycle-coverage.yaml
matrix:
  fresh_install:
    spec: "first install transitions parsed → installing → installed → activating → activated"
    states: [parsed, installing, installed, activating, activated]
    ref: sw-spec ServiceWorkerState enum
  # waituntil, skipwaiting, claim, redundant, controller_semantics, updatefound

CI gates on every matrix row having at least one passing test.

Worked example: a v1 → v2 upgrade-path test

The full worked tests/sw-upgrade-path.spec.ts for an SW using skipWaiting()

• Clients.claim() is in references/upgrade-path.md. It exercises four state transitions (installed → activating in v2, activated → redundant in v1) plus the cache-cleanup convention. Pair it with the per-transition cells from Steps 2 - 8 for the full lifecycle surface.

Anti-patterns

Limitations

• waitUntil test timing is heuristic. Step 3 samples at 500ms; faster machines may see installed already. Use waitForFunction with a state predicate for production-grade tests.
• controller on first load can be null or set depending on whether the SW calls claim() per mdn-sw; Step 7 covers both branches. Tests that hard-pin to one will flake.
• Cross-tab lifecycle isn't observed by this builder. Two open tabs share the SW registration but each has its own serviceWorker.controller; a full multi-tab assertion needs a second context.newPage().
• Hard-reload (Ctrl+Shift+R) behavior can't be triggered programmatically in Playwright - page.reload() is always soft. Manual smoke covers this cell.
• The push and fetch events that waitUntil gates aren't tested here directly; pair with web-push-tests (push side) and the service-worker-tests cache-strategy tests (fetch side).
• Browser variance. Firefox and WebKit implement the state machine but report statechange with slightly different intermediate samples per sw-spec; the assertions here use toContain to absorb the variance.

References

• W3C Service Worker spec (ServiceWorkerState enum, formal state values, statechange event semantics) - sw-spec.
• MDN Service Worker API (lifecycle prose, waitUntil, skipWaiting + claim pairing, controller semantics) - mdn-sw.
• MDN ServiceWorkerGlobalScope.skipWaiting() - mdn-skipwaiting.
• MDN Clients.claim() - mdn-claim.
• Differentiation: service-worker-tests covers general context.serviceWorkers() + cache-strategy patterns; this skill is the dedicated state-machine spec generator.
• Composes: pwa-install-flow-reference, workbox-tests.
• Sibling builders: offline-fallback-tests, add-to-homescreen-flow-tests.