testdino-hq/playwright-skill / core
playwright-core
VerifiedBattle-tested Playwright patterns for writing and debugging reliable E2E, API, component, visual, accessibility, and security tests. Use when you need locator strategy, assertions, fixtures, network mocking, auth flows, trace debugging, or framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.
service-workers-and-pwa.md
View on GitHub# Service Workers and PWA Testing
> **When to use**: When your application is a Progressive Web App (PWA) or uses service workers for offline support, caching, push notifications, or background sync.
> **Prerequisites**: [core/configuration.md](configuration.md), [core/assertions-and-waiting.md](assertions-and-waiting.md)
## Quick Reference
```typescript
// Service workers require a persistent context — use launchPersistentContext
const context = await chromium.launchPersistentContext(userDataDir, {
baseURL: 'https://localhost:3000',
});
// Enable/disable offline mode
await context.setOffline(true); // Go offline
await context.setOffline(false); // Come back online
// Wait for service worker to register
const sw = await context.waitForEvent('serviceworker');
console.log('SW URL:', sw.url());
```
## Patterns
### Service Worker Registration
**Use when**: You need to verify that your service worker registers successfully, activates, and controls the page.
**Avoid when**: Your app does not use service workers.
Service workers require a persistent browser context because they are tied to a profile. The default `page` fixture uses a temporary context that does not persist service worker registrations across navigations reliably.
**TypeScript**
```typescript
import { test as base, expect, chromium, BrowserContext } from '@playwright/test';
import path from 'path';
import fs from 'fs';
// Create a fixture with a persistent context for SW testing
const test = base.extend<{ swContext: BrowserContext }>({
swContext: async ({}, use) => {
const userDataDir = path.join(__dirname, '.tmp-profile');
const context = await chromium.launchPersistentContext(userDataDir, {
baseURL: 'https://localhost:3000',
});
await use(context);
await context.close();
fs.rmSync(userDataDir, { recursive: true, force: true });
},
});
test('service worker registers and activates', async ({ swContext }) => {
const page = await swContext.newPage();
// Listen for the service worker event
const swPromise = swContext.waitForEvent('serviceworker');
await page.goto('/');
const sw = await swPromise;
expect(sw.url()).toContain('service-worker.js');
// Verify the SW is controlling the page
const isControlled = await page.evaluate(() => {
return navigator.serviceWorker.controller !== null;
});
expect(isControlled).toBe(true);
});
```
**JavaScript**
```javascript
const { test: base, expect, chromium } = require('@playwright/test');
const path = require('path');
const fs = require('fs');
const test = base.extend({
swContext: async ({}, use) => {
const userDataDir = path.join(__dirname, '.tmp-profile');
const context = await chromium.launchPersistentContext(userDataDir, {
baseURL: 'https://localhost:3000',
});
await use(context);
await context.close();
fs.rmSync(userDataDir, { recursive: true, force: true });
},
});
test('service worker registers and activates', async ({ swContext }) => {
const page = await swContext.newPage();
const swPromise = swContext.waitForEvent('serviceworker');
await page.goto('/');
const sw = await swPromise;
expect(sw.url()).toContain('service-worker.js');
const isControlled = await page.evaluate(() => {
return navigator.serviceWorker.controller !== null;
});
expect(isControlled).toBe(true);
});
```
### Offline Mode Testing
**Use when**: Your PWA should work offline -- serving cached pages, showing offline indicators, queuing data for sync.
**Avoid when**: Your app has no offline support.
**TypeScript**
```typescript
import { test, expect } from '@playwright/test';
test('app serves cached page when offline', async ({ swContext }) => {
const page = await swContext.newPage();
// First visit — caches the page and assets
await page.goto('/');
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
// Wait for the service worker to finish caching
await page.evaluate(async () => {
const registration = await navigator.serviceWorker.ready;
// Wait for the SW to be in the 'activated' state
return registration.active?.state === 'activated';
});
// Go offline
await swContext.setOffline(true);
// Reload — should serve from cache
await page.reload();
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
// Verify offline indicator appears
await expect(page.getByText('You are offline')).toBeVisible();
// Come back online
await swContext.setOffline(false);
await expect(page.getByText('You are offline')).toBeHidden();
});
test('form submission queues when offline', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/feedback');
// Ensure SW is active
await page.evaluate(() => navigator.serviceWorker.ready);
// Go offline
await swContext.setOffline(true);
// Submit a form while offline
await page.getByLabel('Feedback').fill('Great product!');
await page.getByRole('button', { name: 'Submit' }).click();
// App should show a "queued" message, not an error
await expect(page.getByText('Saved offline. Will sync when connected.')).toBeVisible();
// Come back online — the queued data should sync
await swContext.setOffline(false);
await expect(page.getByText('Feedback submitted successfully')).toBeVisible({ timeout: 10000 });
});
```
**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');
test('app serves cached page when offline', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/');
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
await page.evaluate(async () => {
const registration = await navigator.serviceWorker.ready;
return registration.active?.state === 'activated';
});
await swContext.setOffline(true);
await page.reload();
await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
await expect(page.getByText('You are offline')).toBeVisible();
await swContext.setOffline(false);
await expect(page.getByText('You are offline')).toBeHidden();
});
```
### Cache Verification
**Use when**: You need to confirm that specific resources are cached by the service worker.
**Avoid when**: You trust the framework's caching strategy and only need to verify the offline UX (test offline mode instead).
**TypeScript**
```typescript
import { test, expect } from '@playwright/test';
test('critical assets are cached by the service worker', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/');
// Wait for SW to be ready
await page.evaluate(() => navigator.serviceWorker.ready);
// Check the cache contents
const cachedUrls = await page.evaluate(async () => {
const cacheNames = await caches.keys();
const allUrls: string[] = [];
for (const name of cacheNames) {
const cache = await caches.open(name);
const keys = await cache.keys();
allUrls.push(...keys.map((req) => new URL(req.url).pathname));
}
return allUrls;
});
// Verify critical resources are cached
expect(cachedUrls).toContain('/');
expect(cachedUrls).toContain('/offline.html');
expect(cachedUrls.some((url) => url.endsWith('.js'))).toBe(true);
expect(cachedUrls.some((url) => url.endsWith('.css'))).toBe(true);
});
test('cache is invalidated after service worker update', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/');
// Get initial cache version
const initialCaches = await page.evaluate(() => caches.keys());
// Simulate a new SW version by clearing and reloading
await page.evaluate(async () => {
const registration = await navigator.serviceWorker.getRegistration();
await registration?.update();
});
// After update, old caches should be cleaned up
await page.reload();
await page.evaluate(() => navigator.serviceWorker.ready);
const updatedCaches = await page.evaluate(() => caches.keys());
// The app should manage cache names with versioning
expect(updatedCaches.length).toBeGreaterThanOrEqual(1);
});
```
**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');
test('critical assets are cached by the service worker', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/');
await page.evaluate(() => navigator.serviceWorker.ready);
const cachedUrls = await page.evaluate(async () => {
const cacheNames = await caches.keys();
const allUrls = [];
for (const name of cacheNames) {
const cache = await caches.open(name);
const keys = await cache.keys();
allUrls.push(...keys.map((req) => new URL(req.url).pathname));
}
return allUrls;
});
expect(cachedUrls).toContain('/');
expect(cachedUrls).toContain('/offline.html');
});
```
### PWA Install Prompt
**Use when**: You need to test the "Add to Home Screen" / PWA install flow.
**Avoid when**: Your app is not a PWA or does not handle the `beforeinstallprompt` event.
The `beforeinstallprompt` event cannot be synthetically triggered by Playwright. Instead, verify that your app captures and handles the event correctly.
**TypeScript**
```typescript
import { test, expect } from '@playwright/test';
test('app captures install prompt and shows install button', async ({ swContext }) => {
const page = await swContext.newPage();
// Mock the beforeinstallprompt event
await page.addInitScript(() => {
let deferredPrompt: Event | null = null;
// Simulate the browser firing beforeinstallprompt
window.addEventListener('load', () => {
const event = new Event('beforeinstallprompt');
(event as any).preventDefault = () => {};
(event as any).prompt = () => Promise.resolve();
(event as any).userChoice = Promise.resolve({ outcome: 'accepted' });
window.dispatchEvent(event);
});
});
await page.goto('/');
// Your app should show an install button when it captures the prompt
await expect(page.getByRole('button', { name: 'Install app' })).toBeVisible();
});
test('web app manifest is valid', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/');
// Verify manifest link exists
const manifestUrl = await page.evaluate(() => {
const link = document.querySelector('link[rel="manifest"]') as HTMLLinkElement;
return link?.href;
});
expect(manifestUrl).toBeTruthy();
// Fetch and validate the manifest
const response = await page.request.get(manifestUrl!);
expect(response.ok()).toBe(true);
const manifest = await response.json();
expect(manifest.name).toBeTruthy();
expect(manifest.icons).toHaveLength(expect.any(Number));
expect(manifest.start_url).toBeTruthy();
expect(manifest.display).toBe('standalone');
});
```
**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');
test('app captures install prompt and shows install button', async ({ swContext }) => {
const page = await swContext.newPage();
await page.addInitScript(() => {
window.addEventListener('load', () => {
const event = new Event('beforeinstallprompt');
event.preventDefault = () => {};
event.prompt = () => Promise.resolve();
event.userChoice = Promise.resolve({ outcome: 'accepted' });
window.dispatchEvent(event);
});
});
await page.goto('/');
await expect(page.getByRole('button', { name: 'Install app' })).toBeVisible();
});
```
### Push Notification Testing
**Use when**: Your PWA uses the Push API to receive push notifications from a server.
**Avoid when**: Notifications are handled entirely client-side without the Push API.
**TypeScript**
```typescript
import { test, expect } from '@playwright/test';
test('push notification triggers UI update', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/');
// Wait for SW to be ready
const swURL = await page.evaluate(async () => {
const reg = await navigator.serviceWorker.ready;
return reg.active?.scriptURL;
});
expect(swURL).toBeTruthy();
// Get the service worker and evaluate inside it
const sw = swContext.serviceWorkers()[0];
// Simulate a push event inside the service worker
await sw.evaluate(async () => {
const event = new PushEvent('push', {
data: new TextEncoder().encode(JSON.stringify({
title: 'New Message',
body: 'You have a new message from Alice',
url: '/messages',
})),
});
// @ts-ignore — dispatchEvent works in SW context
self.dispatchEvent(event);
});
// Verify the app reacts (e.g., shows a badge or notification banner)
await expect(page.getByTestId('notification-badge')).toHaveText('1');
});
```
**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');
test('push notification triggers UI update', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/');
const swURL = await page.evaluate(async () => {
const reg = await navigator.serviceWorker.ready;
return reg.active?.scriptURL;
});
expect(swURL).toBeTruthy();
const sw = swContext.serviceWorkers()[0];
await sw.evaluate(async () => {
const event = new PushEvent('push', {
data: new TextEncoder().encode(JSON.stringify({
title: 'New Message',
body: 'You have a new message from Alice',
url: '/messages',
})),
});
self.dispatchEvent(event);
});
await expect(page.getByTestId('notification-badge')).toHaveText('1');
});
```
### Background Sync Testing
**Use when**: Your app uses the Background Sync API to defer network requests until the user has connectivity.
**Avoid when**: Your app does not use background sync.
**TypeScript**
```typescript
import { test, expect } from '@playwright/test';
test('background sync retries failed requests when online', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/tasks');
// Ensure SW is active
await page.evaluate(() => navigator.serviceWorker.ready);
// Go offline
await swContext.setOffline(true);
// Create a task (will fail to sync)
await page.getByLabel('New task').fill('Buy groceries');
await page.getByRole('button', { name: 'Add' }).click();
// Task shows as "pending sync"
await expect(page.getByText('Buy groceries')).toBeVisible();
await expect(page.getByTestId('sync-status')).toHaveText('Pending');
// Come back online — background sync should fire
await swContext.setOffline(false);
// Wait for sync to complete
await expect(page.getByTestId('sync-status')).toHaveText('Synced', { timeout: 15000 });
});
```
**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');
test('background sync retries failed requests when online', async ({ swContext }) => {
const page = await swContext.newPage();
await page.goto('/tasks');
await page.evaluate(() => navigator.serviceWorker.ready);
await swContext.setOffline(true);
await page.getByLabel('New task').fill('Buy groceries');
await page.getByRole('button', { name: 'Add' }).click();
await expect(page.getByText('Buy groceries')).toBeVisible();
await expect(page.getByTestId('sync-status')).toHaveText('Pending');
await swContext.setOffline(false);
await expect(page.getByTestId('sync-status')).toHaveText('Synced', { timeout: 15000 });
});
```
## Decision Guide
| Scenario | Approach | Why |
|---|---|---|
| Verify SW registers | `context.waitForEvent('serviceworker')` | Confirms the SW file was fetched and registered |
| Test offline page serving | `context.setOffline(true)` + reload | Simulates network loss at the browser level |
| Verify specific assets are cached | `page.evaluate(() => caches.keys())` | Directly queries the Cache API |
| Test install prompt | `addInitScript` to mock `beforeinstallprompt` | Browser does not fire this event in automation |
| Validate web manifest | `page.request.get(manifestUrl)` | Fetch and parse the JSON manifest |
| Test push notifications | `sw.evaluate()` to dispatch PushEvent | Simulates a push message inside the SW |
| Test background sync | Go offline, perform action, come back online | Verifies the sync queue processes correctly |
| Test SW update flow | `registration.update()` via `page.evaluate` | Triggers a manual SW update check |
## Anti-Patterns
| Don't Do This | Problem | Do This Instead |
|---|---|---|
| Test service workers with the default `page` fixture | Default context is temporary; SWs may not persist | Use `launchPersistentContext` for reliable SW testing |
| Skip `navigator.serviceWorker.ready` before going offline | SW may not have finished caching | Always `await page.evaluate(() => navigator.serviceWorker.ready)` first |
| Use `page.route()` to simulate offline | `page.route()` never sees requests the SW itself makes (only `context.route()` does, Chromium 1.57+), and requests the SW answers from cache never hit the network | Use `context.setOffline(true)` for true network-level offline |
| Test the SW JavaScript file directly with unit tests only | Misses integration with the page and caching behavior | Combine unit tests with Playwright end-to-end SW tests |
| Assume caches are clean at test start | Previous test runs may leave stale caches | Clear caches in fixture setup or use a fresh `userDataDir` |
| `waitForTimeout` after `setOffline(false)` | Background sync timing is unpredictable | Use `expect(...).toHaveText('Synced', { timeout: 15000 })` |
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `context.waitForEvent('serviceworker')` never resolves | SW already registered before listener attached | Register listener before `page.goto()`, or check `context.serviceWorkers()` |
| SW does not activate | Old SW is still controlling the page | Use `skipWaiting()` in the SW or clear the `userDataDir` |
| Offline test still loads fresh content | SW cache was not populated before going offline | Wait for `navigator.serviceWorker.ready` and verify cache contents first |
| `context.setOffline(true)` has no effect | Using a non-persistent context or the wrong context | Ensure offline is set on the same context that owns the page |
| Push event does nothing | SW is not the active controller | Ensure `sw.evaluate()` targets the correct service worker from `context.serviceWorkers()` |
| Tests interfere with each other | Shared `userDataDir` between tests | Use a unique temp directory per test, cleaned in fixture teardown |
| Service worker tests only work in Chromium | Firefox and WebKit have limited SW support in Playwright | Run SW tests in Chromium only via `test.skip` or project config |
## Related
- [core/browser-apis.md](browser-apis.md) -- IndexedDB and localStorage used alongside service workers
- [core/configuration.md](configuration.md) -- project-level config for PWA testing
- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) -- wrapping persistent context in fixtures
- [core/websockets-and-realtime.md](websockets-and-realtime.md) -- real-time features that interact with offline/online state
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |