Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

browser-apis/service-workers.md

View on GitHub
# 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
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