Back to Blog
Blog

Chrome Extension Testing: How to Test a Manifest V3 Extension End to End

A practical guide to Chrome extension testing: Manifest V3 service workers, Puppeteer vs Selenium vs BugRadar, worked failure examples and CI setup.

Written by
Gautam Agarwal
Read time
12 min read
Published
Chrome Extension Testing: How to Test a Manifest V3 Extension End to End

Quick answer: Chrome extension testing loads your built extension into a real browser and drives it the way a user would, using the popup, the content script on a live page and any approval screens, then checks what changes. It confirms that your service worker, content scripts and storage work together in the package people install.

An extension is a guest in other people's houses. It lives on pages built by other teams, wakes up only when something calls it, and forgets whatever it held in memory each time it sleeps. Your tests have to follow it through all three.

Key Takeaways

  • Chrome's docs define extension E2E testing as building the package, loading it into a browser and automating the flows a user goes through.
  • Manifest V3 service workers stop when idle, so test that every feature still works after the worker restarts.
  • Only Chrome's new headless mode loads extensions, which matters for CI.
  • Selenium's ChromeDriver keeps service workers awake, which hides suspension bugs; Chrome documents a Puppeteer approach for termination tests.
  • Updates are where most users meet your changes: a new permission can disable the extension until each user approves it.
  • BugRadar runs the real extension in Chromium, from a Chrome Web Store URL or a zipped unpacked folder, and records the exact build used in every run.

What is Chrome extension testing?

According to the Chrome guide to end to end testing for extensions, E2E testing loads your built extension package into a browser while a testing tool automates the same flows a user would go through.

A Manifest V3 extension has four surfaces worth testing:

  1. Extension pages: the popup, side panel and options page.
  2. Content scripts: the code that runs inside other websites.
  3. The service worker: the event handler that wakes, works and sleeps.
  4. Storage: the state that has to survive every sleep.

Every E2E test follows the same spine: build the package, load it, drive the user's actions and assert on what the user sees.

Where extensions break

LayerWhat can break
Install and permissionsThe extension asks for more than it needs, or loses access after an update
Extension pagesThe popup or side panel renders stale data
Content scriptsA host site changes its markup and the script misses its target
Service workerState held in memory disappears when the worker stops
Message passingThe popup, content script and worker stop hearing each other
StorageSettings fail to persist or sync across devices
UpdatesA new version adds a permission and Chrome disables the extension until the user approves

Ways to test a Chrome extension

MethodWhat it provesWhat it skips
Manual: Load unpacked at chrome://extensions in Developer modeThe extension installs and works for you, todayRepeatability and every later build
Unit tests with mocked chrome.* APIs (Jest with a mock library such as sinon-chrome)Your logic, fastThe real browser, real pages and the worker lifecycle
Puppeteer or PlaywrightReal journeys, plus direct access to the service workerUpkeep of selectors on host pages
SeleniumExtension pages through chrome-extension:// URLsService worker suspension, since ChromeDriver keeps workers awake
Extension Update Testing Tool from Google Chrome LabsUpdate flows and permission warningsDay to day journeys
BugRadarReal journeys from a written flow, in Chromium, on every PRFirefox and Safari extensions

Unit tests vs E2E tests for extensions

Test typeWhat it checksRuns inCommon tool
UnitOne function, with chrome.* APIs replaced by fakesNode.jsJest, Vitest
E2EThe built extension on real pagesA real browserPuppeteer, Playwright, Selenium, BugRadar

Chrome's own guidance favors E2E tests based on what is visible to the user rather than on internal state, so an internal refactor leaves the tests green.

__wf_reserved_inherit

Why E2E testing matters for Manifest V3 extensions

The service worker sleeps. In their write up on Chrome for Developers, engineers at eyeo found that Chrome suspended their extension's service worker after about 30 seconds of idle time, and that any state held in global variables vanished with it.

Host pages change on their own schedule. Content scripts depend on markup owned by other teams, so a site redesign can break your extension overnight.

Users cross several surfaces in one journey. A typical flow starts on a web page, opens the popup or side panel, and returns to the page.

Puppeteer vs Selenium vs BugRadar for extensions

PuppeteerSeleniumBugRadar
Loading the extensionLaunch arguments pointing at the unpacked folderChromeOptionsA Chrome Web Store URL or a zipped unpacked folder
Reaching the service workerYes, as a service_worker targetThrough an extension pageRuns the real worker
Service worker suspensionTested by stopping the worker in codeHidden, since ChromeDriver keeps workers awakeReal browser lifecycle
Test formatJavaScriptClient code in several languagesA written flow, in YAML or the dashboard
CostFree, open sourceFree, open sourceFree tier, then paid plans

Playwright and WebDriverIO also support extensions, and Chrome's docs point to their guides.

How to set up Chrome extension testing

Step 1: Build and package the extension

Build the unpacked Manifest V3 folder, then zip it with manifest.json at the archive root or inside one top level folder. Chrome's docs also recommend a fixed extension ID in tests, which keeps URLs like chrome-extension://<id>/popup.html stable.

With BugRadar: upload that .zip or paste the Chrome Web Store URL. BugRadar expects a zip of the unpacked folder rather than a .crx file.

Step 2: Write a Puppeteer test

import puppeteer from 'puppeteer';

‍

const EXT = '/path/to/dist';

const browser = await puppeteer.launch({

  headless: false,

  args: [`--disable-extensions-except=${EXT}`, `--load-extension=${EXT}`],

});

const worker = await browser.waitForTarget(t => t.type() === 'service_worker');

const EXT_ID = new URL(worker.url()).host;

const page = await browser.newPage();

await page.goto(`chrome-extension://${EXT_ID}/popup.html`);

From there, drive the popup and assert on what it shows. Run these tests against Chromium, because Google Chrome and Microsoft Edge now block automation tools from side loading extensions.

Step 3: Write the same journey as a flow

```yaml

# .BugRadar/price-tracker.flow.yaml

name: Track a price

instructions: |

  Open https://shop.example.com/product/42.

  Verify the price tracker badge appears beside the price.

  Click "Track price" and verify the confirmation appears.

```

‍

With BugRadar: add the extension from Apps → Create New App → Chrome Extension with a Web Store URL or a .zip, then attach it to your web app as the default for every run. The agent works with the real extension: service workers, content scripts, storage and network interception all run for real.

Step 4: Run on every pull request

```yaml

- uses: BugRadar/BugRadar-ci@main

  with:

    api-key: ${{ secrets.BugRadar_KEY }}

    platform: web

    app-id: my-web-app

    flow-ids: "uuid-1,uuid-2"

```

‍

With BugRadar: each run resolves every attached extension to an exact build and stores it with the results, so a later extension update leaves past results intact. The BugRadar web testing docs cover extension runs and per run overrides.

Test updates and permission changes

Most users meet a new version as an update rather than a fresh install. Google Chrome Labs publishes the Extension Update Testing Tool, a local update server that shows:

  • the permission warnings a manifest.json change triggers
  • how Chrome disables an updated extension until the user grants new permissions
  • whether your migration logic between versions works, through a flow closer to a Chrome Web Store update than a simple reload

Run it before any release that touches permissions, and prefer optional permissions requested at the moment a feature needs them.

__wf_reserved_inherit

The extension journey checklist

JourneyWhat to verify
First installThe onboarding page opens and default settings exist
Popup or side panel actionThe page changes and the popup reflects it
Content script on a live siteThe injected UI appears on the right element
Worker restart mid journeyThe feature still works after the worker stops
Sign in inside the extensionThe session survives restarts and browser relaunch
Update with a new permissionUsers see the right prompt and keep their data
Several extensions togetherYour extension and others, such as a wallet, coexist on one page

With BugRadar: attach several extensions to one web app and BugRadar loads them together in one browser session, so the last row runs as a normal flow.

Chrome extension testing examples

Each example starts from a failing run and traces it to a cause and a fix.

Example 1: The popup forgets the user after a coffee break

Scenario: the Selenium suite passes. Real users report that the popup shows "Sign in" again after a few minutes away.

StepExpectedWhat a Puppeteer run showed
Sign in through the popupSigned inSigned in
Stop the service workerWorker restarts on demandWorker restarts on demand
Open the popup againStill signed in"Sign in" shown

Cause: the session lived in a global variable in the service worker, and the restart cleared it. Selenium kept the worker awake, so the suite missed the restart.

Fix: persist the session in chrome.storage and add a test that stops the worker mid journey.

With BugRadar: extension runs use the real service worker in Chromium, so BugRadar flows follow the browser's normal lifecycle rather than a worker held awake by a debugger.

Example 2: CI loads the browser and skips the extension

Scenario: tests pass on a laptop. In CI, every test fails at the first popup step.

StepExpectedWhat the CI run showed
Start the browserBrowser runningBrowser running
Load the extensionExtension installedExtension absent
Open the popupPopup visiblePage error

Cause: the CI job ran an old headless mode, or branded Chrome, and both block side loaded extensions for automation.

Fix: run Chromium in the new headless mode.

With BugRadar: extension runs always use Chromium with Manifest V3 support in headless workers, so the browser choice is handled for you.

Example 3: Wallet connection hangs at approval

Scenario: a dApp test clicks "Connect wallet" and waits until it times out.

StepExpectedWhat the run showed
Open the dAppConnect buttonConnect button
Click "Connect wallet"Approval requestApproval opened in the side panel
Approve the requestWallet connectedTest still waiting on the page

Cause: the approval lives in a side panel, outside the page the test was driving.

Fix: drive the approval surface directly as part of the journey.

With BugRadar: side panel approval surfaces, such as MetaMask connection requests, appear to the agent as interactable browser pages, so the flow can approve and continue. BugRadar can also load the wallet and your own extension together in one browser session. Sign in steps with email codes work through leased inboxes, as this guide to OTP testing shows.

Example 4: An update quietly switches the extension off

Scenario: version 2.4 adds a feature that reads every site. A day after release, daily active users drop by a third.

StepExpectedWhat the update test showed
Install version 2.3Extension activeExtension active
Update to version 2.4Extension activeExtension disabled, waiting for approval
Open the popupNew featurePopup unavailable

Cause: the new version requested broad host permissions in the manifest, and Chrome disabled the extension until each user approved the new warning.

Fix: move the new access to optional permissions requested when the user first opens the feature, and run the update flow before every release.

Common Chrome extension testing problems and fixes

SymptomLikely causeFix
State lost after idle timeData held in service worker memoryPersist it in chrome.storage
Suite green, users report resetsChromeDriver keeps workers awakeAdd a Puppeteer test that stops the worker
Extension absent in CIOld headless mode or branded ChromeUse Chromium in the new headless mode
BugRadar upload rejectedA .crx file or a nested manifestZip the unpacked folder with manifest.json at the root
Popup test opens the wrong tabPopup reads the active tabPass a tab ID through the popup URL in tests
Users report the extension switched offAn update added a permission warningUse optional permissions and test the update flow

The Chrome extension testing process, summarized

StepWhat you doOutput
1. PackageZip the unpacked Manifest V3 buildA loadable extension
2. PinSet a fixed extension ID for testsStable extension URLs
3. WriteCover each journey across page, popup and workerVital journey tests
4. StressStop the service worker mid journeyProof that state survives
5. AutomateRun on every pull requestResults on each PR
6. DiagnoseTrace each failure to its causeA fix in the extension or the test

Conclusion

Chrome extension testing comes down to following the extension everywhere it lives: on host pages, in its own pages, and through every service worker restart. Test the built package in a real browser, stop the worker on purpose, and trace each failing run back to its cause.

A good first step this week: zip your unpacked build, attach it to an BugRadar web app, and run your main journey as one flow. If your team also ships a web app built with AI tools, this guide on how to test a Lovable app covers the same approach for full sites, and this ranking of mobile app testing tools covers native apps.

__wf_reserved_inherit

FAQs

How do you test a Chrome extension end to end?

Load the built package into a real browser and automate the journeys a user follows.

Can Selenium test Manifest V3 service workers?

Selenium reaches them through extension pages, though ChromeDriver keeps workers awake and hides suspension bugs.

Does headless Chrome load extensions?

Chrome's new headless mode loads extensions; the old headless mode skips them.

Why does my extension lose state?

Manifest V3 service workers stop when idle, which clears anything held in memory.

Which file does BugRadar accept for an extension?

A Chrome Web Store URL or a zip of the unpacked Manifest V3 folder.

Which browser runs BugRadar extension tests?

Chromium, which shares Chrome's Blink and V8 engines and supports Manifest V3 extensions.

‍

‍

Fix bugs, not tests.

Talk to an expert.

Book 30 minutes with our team. We'll show you BugRadar running on your app.

Start building.

Describe a user journey and watch an agent run it on iOS, Android, and web.

Try for free