zebbern/claude-code-guide / skills/playwright/core
playwright-core
VerifiedBattle-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.
browser-extensions.md
View on GitHub# Browser Extensions
> **When to use**: Testing Chrome extensions — popups, content scripts, background service workers, or extension-injected UI. Requires Chromium and a persistent browser context.
> **Prerequisites**: [core/configuration.md](configuration.md), [core/fixtures-and-hooks.md](fixtures-and-hooks.md)
## Quick Reference
```typescript
// Load an unpacked extension with a persistent context (Chromium only)
const context = await chromium.launchPersistentContext(userDataDir, {
headless: false, // Extensions require headed mode
args: [`--disable-extensions-except=${pathToExtension}`, `--load-extension=${pathToExtension}`],
})
```
**Hard constraints**: Extensions only work in Chromium. They require `launchPersistentContext` (not `browser.newContext`). Headed mode is mandatory — `headless: false` or use the `--headless=new` Chromium flag for "new headless" mode which supports extensions.
## Patterns
### Loading an Extension
**Use when**: You need to test any Chrome extension functionality.
**Avoid when**: You only need to test the web app that an extension interacts with — mock the extension's effects instead.
**TypeScript**
```typescript
import { test as base, expect, chromium, type BrowserContext } from "@playwright/test"
import path from "path"
// Create a fixture that provides a context with the extension loaded
type ExtensionFixtures = {
context: BrowserContext
extensionId: string
}
export const test = base.extend<ExtensionFixtures>({
// Override the default context to load the extension
context: async ({}, use) => {
const extensionPath = path.resolve(__dirname, "../my-extension")
const context = await chromium.launchPersistentContext("", {
headless: false,
args: [`--disable-extensions-except=${extensionPath}`, `--load-extension=${extensionPath}`],
})
await use(context)
await context.close()
},
// Extract the extension ID from the service worker URL
extensionId: async ({ context }, use) => {
let [background] = context.serviceWorkers()
if (!background) {
background = await context.waitForEvent("serviceworker")
}
const extensionId = background.url().split("/")[2]
await use(extensionId)
},
})
export { expect }
```
**JavaScript**
```javascript
const { test: base, expect, chromium } = require("@playwright/test")
const path = require("path")
const test = base.extend({
context: async ({}, use) => {
const extensionPath = path.resolve(__dirname, "../my-extension")
const context = await chromium.launchPersistentContext("", {
headless: false,
args: [`--disable-extensions-except=${extensionPath}`, `--load-extension=${extensionPath}`],
})
await use(context)
await context.close()
},
extensionId: async ({ context }, use) => {
let [background] = context.serviceWorkers()
if (!background) {
background = await context.waitForEvent("serviceworker")
}
const extensionId = background.url().split("/")[2]
await use(extensionId)
},
})
module.exports = { test, expect }
```
### Testing Extension Popups
**Use when**: Your extension has a browser action popup (the UI that appears when clicking the extension icon).
**Avoid when**: The popup is trivial — test the content script or background logic instead.
**TypeScript**
```typescript
import { test, expect } from "./extension-fixture"
test("extension popup displays saved bookmarks", async ({ page, extensionId }) => {
// Navigate directly to the popup HTML
await page.goto(`chrome-extension://${extensionId}/popup.html`)
// Interact with popup UI using standard locators
await expect(page.getByRole("heading", { name: "My Bookmarks" })).toBeVisible()
await page.getByRole("button", { name: "Add current page" }).click()
await expect(page.getByRole("listitem")).toHaveCount(1)
})
test("extension popup settings toggle works", async ({ page, extensionId }) => {
await page.goto(`chrome-extension://${extensionId}/popup.html`)
await page.getByRole("checkbox", { name: "Enable notifications" }).check()
await expect(page.getByText("Notifications enabled")).toBeVisible()
})
```
**JavaScript**
```javascript
const { test, expect } = require("./extension-fixture")
test("extension popup displays saved bookmarks", async ({ page, extensionId }) => {
await page.goto(`chrome-extension://${extensionId}/popup.html`)
await expect(page.getByRole("heading", { name: "My Bookmarks" })).toBeVisible()
await page.getByRole("button", { name: "Add current page" }).click()
await expect(page.getByRole("listitem")).toHaveCount(1)
})
```
### Testing Content Scripts
**Use when**: Your extension injects scripts or UI into web pages.
**Avoid when**: The content script only modifies data without visible effects — test via the background worker or storage.
**TypeScript**
```typescript
import { test, expect } from "./extension-fixture"
test("content script injects price comparison widget", async ({ context }) => {
const page = await context.newPage()
await page.goto("https://example-shop.com/product/123")
// Wait for the content script to inject its UI
// The extension adds a shadow DOM element — Playwright pierces it automatically
await expect(page.getByTestId("price-compare-widget")).toBeVisible({ timeout: 10000 })
await expect(page.getByText("Best price: $29.99")).toBeVisible()
})
test("content script highlights search terms", async ({ context }) => {
const page = await context.newPage()
await page.goto("https://example.com/article")
// Verify the content script added highlight spans
const highlights = page.locator(".ext-highlight")
await expect(highlights).toHaveCount(5)
await expect(highlights.first()).toHaveCSS("background-color", "rgb(255, 255, 0)")
})
```
**JavaScript**
```javascript
const { test, expect } = require("./extension-fixture")
test("content script injects price comparison widget", async ({ context }) => {
const page = await context.newPage()
await page.goto("https://example-shop.com/product/123")
await expect(page.getByTestId("price-compare-widget")).toBeVisible({ timeout: 10000 })
await expect(page.getByText("Best price: $29.99")).toBeVisible()
})
```
### Testing Background Service Workers
**Use when**: Your extension uses Manifest V3 service workers for background processing, alarms, or message passing.
**Avoid when**: The background logic is simple and already covered by popup or content script tests.
**TypeScript**
```typescript
import { test, expect } from "./extension-fixture"
test("background worker processes messages correctly", async ({ context, extensionId }) => {
const page = await context.newPage()
await page.goto(`chrome-extension://${extensionId}/popup.html`)
// Trigger an action that sends a message to the background worker
await page.getByRole("button", { name: "Sync data" }).click()
// Verify the response from the background worker updates the popup
await expect(page.getByText("Last synced: just now")).toBeVisible()
})
test("service worker handles extension storage", async ({ context, extensionId }) => {
const page = await context.newPage()
await page.goto(`chrome-extension://${extensionId}/popup.html`)
// Set a value through the popup
await page.getByLabel("API Key").fill("test-key-123")
await page.getByRole("button", { name: "Save" }).click()
// Reload popup and verify persistence through the service worker
await page.reload()
await expect(page.getByLabel("API Key")).toHaveValue("test-key-123")
})
```
**JavaScript**
```javascript
const { test, expect } = require("./extension-fixture")
test("background worker processes messages correctly", async ({ context, extensionId }) => {
const page = await context.newPage()
await page.goto(`chrome-extension://${extensionId}/popup.html`)
await page.getByRole("button", { name: "Sync data" }).click()
await expect(page.getByText("Last synced: just now")).toBeVisible()
})
```
### Testing Extension Options Page
**Use when**: Your extension has a dedicated options/settings page.
**Avoid when**: Settings are fully covered by popup tests.
**TypeScript**
```typescript
import { test, expect } from "./extension-fixture"
test("options page saves preferences", async ({ page, extensionId }) => {
await page.goto(`chrome-extension://${extensionId}/options.html`)
await page.getByRole("combobox", { name: "Theme" }).selectOption("dark")
await page.getByRole("checkbox", { name: "Auto-update" }).check()
await page.getByRole("button", { name: "Save" }).click()
await expect(page.getByText("Settings saved")).toBeVisible()
// Verify persistence after reload
await page.reload()
await expect(page.getByRole("combobox", { name: "Theme" })).toHaveValue("dark")
await expect(page.getByRole("checkbox", { name: "Auto-update" })).toBeChecked()
})
```
**JavaScript**
```javascript
const { test, expect } = require("./extension-fixture")
test("options page saves preferences", async ({ page, extensionId }) => {
await page.goto(`chrome-extension://${extensionId}/options.html`)
await page.getByRole("combobox", { name: "Theme" }).selectOption("dark")
await page.getByRole("checkbox", { name: "Auto-update" }).check()
await page.getByRole("button", { name: "Save" }).click()
await expect(page.getByText("Settings saved")).toBeVisible()
await page.reload()
await expect(page.getByRole("combobox", { name: "Theme" })).toHaveValue("dark")
await expect(page.getByRole("checkbox", { name: "Auto-update" })).toBeChecked()
})
```
## Decision Guide
| Scenario | Approach | Why |
| ----------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
| Test popup UI | Navigate to `chrome-extension://<id>/popup.html` | Direct access without needing to click the extension icon |
| Test content script effects | Load a real or test page, assert injected elements | Content scripts run automatically on matching URLs |
| Test background logic | Trigger via popup/content script, verify side effects | Cannot directly call service worker functions from Playwright |
| Test extension storage | Use popup to set values, reload, verify persistence | `chrome.storage` is only accessible from extension pages |
| Test options page | Navigate to `chrome-extension://<id>/options.html` | Same approach as popup testing |
| Test cross-page behavior | Open multiple pages in the same context | Persistent context shares extension state across tabs |
| Run in CI (headless) | Use `--headless=new` Chromium flag | New headless mode supports extensions unlike old headless |
| Test with multiple extensions | Add multiple paths to `--load-extension` | Comma-separate paths in the flag value |
## Anti-Patterns
| Don't Do This | Problem | Do This Instead |
| ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| `browser.newContext()` for extensions | Extensions require persistent context | `chromium.launchPersistentContext()` |
| `headless: true` without `--headless=new` | Old headless mode does not support extensions | Set `headless: false` or use `args: ['--headless=new']` |
| Testing on Firefox or WebKit | Extensions only work in Chromium | Skip extension tests for non-Chromium projects |
| Clicking the extension icon via coordinates | Fragile, toolbar layout varies | Navigate directly to `chrome-extension://<id>/popup.html` |
| Hardcoding the extension ID | IDs change between builds and machines | Extract dynamically from the service worker URL |
| Testing packed `.crx` files directly | Harder to debug, need to unpack first | Test the unpacked extension source directory |
| Sharing persistent context user data dir | State leaks between test runs | Use an empty string `''` for a temp directory |
| No timeout on content script assertions | Content scripts may load after page load | Use `{ timeout: 10000 }` on content script element assertions |
## Troubleshooting
| Symptom | Likely Cause | Fix |
| ---------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| Extension does not load | Wrong path in `--load-extension` | Use `path.resolve()` to get the absolute path to the extension directory |
| `context.serviceWorkers()` returns empty | Service worker not yet registered | Use `context.waitForEvent('serviceworker')` before extracting the ID |
| Popup page is blank | Popup HTML path is wrong | Check `manifest.json` for the correct `default_popup` path |
| Content script not injecting | Page URL does not match `matches` in manifest | Verify the URL pattern in `content_scripts[].matches` |
| Extension works locally but not in CI | CI uses old headless mode | Add `--headless=new` to launch args for CI |
| `chrome.storage` calls fail | Accessing storage from non-extension context | Only access storage through extension pages (popup, options, background) |
| Multiple extensions conflict | Both extensions modify the same page elements | Test each extension in its own persistent context |
| Tests are slow to start | Persistent context initialization overhead | Reuse context across tests in the same file with `test.describe` |
## Related
- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) -- building custom fixtures for extension contexts
- [core/service-workers-and-pwa.md](service-workers-and-pwa.md) -- service worker testing patterns (non-extension)
- [core/iframes-and-shadow-dom.md](iframes-and-shadow-dom.md) -- content scripts often inject Shadow DOM elements
- [core/configuration.md](configuration.md) -- project configuration for Chromium-only test suites
- [ci/ci-github-actions.md](../ci/ci-github-actions.md) -- CI setup for headed/extension tests
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: 468k | 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: 468k | 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: 468k | 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 |