Skip to content

zebbern/claude-code-guide / skills/playwright/core

playwright-core

Verified

Battle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, assertions, fixtures, network mocking, auth flows, debugging, and framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.

FileKindSize
SKILL.mdskill md7.6 KB
accessibility.mdmarkdown53.2 KB
angular.mdmarkdown40.7 KB
api-testing.mdmarkdown51.4 KB
assertions-and-waiting.mdmarkdown26.8 KB
auth-flows.mdmarkdown32.6 KB
authentication.mdmarkdown48.7 KB
browser-apis.mdmarkdown24.0 KB
browser-extensions.mdmarkdown14.6 KB
canvas-and-webgl.mdmarkdown19.8 KB
clock-and-time-mocking.mdmarkdown19.5 KB
common-pitfalls.mdmarkdown44.4 KB
component-testing.mdmarkdown46.4 KB
configuration.mdmarkdown25.0 KB
crud-testing.mdmarkdown31.1 KB
debugging.mdmarkdown26.5 KB
drag-and-drop.mdmarkdown28.7 KB
electron-testing.mdmarkdown22.4 KB
error-and-edge-cases.mdmarkdown39.2 KB
error-index.mdmarkdown58.2 KB
file-operations.mdmarkdown26.1 KB
file-upload-download.mdmarkdown29.6 KB
fixtures-and-hooks.mdmarkdown32.9 KB
flaky-tests.mdmarkdown31.0 KB
forms-and-validation.mdmarkdown39.1 KB
i18n-and-localization.mdmarkdown24.4 KB
iframes-and-shadow-dom.mdmarkdown20.5 KB
locator-strategy.mdmarkdown20.1 KB
locators.mdmarkdown28.3 KB
mobile-and-responsive.mdmarkdown58.2 KB
multi-context-and-popups.mdmarkdown22.3 KB
multi-user-and-collaboration.mdmarkdown20.0 KB
network-mocking.mdmarkdown44.8 KB
nextjs.mdmarkdown36.1 KB
performance-testing.mdmarkdown23.0 KB
react.mdmarkdown38.6 KB
search-and-filter.mdmarkdown43.2 KB
security-testing.mdmarkdown25.2 KB
service-workers-and-pwa.mdmarkdown20.3 KB
test-architecture.mdmarkdown24.5 KB
test-data-management.mdmarkdown35.7 KB
test-organization.mdmarkdown30.5 KB
third-party-integrations.mdmarkdown30.4 KB
visual-regression.mdmarkdown35.4 KB
vue.mdmarkdown38.6 KB
websockets-and-realtime.mdmarkdown20.8 KB
when-to-mock.mdmarkdown28.0 KB

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                    | Only intercepts Playwright-visible requests; SW fetch events are not intercepted | 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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall