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

testing-patterns/browser-extensions.md

View on GitHub
# Browser Extension Testing

## Table of Contents

1. [Setup & Configuration](#setup--configuration)
2. [Loading Extensions](#loading-extensions)
3. [Popup Testing](#popup-testing)
4. [Background Script Testing](#background-script-testing)
5. [Content Script Testing](#content-script-testing)
6. [Extension APIs](#extension-apis)
7. [Cross-Browser Testing](#cross-browser-testing)

## Setup & Configuration

### Prerequisites

```bash
npm install -D @playwright/test
npx playwright install chromium  # Extensions only work in Chromium
```

### Basic Configuration

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import path from 'path';

export default defineConfig({
	testDir: './tests',
	use: {
		// Extensions require non-headless Chromium
		headless: false
	},
	projects: [
		{
			name: 'chromium-extension',
			use: {
				browserName: 'chromium'
			}
		}
	]
});
```

### Extension Fixture

```typescript
// fixtures/extension.ts
import { test as base, chromium, BrowserContext, Page } from '@playwright/test';
import path from 'path';

type ExtensionFixtures = {
	context: BrowserContext;
	extensionId: string;
	backgroundPage: Page;
};

export const test = base.extend<ExtensionFixtures>({
	context: async ({}, use) => {
		const pathToExtension = path.join(__dirname, '../extension');

		const context = await chromium.launchPersistentContext('', {
			headless: false,
			args: [`--disable-extensions-except=${pathToExtension}`, `--load-extension=${pathToExtension}`]
		});

		await use(context);
		await context.close();
	},

	extensionId: async ({ context }, use) => {
		// Get extension ID from service worker URL
		let extensionId = '';

		// Wait for service worker to be registered
		const serviceWorker = context.serviceWorkers()[0] || (await context.waitForEvent('serviceworker'));

		extensionId = serviceWorker.url().split('/')[2];

		await use(extensionId);
	},

	backgroundPage: async ({ context }, use) => {
		// For Manifest V2 extensions
		const backgroundPage = context.backgroundPages()[0] || (await context.waitForEvent('backgroundpage'));

		await use(backgroundPage);
	}
});

export { expect } from '@playwright/test';
```

## Loading Extensions

### Manifest V3 (Service Worker)

```typescript
test('load MV3 extension', async () => {
	const pathToExtension = path.join(__dirname, '../my-extension');

	const context = await chromium.launchPersistentContext('', {
		headless: false,
		args: [`--disable-extensions-except=${pathToExtension}`, `--load-extension=${pathToExtension}`]
	});

	// Wait for service worker
	const serviceWorker = await context.waitForEvent('serviceworker');
	expect(serviceWorker.url()).toContain('chrome-extension://');

	await context.close();
});
```

### Manifest V2 (Background Page)

```typescript
test('load MV2 extension', async () => {
	const pathToExtension = path.join(__dirname, '../my-extension-v2');

	const context = await chromium.launchPersistentContext('', {
		headless: false,
		args: [`--disable-extensions-except=${pathToExtension}`, `--load-extension=${pathToExtension}`]
	});

	// Wait for background page
	const backgroundPage = await context.waitForEvent('backgroundpage');
	expect(backgroundPage.url()).toContain('chrome-extension://');

	await context.close();
});
```

### Multiple Extensions

```typescript
test('load multiple extensions', async () => {
	const extension1 = path.join(__dirname, '../extension1');
	const extension2 = path.join(__dirname, '../extension2');

	const context = await chromium.launchPersistentContext('', {
		headless: false,
		args: [
			`--disable-extensions-except=${extension1},${extension2}`,
			`--load-extension=${extension1},${extension2}`
		]
	});

	// Both service workers should be available
	await context.waitForEvent('serviceworker');
	await context.waitForEvent('serviceworker');

	expect(context.serviceWorkers().length).toBe(2);

	await context.close();
});
```

## Popup Testing

### Opening Extension Popup

```typescript
test('test popup UI', async ({ context, extensionId }) => {
	// Open popup directly by URL
	const popupPage = await context.newPage();
	await popupPage.goto(`chrome-extension://${extensionId}/popup.html`);

	// Test popup interactions
	await expect(popupPage.getByRole('heading')).toHaveText('My Extension');
	await popupPage.getByRole('button', { name: 'Enable' }).click();
	await expect(popupPage.getByText('Enabled')).toBeVisible();
});
```

### Popup State Persistence

```typescript
test('popup remembers state', async ({ context, extensionId }) => {
	// First interaction
	const popup1 = await context.newPage();
	await popup1.goto(`chrome-extension://${extensionId}/popup.html`);
	await popup1.getByRole('checkbox', { name: 'Dark Mode' }).check();
	await popup1.close();

	// Reopen popup
	const popup2 = await context.newPage();
	await popup2.goto(`chrome-extension://${extensionId}/popup.html`);

	// State should persist
	await expect(popup2.getByRole('checkbox', { name: 'Dark Mode' })).toBeChecked();
});
```

### Popup Communication with Background

```typescript
test('popup sends message to background', async ({ context, extensionId }) => {
	const popup = await context.newPage();
	await popup.goto(`chrome-extension://${extensionId}/popup.html`);

	// Set up listener for response
	const responsePromise = popup.evaluate(() => {
		return new Promise((resolve) => {
			chrome.runtime.onMessage.addListener((message) => {
				if (message.type === 'RESPONSE') resolve(message.data);
			});
		});
	});

	// Click button that sends message
	await popup.getByRole('button', { name: 'Fetch Data' }).click();

	// Verify response
	const response = await responsePromise;
	expect(response).toBeDefined();
});
```

## Background Script Testing

### Manifest V3 Service Worker

```typescript
test('service worker handles messages', async ({ context, extensionId }) => {
	const page = await context.newPage();
	await page.goto('https://example.com');

	// Send message to service worker from page
	const response = await page.evaluate(async (extId) => {
		return new Promise((resolve) => {
			chrome.runtime.sendMessage(extId, { type: 'GET_STATUS' }, resolve);
		});
	}, extensionId);

	expect(response).toEqual({ status: 'active' });
});
```

### Testing Background Logic

```typescript
test('background script logic', async ({ context }) => {
	const serviceWorker = context.serviceWorkers()[0] || (await context.waitForEvent('serviceworker'));

	// Evaluate in service worker context
	const result = await serviceWorker.evaluate(async () => {
		// Access extension APIs
		const storage = await chrome.storage.local.get('settings');
		return storage;
	});

	expect(result.settings).toBeDefined();
});
```

### Alarms and Timers

```typescript
test('alarm triggers correctly', async ({ context }) => {
	const serviceWorker = await context.waitForEvent('serviceworker');

	// Create alarm
	await serviceWorker.evaluate(async () => {
		await chrome.alarms.create('test-alarm', { delayInMinutes: 0.01 });
	});

	// Wait for alarm handler
	await serviceWorker.evaluate(() => {
		return new Promise<void>((resolve) => {
			chrome.alarms.onAlarm.addListener((alarm) => {
				if (alarm.name === 'test-alarm') resolve();
			});
		});
	});

	// Verify alarm was handled (check side effects)
	const wasHandled = await serviceWorker.evaluate(async () => {
		const { alarmTriggered } = await chrome.storage.local.get('alarmTriggered');
		return alarmTriggered;
	});

	expect(wasHandled).toBe(true);
});
```

## Content Script Testing

### Injected Content Script

```typescript
test('content script injects UI', async ({ context }) => {
	const page = await context.newPage();
	await page.goto('https://example.com');

	// Wait for content script to inject elements
	await expect(page.locator('#my-extension-widget')).toBeVisible();

	// Interact with injected UI
	await page.locator('#my-extension-widget button').click();
	await expect(page.locator('#my-extension-widget .result')).toHaveText('Success');
});
```

### Content Script Communication

```typescript
test('content script communicates with background', async ({ context, extensionId }) => {
	const page = await context.newPage();
	await page.goto('https://example.com');

	// Trigger content script action
	await page.locator('#my-extension-button').click();

	// Wait for background response reflected in UI
	await expect(page.locator('#my-extension-status')).toHaveText('Connected');
});
```

### Page Modification Testing

```typescript
test('content script modifies page', async ({ context }) => {
	const page = await context.newPage();
	await page.goto('https://example.com');

	// Verify content script modifications
	const hasModification = await page.evaluate(() => {
		// Check for injected styles
		const styles = document.querySelectorAll('style[data-extension="my-ext"]');
		return styles.length > 0;
	});

	expect(hasModification).toBe(true);

	// Check DOM modifications
	const modifiedElements = await page.locator('[data-modified-by-extension]').count();
	expect(modifiedElements).toBeGreaterThan(0);
});
```

## Extension APIs

### Storage API

```typescript
test('chrome.storage operations', async ({ context }) => {
	const serviceWorker = await context.waitForEvent('serviceworker');

	// Set storage
	await serviceWorker.evaluate(async () => {
		await chrome.storage.local.set({ key: 'value', count: 42 });
	});

	// Get storage
	const data = await serviceWorker.evaluate(async () => {
		return await chrome.storage.local.get(['key', 'count']);
	});

	expect(data).toEqual({ key: 'value', count: 42 });

	// Test storage.sync
	await serviceWorker.evaluate(async () => {
		await chrome.storage.sync.set({ synced: true });
	});

	const syncData = await serviceWorker.evaluate(async () => {
		return await chrome.storage.sync.get('synced');
	});

	expect(syncData.synced).toBe(true);
});
```

### Tabs API

```typescript
test('chrome.tabs operations', async ({ context }) => {
	const serviceWorker = await context.waitForEvent('serviceworker');

	// Create a tab
	const page = await context.newPage();
	await page.goto('https://example.com');

	// Query tabs from service worker
	const tabs = await serviceWorker.evaluate(async () => {
		return await chrome.tabs.query({ url: '*://example.com/*' });
	});

	expect(tabs.length).toBeGreaterThan(0);
	expect(tabs[0].url).toContain('example.com');

	// Send message to tab
	await serviceWorker.evaluate(async (tabId) => {
		await chrome.tabs.sendMessage(tabId, { type: 'PING' });
	}, tabs[0].id);
});
```

### Context Menus

```typescript
test('context menu actions', async ({ context, extensionId }) => {
	const serviceWorker = await context.waitForEvent('serviceworker');

	// Create context menu
	await serviceWorker.evaluate(async () => {
		await chrome.contextMenus.create({
			id: 'test-menu',
			title: 'Test Action',
			contexts: ['selection']
		});
	});

	// Simulate context menu click
	const page = await context.newPage();
	await page.goto('https://example.com');

	// Select text
	await page.evaluate(() => {
		const range = document.createRange();
		range.selectNodeContents(document.body.firstChild!);
		window.getSelection()?.addRange(range);
	});

	// Trigger context menu action programmatically
	await serviceWorker.evaluate(async () => {
		// Simulate the click handler
		chrome.contextMenus.onClicked.dispatch(
			{ menuItemId: 'test-menu', selectionText: 'selected text' },
			{ id: 1, url: 'https://example.com' }
		);
	});
});
```

### Permissions API

```typescript
test('request permissions', async ({ context, extensionId }) => {
	const popup = await context.newPage();
	await popup.goto(`chrome-extension://${extensionId}/popup.html`);

	// Check current permissions
	const hasPermission = await popup.evaluate(async () => {
		return await chrome.permissions.contains({
			origins: ['https://*.github.com/*']
		});
	});

	// Request new permission (will show prompt in real scenario)
	// For testing, we check the request is made correctly
	const permissionRequest = popup.evaluate(async () => {
		try {
			return await chrome.permissions.request({
				origins: ['https://*.github.com/*']
			});
		} catch (e) {
			return false;
		}
	});

	// In automated tests, permission prompts are typically auto-granted or mocked
});
```

## Anti-Patterns to Avoid

| Anti-Pattern                   | Problem               | Solution                                 |
| ------------------------------ | --------------------- | ---------------------------------------- |
| Testing in headless mode       | Extensions don't load | Use `headless: false`                    |
| Not waiting for service worker | Race conditions       | Wait for `serviceworker` event           |
| Hardcoding extension ID        | ID changes on reload  | Extract ID from service worker URL       |
| Testing packed extensions only | Slow iteration        | Test unpacked during development         |
| Ignoring MV3 differences       | Breaking changes      | Test both MV2 and MV3 if supporting both |

## Related References

- **Service Workers**: See [service-workers.md](../browser-apis/service-workers.md) for SW testing patterns
- **Multi-Context**: See [multi-context.md](../advanced/multi-context.md) for popup handling
- **Browser APIs**: See [browser-apis.md](../browser-apis/browser-apis.md) for permissions testing
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