Automated Testing for Progressive Web Apps¶

// Pure caching logic. No reference to `self` or the global `caches`, so it
// runs unchanged in a service worker, in Node and in a browser test runner.

/**
 * Network-first with a timeout, falling back to the cache.
 * @param {Request} request
 * @param {object} deps
 * @param {CacheStorage} deps.cacheStorage
 * @param {typeof fetch} deps.fetchImpl
 * @param {string} deps.cacheName
 * @param {number} [deps.timeoutMs]
 * @returns {Promise<Response>}
 */
export async function networkFirst(request, { cacheStorage, fetchImpl, cacheName, timeoutMs = 3000 }) {
  const cache = await cacheStorage.open(cacheName);
  const controller = new AbortController();
  let timer;
  const timeout = new Promise((_, reject) => {
    timer = setTimeout(() => {
      controller.abort(); // (1)!
      reject(new Error('network-timeout'));
    }, timeoutMs);
  });

  try {
    const response = await Promise.race([
      fetchImpl(request, { signal: controller.signal }),
      timeout,
    ]);
    // Cache only successful responses we can read. "default" is the type of
    // a constructed Response (unit tests); real fetches are basic or cors.
    if (response.ok && ['basic', 'cors', 'default'].includes(response.type)) {
      await cache.put(request, response.clone()); // (2)!
    }
    return response;
  } catch (error) {
    const cached = await cache.match(request);
    if (cached) return cached;
    throw error;
  } finally {
    clearTimeout(timer);
  }
}

/**
 * Decide which strategy a request gets. Returning null means "let the
 * browser handle it" (no respondWith call).
 * @param {Request} request
 * @param {string} origin the service worker's origin
 */
export function routeFor(request, origin) {
  if (request.method !== 'GET') return null;
  const url = new URL(request.url);
  if (url.origin !== origin) return null;
  if (request.mode === 'navigate') return 'page';
  if (url.pathname.startsWith('/api/')) return 'api';
  if (/\.(?:js|css|woff2|png|svg|webp)$/.test(url.pathname)) return 'static';
  return null;
}

import { networkFirst, routeFor } from './strategies.js';

export const VERSION = '2026-09-25';
export const PRECACHE = `precache-${VERSION}`;
export const RUNTIME = 'runtime';
export const PRECACHE_URLS = ['/', '/offline.html', '/app.css', '/app.js'];

/**
 * Wires every event listener onto `scope`. In production `scope` is `self`;
 * in unit tests it is a plain EventTarget with fakes attached.
 * @param {ServiceWorkerGlobalScope} scope
 */
export function registerHandlers(scope) {
  scope.addEventListener('install', (event) => {
    event.waitUntil(
      scope.caches.open(PRECACHE).then((cache) => cache.addAll(PRECACHE_URLS)),
    );
  });

  scope.addEventListener('activate', (event) => {
    event.waitUntil((async () => {
      const keep = new Set([PRECACHE, RUNTIME]);
      for (const key of await scope.caches.keys()) {
        if (!keep.has(key)) await scope.caches.delete(key);
      }
      await scope.clients.claim();
    })());
  });

  scope.addEventListener('message', (event) => {
    if (event.data?.type === 'SKIP_WAITING') scope.skipWaiting();
  });

  scope.addEventListener('fetch', (event) => {
    const route = routeFor(event.request, scope.location.origin);
    if (route === null) return; // fall through to the network

    // Bind fetch: calling it as a method of `deps` would throw "Illegal invocation".
    const deps = { cacheStorage: scope.caches, fetchImpl: scope.fetch.bind(scope), cacheName: RUNTIME };

    if (route === 'page') {
      event.respondWith(
        networkFirst(event.request, { ...deps, timeoutMs: 4000 })
          .catch(async () => (await scope.caches.match('/offline.html')) ?? Response.error()),
      );
    } else if (route === 'api') {
      event.respondWith(networkFirst(event.request, { ...deps, timeoutMs: 5000 }));
    } else {
      event.respondWith(
        scope.caches.match(event.request).then((hit) => hit ?? scope.fetch(event.request)),
      );
    }
  });
}

// Module service worker entry point: register with { type: 'module' }.
import { registerHandlers } from './handlers.js';

registerHandlers(self);

// Minimal, spec-shaped fakes for the parts of the service worker global
// scope the handlers use. Keep them small: they exist to make assertions
// possible, not to re-implement the platform.

export class FakeCache {
  #entries = new Map(); // url -> Response
  async match(request) {
    const url = typeof request === 'string' ? new URL(request, 'https://app.test').href : request.url;
    return this.#entries.get(url)?.clone();
  }
  async put(request, response) {
    const url = typeof request === 'string' ? new URL(request, 'https://app.test').href : request.url;
    // Mirror Cache.put(): a used body cannot be stored.
    if (response.bodyUsed) throw new TypeError('Response body is already used');
    this.#entries.set(url, response);
  }
  async addAll(urls) {
    for (const u of urls) this.#entries.set(new URL(u, 'https://app.test').href, new Response(`precached ${u}`));
  }
  async keys() { return [...this.#entries.keys()].map((u) => new Request(u)); }
}

export class FakeCacheStorage {
  #caches = new Map();
  async open(name) {
    if (!this.#caches.has(name)) this.#caches.set(name, new FakeCache());
    return this.#caches.get(name);
  }
  async has(name) { return this.#caches.has(name); }
  async delete(name) { return this.#caches.delete(name); }
  async keys() { return [...this.#caches.keys()]; }
  async match(request) {
    for (const cache of this.#caches.values()) {
      const hit = await cache.match(request);
      if (hit) return hit;
    }
    return undefined;
  }
}

export class FakeExtendableEvent extends Event {
  #promises = [];
  waitUntil(promise) { this.#promises.push(Promise.resolve(promise)); }
  // Resolves when every waitUntil() promise settles; rejects like the
  // browser would treat a failed install.
  settled() { return Promise.all(this.#promises); }
}

export class FakeFetchEvent extends FakeExtendableEvent {
  #response = null;
  constructor(request) { super('fetch'); this.request = request; }
  respondWith(promise) {
    if (this.#response) throw new DOMException('respondWith() already called', 'InvalidStateError');
    this.#response = Promise.resolve(promise);
  }
  get handled() { return this.#response !== null; }
  response() { return this.#response; }
}

export class FakeMessageEvent extends FakeExtendableEvent {
  constructor(data) { super('message'); this.data = data; }
}

/** Builds an EventTarget that looks enough like ServiceWorkerGlobalScope. */
export function createScope({ fetchImpl } = {}) {
  const scope = new EventTarget();
  scope.caches = new FakeCacheStorage();
  scope.location = new URL('https://app.test/sw.js');
  scope.fetch = fetchImpl ?? (async () => { throw new TypeError('Failed to fetch'); });
  scope.clients = { claimed: false, async claim() { this.claimed = true; } };
  scope.skipWaitingCalls = 0;
  scope.skipWaiting = async () => { scope.skipWaitingCalls += 1; };
  return scope;
}

/** Builds a navigation Request; Node's Request refuses mode: 'navigate'. */
export function navigationRequest(url) {
  const request = new Request(url);
  Object.defineProperty(request, 'mode', { value: 'navigate' });
  return request;
}

import { test, describe, mock } from 'node:test';
import assert from 'node:assert/strict';
import { networkFirst, routeFor } from '../src/sw/strategies.js';
import { FakeCacheStorage } from './fakes.js';

const ORIGIN = 'https://app.test';

describe('routeFor', () => {
  test('ignores non-GET and cross-origin requests', () => {
    assert.equal(routeFor(new Request(`${ORIGIN}/api/x`, { method: 'POST' }), ORIGIN), null);
    assert.equal(routeFor(new Request('https://cdn.example/lib.js'), ORIGIN), null);
  });
  test('classifies API and static requests', () => {
    assert.equal(routeFor(new Request(`${ORIGIN}/api/items`), ORIGIN), 'api');
    assert.equal(routeFor(new Request(`${ORIGIN}/assets/app.3f9a.js`), ORIGIN), 'static');
  });
});

describe('networkFirst', () => {
  test('stores successful network responses', async () => {
    const cacheStorage = new FakeCacheStorage();
    const fetchImpl = mock.fn(async () => new Response('fresh', { status: 200 }));
    const res = await networkFirst(new Request(`${ORIGIN}/api/items`), { cacheStorage, fetchImpl, cacheName: 'rt' });
    assert.equal(await res.text(), 'fresh');
    const cached = await (await cacheStorage.open('rt')).match(new Request(`${ORIGIN}/api/items`));
    assert.equal(await cached.text(), 'fresh');
    assert.equal(fetchImpl.mock.callCount(), 1);
  });

  test('does not cache error responses', async () => {
    const cacheStorage = new FakeCacheStorage();
    const fetchImpl = async () => new Response('nope', { status: 503 });
    const res = await networkFirst(new Request(`${ORIGIN}/api/items`), { cacheStorage, fetchImpl, cacheName: 'rt' });
    assert.equal(res.status, 503);
    assert.equal(await (await cacheStorage.open('rt')).match(new Request(`${ORIGIN}/api/items`)), undefined);
  });

  test('falls back to the cache when the network fails', async () => {
    const cacheStorage = new FakeCacheStorage();
    await (await cacheStorage.open('rt')).put(new Request(`${ORIGIN}/api/items`), new Response('stale'));
    const fetchImpl = async () => { throw new TypeError('Failed to fetch'); };
    const res = await networkFirst(new Request(`${ORIGIN}/api/items`), { cacheStorage, fetchImpl, cacheName: 'rt' });
    assert.equal(await res.text(), 'stale');
  });

  test('times out slow networks using fake timers', async () => {
    mock.timers.enable({ apis: ['setTimeout'] });
    try {
      const cacheStorage = new FakeCacheStorage();
      await (await cacheStorage.open('rt')).put(new Request(`${ORIGIN}/api/items`), new Response('stale'));
      let signal;
      const fetchImpl = (_req, init) => { signal = init.signal; return new Promise(() => {}); }; // never settles
      const pending = networkFirst(new Request(`${ORIGIN}/api/items`), { cacheStorage, fetchImpl, cacheName: 'rt', timeoutMs: 3000 });
      // Let networkFirst reach its await on Promise.race before advancing time.
      await new Promise((resolve) => setImmediate(resolve));
      mock.timers.tick(3000);
      const res = await pending;
      assert.equal(await res.text(), 'stale');
      assert.equal(signal.aborted, true, 'the in-flight fetch must be aborted');
    } finally {
      mock.timers.reset();
    }
  });

  test('rethrows when there is no cached copy', async () => {
    const cacheStorage = new FakeCacheStorage();
    const fetchImpl = async () => { throw new TypeError('Failed to fetch'); };
    await assert.rejects(
      networkFirst(new Request(`${ORIGIN}/api/items`), { cacheStorage, fetchImpl, cacheName: 'rt' }),
      TypeError,
    );
  });
});

import { test, describe } from 'node:test';
import assert from 'node:assert/strict';
import { registerHandlers, PRECACHE, PRECACHE_URLS } from '../src/sw/handlers.js';
import {
  createScope, FakeExtendableEvent, FakeFetchEvent, FakeMessageEvent, navigationRequest,
} from './fakes.js';

async function installAndActivate(scope) {
  const install = new FakeExtendableEvent('install');
  scope.dispatchEvent(install);
  await install.settled();
  const activate = new FakeExtendableEvent('activate');
  scope.dispatchEvent(activate);
  await activate.settled();
}

describe('service worker handlers', () => {
  test('install precaches the app shell', async () => {
    const scope = createScope();
    registerHandlers(scope);
    const install = new FakeExtendableEvent('install');
    scope.dispatchEvent(install);
    await install.settled();
    const cache = await scope.caches.open(PRECACHE);
    assert.equal((await cache.keys()).length, PRECACHE_URLS.length);
  });

  test('activate deletes old caches and claims clients', async () => {
    const scope = createScope();
    registerHandlers(scope);
    await scope.caches.open('precache-2026-01-01');
    await installAndActivate(scope);
    assert.deepEqual((await scope.caches.keys()).sort(), [PRECACHE]);
    assert.equal(scope.clients.claimed, true);
  });

  test('offline navigations get the offline page', async () => {
    const scope = createScope(); // default fetch always rejects
    registerHandlers(scope);
    await installAndActivate(scope);
    const event = new FakeFetchEvent(navigationRequest('https://app.test/settings'));
    scope.dispatchEvent(event);
    assert.equal(event.handled, true);
    const res = await event.response();
    assert.equal(await res.text(), 'precached /offline.html');
  });

  test('cross-origin requests are left to the browser', () => {
    const scope = createScope();
    registerHandlers(scope);
    const event = new FakeFetchEvent(new Request('https://fonts.example/x.woff2'));
    scope.dispatchEvent(event);
    assert.equal(event.handled, false);
  });

  test('SKIP_WAITING message calls skipWaiting()', () => {
    const scope = createScope();
    registerHandlers(scope);
    scope.dispatchEvent(new FakeMessageEvent({ type: 'SKIP_WAITING' }));
    scope.dispatchEvent(new FakeMessageEvent({ type: 'SOMETHING_ELSE' }));
    assert.equal(scope.skipWaitingCalls, 1);
  });
});

// A tiny static server for the production build, with test-only controls.
// Each Playwright worker starts its own instance on a random port, so tests
// that take the "network" down never affect each other.
import http from 'node:http';
import { readFile } from 'node:fs/promises';
import path from 'node:path';

const TYPES = {
  '.html': 'text/html; charset=utf-8',
  '.js': 'text/javascript; charset=utf-8',
  '.css': 'text/css; charset=utf-8',
  '.json': 'application/json',
  '.webmanifest': 'application/manifest+json',
  '.png': 'image/png',
  '.svg': 'image/svg+xml',
  '.woff2': 'font/woff2',
};

/**
 * @param {{ root: string, port?: number }} options
 */
export async function startServer({ root, port = 0 }) {
  const rootDir = path.resolve(root);
  let networkDown = false;
  /** @type {Map<string, (body: string) => string>} */
  const patches = new Map();
  /** @type {Array<{ method: string, path: string, serviceWorker: boolean }>} */
  const log = [];

  const server = http.createServer(async (req, res) => {
    // Simulate a dead network: drop the TCP connection without a response.
    // Browsers surface this as a network error (TypeError in fetch()).
    if (networkDown) {
      req.socket.destroy();
      return;
    }

    const url = new URL(req.url, 'http://localhost');
    log.push({
      method: req.method,
      path: url.pathname,
      // The Service Workers spec adds "Service-Worker: script" to script fetches.
      serviceWorker: req.headers['service-worker'] === 'script',
    });

    if (url.pathname.startsWith('/api/')) {
      res.setHeader('content-type', 'application/json');
      res.end(JSON.stringify({ path: url.pathname, at: Date.now() }));
      return;
    }

    const file = url.pathname.endsWith('/') ? `${url.pathname}index.html` : url.pathname;
    const fullPath = path.join(rootDir, path.normalize(file));
    // Compare with a trailing separator so "/srv/dist-old" can't pass as "/srv/dist".
    if (!fullPath.startsWith(rootDir + path.sep)) {
      res.writeHead(403).end();
      return;
    }

    try {
      let body = await readFile(fullPath);
      const patch = patches.get(url.pathname);
      if (patch) body = Buffer.from(patch(body.toString('utf8')));
      res.setHeader('content-type', TYPES[path.extname(fullPath)] ?? 'application/octet-stream');
      // The SW script must never be served from the HTTP cache in tests.
      if (url.pathname === '/sw.js') res.setHeader('cache-control', 'no-cache');
      res.end(body);
    } catch {
      res.writeHead(404, { 'content-type': 'text/plain' }).end('Not found');
    }
  });

  // No host argument: listen on all interfaces so "localhost" works over IPv4 and IPv6.
  await new Promise((resolve) => server.listen(port, resolve));
  const { port: actualPort } = /** @type {import('node:net').AddressInfo} */ (server.address());

  return {
    // Use "localhost", not 127.0.0.1: both are secure contexts, but they are
    // different origins, and the SW registration belongs to one of them.
    url: `http://localhost:${actualPort}`,
    log,
    setNetworkDown(value) { networkDown = value; },
    /** Rewrite a file on the fly, e.g. to ship a "new" service worker. */
    patch(pathname, transform) { patches.set(pathname, transform); },
    reset() { networkDown = false; patches.clear(); log.length = 0; },
    close() {
      server.closeAllConnections();
      return new Promise((resolve) => server.close(resolve));
    },
  };
}

import { test as base, expect } from '@playwright/test';
import { startServer } from './server.mjs';

/**
 * Resolves once the page is controlled by an *activated* service worker.
 * navigator.serviceWorker.ready resolves when the registration has an active
 * worker, which can happen before clients.claim() makes it the controller,
 * so check the controller too.
 * @param {import('@playwright/test').Page} page
 */
export async function waitForServiceWorkerControl(page, { timeout = 10_000 } = {}) {
  await page.waitForFunction(async () => {
    if (!('serviceWorker' in navigator)) throw new Error('No service worker support');
    const registration = await navigator.serviceWorker.ready;
    return registration.active?.state === 'activated' && navigator.serviceWorker.controller !== null;
  }, undefined, { timeout, polling: 100 });
}

export const test = base.extend({
  // One server per worker process; torn down when the worker exits.
  app: [async ({}, use) => {
    const app = await startServer({ root: process.env.DIST_DIR ?? 'dist' });
    await use(app);
    await app.close();
  }, { scope: 'worker' }],

  // Point relative page.goto('/') calls at this worker's server.
  baseURL: async ({ app }, use) => {
    await use(app.url);
  },

  // Restore the server after every test, even when the test fails midway.
  resetApp: [async ({ app }, use) => {
    await use();
    app.reset();
  }, { auto: true }],

  // A page that has loaded "/" and is already under SW control.
  controlledPage: async ({ page }, use) => {
    await page.goto('/');
    await waitForServiceWorkerControl(page);
    await use(page);
  },
});

export { expect };

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  // Tests are isolated per worker (own server, own port), so parallel is safe.
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: process.env.CI ? [['html', { open: 'never' }], ['github']] : 'list',
  use: {
    trace: 'retain-on-failure',
    // Explicit, even though 'allow' is the default: these tests are about SWs.
    serviceWorkers: 'allow',
  },
  projects: [
    // channel: 'chromium' runs the full browser in new headless mode instead of
    // the headless shell, which is required for notification tests (see below).
    { name: 'chromium', use: { ...devices['Desktop Chrome'], channel: 'chromium' } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

const VERSION = 'v1';
const PRECACHE = `precache-${VERSION}`;
const RUNTIME = 'runtime';
const PRECACHE_URLS = ['/', '/offline.html', '/app.js', '/manifest.webmanifest'];

self.addEventListener('install', (event) => {
  event.waitUntil(caches.open(PRECACHE).then((c) => c.addAll(PRECACHE_URLS)));
});

self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    for (const k of await caches.keys()) if (k !== PRECACHE && k !== RUNTIME) await caches.delete(k);
    await self.clients.claim();
  })());
});

self.addEventListener('message', (event) => {
  if (event.data?.type === 'SKIP_WAITING') self.skipWaiting();
  if (event.data?.type === 'GET_VERSION') event.source?.postMessage({ type: 'VERSION', version: VERSION });
});

self.addEventListener('fetch', (event) => {
  const { request } = event;
  const url = new URL(request.url);
  if (request.method !== 'GET' || url.origin !== location.origin) return;

  if (request.mode === 'navigate') {
    event.respondWith((async () => {
      try { return await fetch(request); }
      catch {
        return (await caches.match(request, { ignoreSearch: true }))
          ?? (await caches.match('/offline.html'));
      }
    })());
    return;
  }

  if (url.pathname.startsWith('/api/')) {
    event.respondWith((async () => {
      try {
        const res = await fetch(request);
        if (res.ok) {
          // Clone synchronously, before the page starts reading the body, and
          // keep the worker alive until the write finishes.
          const copy = res.clone();
          event.waitUntil(caches.open(RUNTIME).then((c) => c.put(request, copy)));
        }
        return res;
      } catch {
        return (await caches.match(request)) ?? Response.json({ error: 'offline' }, { status: 503 });
      }
    })());
    return;
  }

  event.respondWith(caches.match(request).then((hit) => hit ?? fetch(request)));
});

self.addEventListener('push', (event) => {
  let payload = {};
  try {
    payload = event.data?.json() ?? {};
  } catch {
    // Non-JSON payload: show it as the body instead of throwing.
    payload = { body: event.data?.text() ?? '' };
  }
  event.waitUntil(self.registration.showNotification(payload.title ?? 'Update', {
    body: payload.body ?? '',
    tag: payload.tag ?? 'default',
    data: { url: payload.url ?? '/' },
  }));
});

self.addEventListener('sync', (event) => {
  if (event.tag === 'outbox') event.waitUntil(fetch('/api/outbox/flush', { method: 'POST' }));
});

const reloadButton = document.getElementById('reload');

if ('serviceWorker' in navigator) {
  // Only reload on controllerchange if a worker was already in charge.
  // Without this guard, clients.claim() on the very first install reloads the page.
  const hadController = navigator.serviceWorker.controller !== null;
  const reg = await navigator.serviceWorker.register('/sw.js');

  if (reg) { // undefined when Playwright blocks service workers
    const showUpdate = () => { reloadButton.hidden = false; };
    if (reg.waiting && hadController) showUpdate();
    reg.addEventListener('updatefound', () => {
      const w = reg.installing;
      w?.addEventListener('statechange', () => {
        if (w.state === 'installed' && navigator.serviceWorker.controller) showUpdate();
      });
    });
    reloadButton.addEventListener('click', () => reg.waiting?.postMessage({ type: 'SKIP_WAITING' }));

    let reloading = false;
    navigator.serviceWorker.addEventListener('controllerchange', () => {
      if (!hadController || reloading) return;
      reloading = true;
      location.reload();
    });
  }
}

import { test, expect, waitForServiceWorkerControl } from './support/fixtures.mjs';

test.describe('registration and precache', () => {
  test('registers, activates and controls the page', async ({ page, app }) => {
    await page.goto('/');
    await waitForServiceWorkerControl(page);

    const info = await page.evaluate(async () => {
      const reg = await navigator.serviceWorker.getRegistration();
      return {
        scope: reg.scope,
        script: navigator.serviceWorker.controller.scriptURL,
        state: reg.active.state,
      };
    });
    expect(info).toEqual({ scope: `${app.url}/`, script: `${app.url}/sw.js`, state: 'activated' });

    // The browser marks the SW script request with "Service-Worker: script".
    expect(app.log).toContainEqual({ method: 'GET', path: '/sw.js', serviceWorker: true });
  });

  test('precaches the app shell', async ({ controlledPage: page }) => {
    // Cache Storage is exposed to windows too, so this works in every engine.
    const cached = await page.evaluate(async () => {
      const names = await caches.keys();
      const precache = names.find((n) => n.startsWith('precache-'));
      const requests = await (await caches.open(precache)).keys();
      return requests.map((r) => new URL(r.url).pathname).sort();
    });
    expect(cached).toEqual(['/', '/app.js', '/manifest.webmanifest', '/offline.html']);
  });

  test('can evaluate inside the service worker (Chromium only)', async ({ context, page, browserName }) => {
    test.skip(browserName !== 'chromium', 'context.serviceWorkers() is Chromium-only');
    // Start listening before navigation: the event fires while the SW is still installing.
    const swPromise = context.waitForEvent('serviceworker');
    await page.goto('/');
    const worker = await swPromise;
    await waitForServiceWorkerControl(page);

    expect(context.serviceWorkers()).toContain(worker);
    const scope = await worker.evaluate(() => ({
      state: self.serviceWorker.state,
      scope: self.registration.scope,
    }));
    expect(scope.state).toBe('activated');
  });
});