ever-co/ever-works / .agents/skills/playwright-best-practices
playwright-best-practices
VerifiedUse 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.
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
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: 471k | 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: 471k | 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: 471k | 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 |