# 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