mv2-to-mv3-migration-test-checklist

Overview

MV2 -> MV3 migration silently breaks extensions in ways no single test catches: a removed background.scripts array fails to load, a leftover host pattern in permissions[] drops at runtime, a remote <script> tag passes lint but is blocked by the new CSP. It is testable only by walking the checklist section-by-section and emitting the verification case per cell - which is what this builder produces, mapping Chrome's official Manifest V3 migration checklist (opens in new window) to the test that proves each section landed. The per-section verification matrices and worked test code live in references/verification-cases.md.

Composes with:

• manifest-v3-test-surface-reference - the field-level rename + key-matrix reference this builder consults at every step.
• web-ext-cli-mozilla - the Firefox-side validator (web-ext lint) used to verify each MV3 cell against AMO.
• chrome-extension-test-loader - the manual Chrome dev-load that surfaces section-level errors during checklist walk.

For Playwright-driven MV3 popup / content-script fixtures see browser-extension-tests. That skill assumes the MV3 manifest is already valid; this builder is what proves it before assertion-level tests run.

When to use

• An MV2 extension is being migrated to MV3 - produce the per-extension verification checklist before the migration PR.
• An MV3 build is failing to load with no clear error - walk the six checklist sections to localize.
• A Chrome-MV3 extension is being ported to Firefox - the divergence cells flag which sections need Firefox-specific tests.
• A reviewer wants section-by-section evidence the migration is complete.

Workflow

Step 1 - Inventory the source MV2 manifest

Read the project's manifest.json and snapshot the MV2 baseline per cr-manifest (opens in new window). The inventory drives the rest of the workflow - each MV3 checklist section consumes one or more fields from it.

# Snapshot the original
cp manifest.json manifest.mv2.backup.json
jq -r '
  {
    manifest_version: .manifest_version,
    background: .background,
    browser_action: .browser_action,
    page_action: .page_action,
    permissions: .permissions,
    optional_permissions: .optional_permissions,
    web_accessible_resources: .web_accessible_resources,
    content_security_policy: .content_security_policy,
    webRequestBlocking: (.permissions | index("webRequestBlocking") != null)
  }' manifest.json > mv2-inventory.json

Step 2 - Walk the six migration sections

For each section, author one test per checklist item. The full per-item verification matrices and the Section 1 manifest / DNR / CSP code are in references/verification-cases.md.

The signature runtime test - the one migration "passes lint but breaks on first user" without - is the SW-survival probe. Keep it inline:

test('chrome.storage.local survives SW restart (35s idle)', async ({ context, extensionId }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  await sw.evaluate(() => chrome.storage.local.set({ migrationProbe: 'value' }));
  await new Promise(r => setTimeout(r, 35_000)); // idle past SW timeout

  // Wake the SW with a no-op evaluate; storage must survive
  const value = await sw.evaluate(async () => {
    const { migrationProbe } = await chrome.storage.local.get('migrationProbe');
    return migrationProbe;
  });
  expect(value).toBe('value');
});

The 35-second figure is from manifest-v3-test-surface-reference (Chrome auto-suspends idle SWs after ~30s per cr-mig-sw (opens in new window)).

Step 3 - Emit the checklist artifact

Write the per-extension checklist to tests/migration-mv3-checklist.md:

# MV3 Migration Checklist - <extension-name>

Generated: <YYYY-MM-DD>
Source MV2 inventory: tests/mv2-inventory.json

## Section 1 - Update the manifest
- [ ] `manifest_version === 3` (test: manifest.spec.ts > "manifest_version is 3")
- [ ] No host patterns in `permissions[]` (test: manifest.spec.ts > "no host patterns left")
- [ ] `web_accessible_resources` object-array shape (test: manifest.spec.ts > "WAR object-array shape")

## Section 2 - Migrate to a service worker
- [ ] `background.service_worker` single string; no `scripts`, no `persistent`
- [ ] No `document.` / `window.` / `XMLHttpRequest` in SW source
- [ ] No `localStorage` in SW source
- [ ] Listeners registered at top level (no addListener inside async)
- [ ] No `XMLHttpRequest` anywhere
- [ ] Storage survives 35s idle (test: sw-survival.spec.ts)
- [ ] No `setTimeout` / `setInterval` in SW source
- [ ] Keep-alive (if present) gated on managed policy

## Section 3 - Update API calls
- [ ] No `tabs.executeScript` / `tabs.insertCSS` / `tabs.removeCSS`
- [ ] No `browser_action` / `page_action` (Chromium); `action` present
- [ ] No `chrome.extension.getBackgroundPage()`
- [ ] `web-ext lint` clean

## Section 4 - Replace blocking web request listeners
- [ ] No `webRequestBlocking` in `permissions[]`
- [ ] DNR `rule_resources[]` valid shape (if blocking needed)

## Section 5 - Improve extension security
- [ ] No `eval` / `new Function` / string-form setTimeout
- [ ] No remote `<script src=>` in extension HTML
- [ ] CSP is object shape, no `unsafe-eval`, no remote hosts

## Section 6 - Firefox divergences (skip if Chromium-only)
- [ ] `browser_specific_settings.gecko.id` present
- [ ] No `applications` key (renamed to `browser_specific_settings`)
- [ ] No `web_accessible_resources[].use_dynamic_url` (Chromium-only)
- [ ] `page_action` decision documented (Firefox retain / Chromium drop)
- [ ] Firefox 127+ install-prompt host-permission behavior tested

Verify: couple the checklist with a parallel Vitest / Playwright spec that automates each item, then gate CI on both files passing. If the checklist has a cell with no backing test, the migration is unproven for that cell - author the missing test before merging, never check the box by hand.

Anti-patterns

Limitations

• Static-grep is heuristic. Tools like setTimeout("...") and eval can be obfuscated; the grep tests catch the common cases but should be paired with bundler-level AST scans for production confidence.
• DNR rule semantics are not equivalence-tested against the old webRequest listeners - the checklist verifies shape, not that the new rules drop / modify the same requests. Behavior equivalence requires a separate test against representative traffic.
• Firefox 126 vs 127 host-permission behavior is a hard split per ff-mig (opens in new window); the checklist treats 127+ as canonical and notes 126- as a documented caveat rather than a separate test cell.
• web_accessible_resources.use_dynamic_url isn't covered by Firefox's web-ext lint rules (the key is Chromium-only per ff-mig (opens in new window)); the Firefox divergence test must check manifest shape directly.
• Keep-alive policy enforcement is server-side. Per cr-mig-sw (opens in new window), Chrome "reserves the right to take action" against abusive keep-alives - there is no client-detectable signal, so the test only verifies the gate, not enforcement.

References

• Chrome - Manifest V3 migration checklist (the six-section master list this builder walks) - cr-checklist (opens in new window).
• Chrome - Manifest V3 migration overview (baseline platform support, remote-code restriction quote) - cr-mig-overview (opens in new window).
• Chrome - Migrate to a service worker (SW lifecycle, alarms, keep-alive policy) - cr-mig-sw (opens in new window).
• Chrome - Update the manifest (field-level renames, WAR object shape) - cr-manifest (opens in new window).
• Firefox / Extension Workshop - Manifest V3 migration guide (divergence cells, host-permission install-prompt behavior, browser_specific_settings rename) - ff-mig (opens in new window).
• Per-section verification matrices + worked test code (Section 1 manifest, DNR, CSP, publication gates) - references/verification-cases.md.
• Composes: manifest-v3-test-surface-reference, web-ext-cli-mozilla, chrome-extension-test-loader.
• Sibling builder: extension-storage-test-author.