@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/browser-apis/service-workers.md

@@ -0,0 +1,504 @@
+# Service Worker Testing
+
+## Table of Contents
+
+1. [Service Worker Basics](#service-worker-basics)
+2. [Registration & Lifecycle](#registration--lifecycle)
+3. [Cache Testing](#cache-testing)
+4. [Offline Testing](#offline-testing)
+5. [Push Notifications](#push-notifications)
+6. [Background Sync](#background-sync)
+
+## Service Worker Basics
+
+### Waiting for Service Worker Registration
+
+```typescript
+test("service worker registers", async ({ page }) => {
+  await page.goto("/pwa-app");
+
+  // Wait for SW to register
+  const swRegistered = await page.evaluate(async () => {
+    if (!("serviceWorker" in navigator)) return false;
+
+    const registration = await navigator.serviceWorker.ready;
+    return !!registration.active;
+  });
+
+  expect(swRegistered).toBe(true);
+});
+```
+
+### Getting Service Worker State
+
+```typescript
+test("check SW state", async ({ page }) => {
+  await page.goto("/");
+
+  const swState = await page.evaluate(async () => {
+    const registration = await navigator.serviceWorker.getRegistration();
+    if (!registration) return null;
+
+    return {
+      installing: !!registration.installing,
+      waiting: !!registration.waiting,
+      active: !!registration.active,
+      scope: registration.scope,
+    };
+  });
+
+  expect(swState?.active).toBe(true);
+  expect(swState?.scope).toContain(page.url());
+});
+```
+
+### Service Worker Context
+
+```typescript
+test("access service worker", async ({ context, page }) => {
+  await page.goto("/pwa-app");
+
+  // Get all service workers in context
+  const workers = context.serviceWorkers();
+
+  // Wait for service worker if not yet available
+  if (workers.length === 0) {
+    await context.waitForEvent("serviceworker");
+  }
+
+  const sw = context.serviceWorkers()[0];
+  expect(sw.url()).toContain("sw.js");
+});
+```
+
+## Registration & Lifecycle
+
+### Testing SW Update Flow
+
+```typescript
+test("service worker updates", async ({ page }) => {
+  await page.goto("/pwa-app");
+
+  // Check for update
+  const hasUpdate = await page.evaluate(async () => {
+    const registration = await navigator.serviceWorker.ready;
+    await registration.update();
+
+    return new Promise<boolean>((resolve) => {
+      if (registration.waiting) {
+        resolve(true);
+      } else {
+        registration.addEventListener("updatefound", () => {
+          resolve(true);
+        });
+        // Timeout if no update
+        setTimeout(() => resolve(false), 5000);
+      }
+    });
+  });
+
+  // If update found, test skip waiting flow
+  if (hasUpdate) {
+    await page.evaluate(async () => {
+      const registration = await navigator.serviceWorker.ready;
+      registration.waiting?.postMessage({ type: "SKIP_WAITING" });
+    });
+
+    // Wait for controller change
+    await page.evaluate(() => {
+      return new Promise<void>((resolve) => {
+        navigator.serviceWorker.addEventListener("controllerchange", () => {
+          resolve();
+        });
+      });
+    });
+  }
+});
+```
+
+### Testing SW Installation
+
+```typescript
+test("verify SW install event", async ({ context, page }) => {
+  // Listen for service worker before navigating
+  const swPromise = context.waitForEvent("serviceworker");
+
+  await page.goto("/pwa-app");
+
+  const sw = await swPromise;
+
+  // Evaluate in SW context
+  const swVersion = await sw.evaluate(() => {
+    // Access SW globals
+    return (self as any).SW_VERSION || "unknown";
+  });
+
+  expect(swVersion).toBe("1.0.0");
+});
+```
+
+### Unregistering Service Workers
+
+```typescript
+test.beforeEach(async ({ page }) => {
+  await page.goto("/");
+
+  // Unregister all service workers for clean state
+  await page.evaluate(async () => {
+    const registrations = await navigator.serviceWorker.getRegistrations();
+    await Promise.all(registrations.map((r) => r.unregister()));
+  });
+
+  // Clear caches
+  await page.evaluate(async () => {
+    const cacheNames = await caches.keys();
+    await Promise.all(cacheNames.map((name) => caches.delete(name)));
+  });
+});
+```
+
+## Cache Testing
+
+### Verifying Cached Resources
+
+```typescript
+test("assets are cached", async ({ page }) => {
+  await page.goto("/pwa-app");
+
+  // Wait for SW to cache assets
+  await page.evaluate(async () => {
+    await navigator.serviceWorker.ready;
+  });
+
+  // Check cache contents
+  const cachedUrls = await page.evaluate(async () => {
+    const cache = await caches.open("app-cache-v1");
+    const requests = await cache.keys();
+    return requests.map((r) => r.url);
+  });
+
+  expect(cachedUrls).toContain(expect.stringContaining("/styles.css"));
+  expect(cachedUrls).toContain(expect.stringContaining("/app.js"));
+});
+```
+
+### Testing Cache Strategies
+
+```typescript
+test("cache-first strategy", async ({ page }) => {
+  await page.goto("/pwa-app");
+
+  // Wait for initial cache
+  await page.waitForFunction(async () => {
+    const cache = await caches.open("app-cache-v1");
+    const keys = await cache.keys();
+    return keys.length > 0;
+  });
+
+  // Block network for cached resources
+  await page.route("**/styles.css", (route) => route.abort());
+
+  // Reload - should work from cache
+  await page.reload();
+
+  // Verify page still styled (CSS loaded from cache)
+  const hasStyles = await page.evaluate(() => {
+    const body = document.body;
+    const styles = window.getComputedStyle(body);
+    return styles.fontFamily !== ""; // Has custom font from CSS
+  });
+
+  expect(hasStyles).toBe(true);
+});
+```
+
+### Testing Cache Updates
+
+```typescript
+test("cache updates on new version", async ({ page }) => {
+  await page.goto("/pwa-app");
+
+  // Get initial cache
+  const initialCacheKeys = await page.evaluate(async () => {
+    const cache = await caches.open("app-cache-v1");
+    const keys = await cache.keys();
+    return keys.map((r) => r.url);
+  });
+
+  // Simulate app update by mocking SW response
+  await page.route("**/sw.js", (route) => {
+    route.fulfill({
+      contentType: "application/javascript",
+      body: `
+        const VERSION = 'v2';
+        self.addEventListener('install', (e) => {
+          e.waitUntil(caches.open('app-cache-v2'));
+          self.skipWaiting();
+        });
+      `,
+    });
+  });
+
+  // Trigger update
+  await page.evaluate(async () => {
+    const reg = await navigator.serviceWorker.ready;
+    await reg.update();
+  });
+
+  // Verify new cache exists
+  await page.waitForFunction(async () => {
+    return await caches.has("app-cache-v2");
+  });
+});
+```
+
+## Offline Testing
+
+This section covers **offline-first apps (PWAs)** that are designed to work offline using service workers, caching, and background sync. For testing **unexpected network failures** (error recovery, graceful degradation), see [error-testing.md](error-testing.md#offline-testing).
+
+### Simulating Offline Mode
+
+```typescript
+test("app works offline", async ({ page, context }) => {
+  await page.goto("/pwa-app");
+
+  // Ensure SW is active and content cached
+  await page.evaluate(async () => {
+    await navigator.serviceWorker.ready;
+  });
+  await page.waitForTimeout(1000); // Allow caching to complete
+
+  // Go offline
+  await context.setOffline(true);
+
+  // Navigate to cached page
+  await page.reload();
+
+  // Verify content loads
+  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
+
+  // Verify offline indicator
+  await expect(page.locator(".offline-badge")).toBeVisible();
+
+  // Go back online
+  await context.setOffline(false);
+  await expect(page.locator(".offline-badge")).not.toBeVisible();
+});
+```
+
+### Testing Offline Fallback
+
+```typescript
+test("shows offline page for uncached routes", async ({ page, context }) => {
+  await page.goto("/pwa-app");
+  await page.evaluate(() => navigator.serviceWorker.ready);
+
+  // Go offline
+  await context.setOffline(true);
+
+  // Navigate to uncached page
+  await page.goto("/uncached-page");
+
+  // Should show offline fallback
+  await expect(page.getByText("You are offline")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible();
+});
+```
+
+### Testing Offline Form Submission
+
+```typescript
+test("queues form submission offline", async ({ page, context }) => {
+  await page.goto("/pwa-app/form");
+
+  // Go offline
+  await context.setOffline(true);
+
+  // Submit form
+  await page.getByLabel("Message").fill("Offline message");
+  await page.getByRole("button", { name: "Send" }).click();
+
+  // Should show queued status
+  await expect(page.getByText("Queued for sync")).toBeVisible();
+
+  // Go online
+  await context.setOffline(false);
+
+  // Trigger sync (or wait for automatic)
+  await page.evaluate(async () => {
+    const reg = await navigator.serviceWorker.ready;
+    // Manually trigger sync for testing
+    await (reg as any).sync?.register("form-sync");
+  });
+
+  // Verify submission completed
+  await expect(page.getByText("Message sent")).toBeVisible({ timeout: 10000 });
+});
+```
+
+## Push Notifications
+
+### Mocking Push Subscription
+
+```typescript
+test("handles push subscription", async ({ page, context }) => {
+  // Grant notification permission
+  await context.grantPermissions(["notifications"]);
+
+  await page.goto("/pwa-app");
+
+  // Subscribe to push
+  const subscription = await page.evaluate(async () => {
+    const reg = await navigator.serviceWorker.ready;
+    const sub = await reg.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: "test-key",
+    });
+    return sub.toJSON();
+  });
+
+  expect(subscription.endpoint).toBeDefined();
+});
+```
+
+### Testing Push Message Handling
+
+```typescript
+test("handles push notification", async ({ context, page }) => {
+  await context.grantPermissions(["notifications"]);
+  await page.goto("/pwa-app");
+
+  // Wait for SW
+  const swPromise = context.waitForEvent("serviceworker");
+  const sw = await swPromise;
+
+  // Simulate push message to service worker
+  await sw.evaluate(async () => {
+    // Dispatch push event
+    const pushEvent = new PushEvent("push", {
+      data: new PushMessageData(
+        JSON.stringify({ title: "Test", body: "Push message" }),
+      ),
+    });
+    self.dispatchEvent(pushEvent);
+  });
+
+  // Note: Actual notification display testing is limited in Playwright
+  // Focus on verifying the SW handles the push correctly
+});
+```
+
+### Testing Notification Click
+
+```typescript
+test("notification click opens page", async ({ context, page }) => {
+  await context.grantPermissions(["notifications"]);
+  await page.goto("/pwa-app");
+
+  // Store notification URL target
+  let notificationUrl = "";
+
+  // Listen for new pages (notification click opens new page)
+  context.on("page", (newPage) => {
+    notificationUrl = newPage.url();
+  });
+
+  // Trigger notification via SW
+  await page.evaluate(async () => {
+    const reg = await navigator.serviceWorker.ready;
+    await reg.showNotification("Test", {
+      body: "Click me",
+      data: { url: "/notification-target" },
+    });
+  });
+
+  // Simulate clicking notification (via SW)
+  const sw = context.serviceWorkers()[0];
+  await sw.evaluate(() => {
+    self.dispatchEvent(
+      new NotificationEvent("notificationclick", {
+        notification: { data: { url: "/notification-target" } } as any,
+      }),
+    );
+  });
+
+  // Verify navigation occurred
+  await page.waitForTimeout(1000);
+  // Check if new page opened or current page navigated
+});
+```
+
+## Background Sync
+
+### Testing Background Sync Registration
+
+```typescript
+test("registers background sync", async ({ page }) => {
+  await page.goto("/pwa-app");
+
+  // Register sync
+  const syncRegistered = await page.evaluate(async () => {
+    const reg = await navigator.serviceWorker.ready;
+    if (!("sync" in reg)) return false;
+
+    await (reg as any).sync.register("my-sync");
+    return true;
+  });
+
+  expect(syncRegistered).toBe(true);
+});
+```
+
+### Testing Sync Event
+
+```typescript
+test("sync event fires when online", async ({ context, page }) => {
+  await page.goto("/pwa-app");
+
+  // Queue data while offline
+  await context.setOffline(true);
+
+  await page.evaluate(async () => {
+    // Store data in IndexedDB for sync
+    const db = await openDB();
+    await db.put("sync-queue", { id: 1, data: "test" });
+
+    // Register sync
+    const reg = await navigator.serviceWorker.ready;
+    await (reg as any).sync.register("data-sync");
+  });
+
+  // Track sync completion
+  await page.evaluate(() => {
+    window.syncCompleted = false;
+    navigator.serviceWorker.addEventListener("message", (e) => {
+      if (e.data.type === "SYNC_COMPLETE") {
+        window.syncCompleted = true;
+      }
+    });
+  });
+
+  // Go online
+  await context.setOffline(false);
+
+  // Wait for sync to complete
+  await page.waitForFunction(() => window.syncCompleted, { timeout: 10000 });
+});
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern                   | Problem                 | Solution                                     |
+| ------------------------------ | ----------------------- | -------------------------------------------- |
+| Not clearing SW between tests  | Tests affect each other | Unregister SW in beforeEach                  |
+| Not waiting for SW ready       | Race conditions         | Always await `navigator.serviceWorker.ready` |
+| Testing in isolation only      | Misses real SW behavior | Test with actual caching                     |
+| Hardcoded timeouts for caching | Flaky tests             | Wait for cache to populate                   |
+| Ignoring SW update cycle       | Missing update bugs     | Test install, activate, update flows         |
+
+## Related References
+
+- **Network Failures**: See [error-testing.md](error-testing.md#offline-testing) for unexpected network failure patterns
+- **Browser APIs**: See [browser-apis.md](browser-apis.md) for permissions
+- **Network Mocking**: See [network-advanced.md](../advanced/network-advanced.md) for network interception
+- **Browser Extensions**: See [browser-extensions.md](../testing-patterns/browser-extensions.md) for extension service worker patterns