extension-testing-and-debugging

name	extension-testing-and-debugging
description	Debug Chromium browser extensions across service workers, content scripts, and extension pages, and write reproducible Playwright-based tests. Use when loading unpacked extensions, inspecting runtime contexts, building smoke tests, or diagnosing permission, lifecycle, and messaging issues.

Extension Testing and Debugging

Overview

Treat extension debugging as a multi-context problem. A user-visible bug may involve a popup, content script, service worker restart, host permission gap, or page-specific timing issue. Start with the smallest manual reproduction in a load-unpacked flow, then lock the behavior down with reproducible Playwright tests.

Read these references as needed:

• references/load-unpacked-and-inspect.md for the basic Chromium debug loop
• references/playwright-extension-testing.md for automated testing patterns
• references/debugging-checklist.md for context-by-context diagnosis

Core workflow

1) Reproduce in a load-unpacked loop

• Load the built extension directory into Chromium.
• Confirm the issue in the smallest possible scenario: one tab, one site, one action.
• Capture which context owns the failure: popup, side panel, content script, service worker, or packaging.

2) Inspect the right context

• Check service worker logs and lifecycle events for orchestration issues.
• Check content-script behavior on the actual page and frame that fails.
• Check popup or side-panel state for stale assumptions about tab or storage.

3) Automate with Playwright

• Use a persistent Chromium context that loads the unpacked extension.
• Prefer bundled Chromium for extension tests because the official Playwright guidance notes that Chrome and Edge removed the old command-line side-load flags.
• Assert user-visible outcomes plus the underlying extension state transition when possible.

4) Test the risky paths

• Worker restart and reinstall flows
• messaging across tabs or frames
• permission prompts or missing-host behavior
• page reloads and duplicate injection
• side-panel or popup state re-entry

5) Keep debug instrumentation disposable

• Gate debug logging or diagnostics so they do not leak into production builds.
• Remove temporary probes once the failure mode is understood or codified in a test.

Strong defaults

• Start with a reproducible manual loop before widening the test matrix.
• Write tests against the built extension output, not source assumptions.
• Prefer assertions on visible page effects and extension storage changes.
• Capture the extension ID dynamically in tests when needed.

Anti-patterns

• Debugging only the popup when the real failure lives in worker restart logic.
• Automating a test flow before confirming the extension actually loads unpacked.
• Using a one-off browser profile that hides missing permission prompts or startup races.
• Keeping verbose debug code enabled after the bug is fixed.

Notes

• Primary references:
  • https://playwright.dev/docs/chrome-extensions
  • https://playwright.dev/docs/getting-started-mcp
  • https://developer.chrome.com/docs/extensions/get-started/tutorial/debug
• Playwright MCP is useful for browser-side automation. Extension-specific E2E testing still belongs in Playwright code that launches Chromium with the extension loaded.