Manifest matrix + field shapes - manifest-v3-test-surface-reference

Deep-lookup detail for the summary tables in SKILL.md: exact MV2/MV3 field shapes, the full Firefox/Chrome key matrix, and the two service-worker constructs (offscreen documents, keep-alive). Sources are consolidated in the link list at the bottom.

Exact field shapes

background

MV2:

{
  "background": {
    "scripts": ["backgroundContextMenus.js", "backgroundOauth.js"],
    "persistent": false
  }
}

MV3:

{
  "background": {
    "service_worker": "service_worker.js",
    "type": "module"
  }
}

The MV3 service_worker field is a single string (not an array); type is optional and only valid as "module". The MV2 persistent flag is removed entirely.

host_permissions split

"Host permissions in Manifest V3 are a separate field; you don't specify them in "permissions" or in "optional_permissions"."

MV2:

"permissions": ["tabs", "bookmarks", "https://www.blogger.com/"],
"optional_permissions": ["unlimitedStorage", "*://*/*"]

MV3:

"permissions": ["tabs", "bookmarks"],
"optional_permissions": ["unlimitedStorage"],
"host_permissions": ["https://www.blogger.com/"],
"optional_host_permissions": ["*://*/*"]

"content_scripts[].matches" is unchanged between MV2 and MV3.

web_accessible_resources shape change

MV2 (flat string array):

"web_accessible_resources": [
  "images/*",
  "style/extension.css",
  "script/extension.js"
]

MV3 (array of objects, each scoping resources to URL patterns or extension IDs):

"web_accessible_resources": [
  { "resources": ["images/*"], "matches": ["*://*/*"] },
  {
    "resources": ["style/extension.css", "script/extension.js"],
    "matches": ["https://example.com/*"]
  }
]

Test implication: a page-context fetch(chrome.runtime.getURL('...')) that worked under MV2 may 404 under MV3 if the requester's origin isn't covered by a matches pattern.

Firefox vs Chrome manifest key matrix

Every documented manifest key with Firefox / Chrome availability and MV2 / MV3 status per mdn-manifest (opens in new window). Tests must gate on browser detection or split into per-browser fixtures when a key is "not supported" in one column.

browser_specific_settings.gecko

Firefox-specific metadata (extension ID, min Firefox version) lives under browser_specific_settings.gecko. Chrome silently ignores this key:

{
  "browser_specific_settings": {
    "gecko": {
      "id": "@addon-example",
      "strict_min_version": "42.0"
    }
  }
}

Test note: AMO submission validation requires a stable gecko.id for signing - a test asserting the built zip carries a deterministic ID prevents accidental ID drift across builds.

Service-worker constructs

Offscreen documents

DOM-requiring work in MV3 goes to an offscreen document:

chrome.offscreen.createDocument({
  url: chrome.runtime.getURL('offscreen.html'),
  reasons: ['CLIPBOARD'],
  justification: 'testing the offscreen API',
});

Offscreen documents communicate with the service worker via runtime.sendMessage / runtime.onMessage only - they don't share other extension APIs.

Keep-alive heartbeat

The keep-alive pattern (calling chrome.runtime.getPlatformInfo on a ~25s interval to reset the idle timer, or writing to chrome.storage.local every 20s) is documented but Chrome explicitly limits its use to enterprise/education managed extensions, "reserves the right to take action" against others, and notes a waitUntil()-style API is under discussion in the W3C WebExtensions Community Group (WECG).

web-ext - Mozilla's CLI for Firefox WebExtension testing

Companion reference for manifest-v3-test-surface-reference. Consult when the extension targets Firefox (signing is mandatory for distribution) or when cross-browser test runs need a single CLI that drives both Firefox and Chromium against the same source tree.

web-ext is Mozilla's reference CLI for WebExtension development. Per the mozilla/web-ext README (opens in new window) it bundles run, lint, sign, build, and docs; v8 added dump-config and reworked signing to use the AMO submission API by default (per the web-ext command reference (opens in new window)). --source-dir / -s is a global option; --artifacts-dir (default ./web-ext-artifacts) controls where build / sign write zips.

Install

npm install --save-dev web-ext    # per-project, preferred for CI determinism

Mozilla recommends the current Node LTS (per we-readme (opens in new window)). A web-ext-config.cjs file pins flags per run; web-ext dump-config (v8, per we-cmd (opens in new window)) prints the resolved configuration as JSON for diffing.

Lint

web-ext lint wraps mozilla/addons-linter (opens in new window) and emits AMO-compatible warnings. CI-friendly invocation:

web-ext lint \
  --source-dir ./dist \
  --output json \
  --pretty \
  --warnings-as-errors > lint-report.json

--warnings-as-errors / -w is the right CI default - per we-cmd (opens in new window) it escalates lint warnings (unsupported manifest fields, MV2-only APIs flagged for MV3) into a non-zero exit code. Other flags: --metadata, --self-hosted (disables AMO-related messages - never on AMO-bound builds), --boring.

Output shape: { "count", "summary": { "errors", "notices", "warnings" }, "metadata", "errors": [{ "code", "message", "file", "line", "column" }], ... } (per addons-linter; spot-check its changelog before pinning a parser). Parse with jq '.summary.errors + .summary.warnings'.

Run

web-ext run builds the extension, installs it into a fresh temporary Firefox profile, then watches the source directory and reloads on edit (per we-cmd (opens in new window)):

web-ext run \
  --source-dir ./dist \
  --firefox=firefox \
  --start-url 'about:debugging#/runtime/this-firefox'

--firefox aliases (per we-cmd (opens in new window)): firefox, beta, nightly, deved / firefoxdeveloperedition, or a binary path. To pin a profile: --firefox-profile=qa-profile --profile-create-if-missing --keep-profile-changes (the last persists profile modifications across runs per we-cmd (opens in new window)).

Targets (per we-cmd (opens in new window) --target): firefox-desktop, firefox-android (wired via the --adb-* flag family), and chromium:

web-ext run --source-dir ./dist --target chromium --chromium-binary "$(which chromium)"

The chromium target is the lowest-effort parity smoke-test; deep Chromium test surface lives in playwright-extension-fixtures.

Build

web-ext build -s ./dist -a ./build/artifacts --overwrite-dest \
  --filename 'my-extension-{version}.zip'

Per we-cmd (opens in new window), --filename defaults to {name}-{version}.zip; --overwrite-dest is required when the artefact path already exists. Build runs lint first and exits non-zero on lint failure.

Sign

Per we-cmd (opens in new window), web-ext sign v8 uses the AMO submission API by default and --channel is required:

export WEB_EXT_API_KEY='user:12345:1'
export WEB_EXT_API_SECRET='abcdef...'

web-ext sign -s ./dist --channel listed \
  --amo-metadata ./amo-metadata.json \
  --upload-source-code ./source.tar.gz

Channel semantics (quoted from we-cmd (opens in new window)): with listed the extension "gets submitted for public listing"; with unlisted it "gets submitted for signing for self-distribution." Key flags: --api-key / --api-secret (JWT for the AMO API), --amo-metadata (required for a first listed version), --timeout (default 300000 ms), --approval-timeout (default 900000 ms, v8) - AMO can take longer in queue, requiring follow-up polling. Update submissions require an extension ID in the manifest (browser_specific_settings.gecko.id) per we-cmd (opens in new window). The signed .xpi lands in --artifacts-dir.

Anti-patterns

Limitations

• Linter is not tests. web-ext lint catches manifest issues and AMO policy violations; it does not exercise behaviour - pair with playwright-extension-fixtures.
• Chromium target is run-only. No AMO-style signing path for Chrome; the Chrome Web Store has its own publishing flow.
• No Firefox MV3 parity check. web-ext lint does not warn when a key is MV3-supported in Chrome but not Firefox (or vice versa); cross-reference the SKILL.md matrix manually.

References

• Mozilla web-ext README - we-readme (opens in new window).
• Extension Workshop web-ext v8 command reference (every flag on every subcommand) - we-cmd (opens in new window).
• Mozilla addons-linter (what web-ext lint wraps) - https://github.com/mozilla/addons-linter