An extension can work perfectly in development and still fail after packaging. The risky change is often not in the feature code itself. It can be a permission that moved, a host pattern that expanded, a content script that now runs somewhere new, or a browser surface that was never included in the release checklist.
Here is the small preflight review I now use before testing an MV3 release.
1. Compare the packaged manifests
Compare the last version you actually shipped with the new packaged version, not only the source manifest.
Check separately:
- required permissions;
- optional permissions;
- required host access;
- optional host access.
A permission moving from optional to required deserves attention even if the set of permission names looks familiar.
2. List every browser surface
Turn the manifest into a list of things a person can interact with or that Chrome can start:
- action popup;
- options page;
- side panel;
- background service worker;
- content scripts;
- commands;
- externally connectable pages;
- declarative network rules;
- web-accessible resources.
If a surface changed, add at least one release check for it. This sounds obvious, but it is easy to review the main popup while forgetting an options page or a host-specific content script.
3. Check where code can now run
For every content script, compare:
- match patterns;
- excluded matches;
- frames;
- execution world;
- run timing.
The JavaScript file can be unchanged while one of these settings changes the extension's behavior on real sites.
4. Test the packaged build
Run the checklist against the same build directory that will be uploaded. A development build can hide packaging, path, minification, or generated-manifest differences.
At minimum, reload the packaged extension and exercise one path through each changed surface.
5. Record why each check exists
Instead of keeping a generic list such as “test the popup,†connect each check to a release change:
- host access expanded → test the new host and confirm the old hosts still work;
- service worker declaration changed → test a cold start and a restart;
- popup added → test opening, closing, and the first message to the background;
- web-accessible resource changed → test both the intended page and an unintended page.
This makes the checklist smaller and easier to review than testing everything from memory on every release.
The small tool I am testing
I am building MV3 Replay. Its current tester is intentionally limited: a local static manifest analysis tool with a simple browser interface and a CLI. It reads an MV3 manifest.json, highlights declarations worth reviewing, and builds a manual release checklist.
It does not upload code, control the browser, collect analytics, inspect extension source files, or replace end-to-end testing. Node.js 20 or newer is required.
If you maintain a Chrome or Edge extension, you can download the latest tester ZIP here:
https://github.com/MV3Replay/mv3replay-cli/releases/download/v0.1.0-rc1/MV3Replay-Tester.zip
Extract it, then double-click START-MV3REPLAY-WINDOWS.cmd on Windows or START-MV3REPLAY-MAC.command on macOS. Choose a public or sanitized manifest.json; do not share credentials, private source code, customer data, or an unpublished extension.
I have not proven demand for it yet. If you already compare builds or run a manual release checklist, I would value a blunt answer: would you try this local check on one release, and what feels confusing, missing, or incorrect?
Disclosure: I am building MV3 Replay. This article explains the workflow behind the tool and is not a customer testimonial.
Top comments (0)