extension-storage-test-author

Overview

chrome.storage has four areas with non-overlapping quotas, persistence semantics, and enterprise-policy posture. Picking the wrong one is a class of bug the type checker can't catch: storage.sync silently rejects writes past the 100 KB total or 8 KB per-item limit per Chrome storage reference; storage.session evaporates on browser restart per cr-storage; storage.managed is read-only by definition and throws on write per MDN WebExtensions storage.

This skill emits the test suite that proves the right area was chosen, the quota gates fire on the documented thresholds, and the storage.onChanged payload shape matches across all writing code paths. The output is a Vitest / Playwright spec file the extension ships in its test suite.

Composes with:

• manifest-v3-test-surface-reference - for the SW-runtime restriction that bans localStorage and forces all persistent state into chrome.storage.*.
• playwright-extension-fixtures - the fixture that loads the extension so the spec can call into chrome.storage.* from a service-worker context.
• mv2-to-mv3-migration-test-checklist - Section 2 of that checklist forces every localStorage call through this skill's output.

For Playwright-driven MV3 popup / content-script fixtures see qa-modern-web/browser-extension-tests. That skill covers the chrome.storage usage assertions; this builder covers the suite design - area selection, quota gates, event-payload conformance, multi-area isolation.

When to use

• A new extension is deciding local vs sync vs session - generate the decision-matrix test that proves the choice.
• Migrating from localStorage to chrome.storage.local per the MV3 service-worker rules - emit the equivalence test.
• A user-facing bug ("my settings disappeared") that may be a quota-exceeded silent drop on storage.sync - author the quota-boundary test that catches it.
• Adding an enterprise-policy storage.managed read path - emit the read-only-error test plus the policy-fixture loader.

Workflow

Step 1 - Inventory the access pattern

For each storage call in the extension, capture three facts:

grep -rn 'chrome\.storage\.\|browser\.storage\.' \
  --include='*.{ts,js,tsx,jsx}' src/ \
  > storage-access-inventory.txt

Step 2 - Pick the area per the decision matrix

The decision is driven by the four facts in Step 1 and the constants in cr-storage:

storage.sync also has the write-throughput caps per cr-storage: MAX_ITEMS = 512, MAX_WRITE_OPERATIONS_PER_MINUTE = 120, MAX_WRITE_OPERATIONS_PER_HOUR = 1,800.

Per cr-storage: "MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE for storage.sync is deprecated: 'The storage.sync API no longer has a sustained write operation quota.'" - assertions referencing this constant should be removed.

Emit a decision-matrix test:

import manifest from '../dist/manifest.json';

describe('storage area selection', () => {
  it('uses storage.sync only for user-preference-sized data', () => {
    // grep'd inventory; verify the sync writes are all < 8 KB
    const syncCalls = readStorageInventory().filter(c => c.area === 'sync');
    for (const c of syncCalls) {
      expect(c.maxBytes).toBeLessThan(8 * 1024); // QUOTA_BYTES_PER_ITEM
    }
  });

  it('does not use storage.session for data needed across browser restart', () => {
    const sessionCalls = readStorageInventory().filter(c => c.area === 'session');
    for (const c of sessionCalls) {
      expect(c.requiresPersistence).toBe(false);
    }
  });
});

Step 3 - Quota-exceeded behavior tests

Per cr-storage, quota-exceeded writes "fail immediately and set" runtime.lastError (callback form) or "reject the Promise" (async form). The test must drive both paths.

Worked test - storage.sync per-item quota (8,192 bytes):

test('storage.sync rejects on per-item quota exceeded', async ({ context }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  const result = await sw.evaluate(async () => {
    const oversized = 'x'.repeat(9 * 1024); // 9 KB > 8 KB limit
    try {
      await chrome.storage.sync.set({ big: oversized });
      return { ok: true };
    } catch (e: any) {
      return { ok: false, message: e.message };
    }
  });

  expect(result.ok).toBe(false);
  // Per cr-storage the exact message is unstable; assert quota-shaped text
  expect(result.message).toMatch(/quota|QUOTA_BYTES/i);
});

Worked test - storage.sync total-quota (102,400 bytes):

test('storage.sync rejects past total-quota (~100 KB)', async ({ context }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  const result = await sw.evaluate(async () => {
    // 13 items × 8 KB = 104 KB > 102.4 KB total per QUOTA_BYTES
    const batch: Record<string, string> = {};
    const chunk = 'x'.repeat(7.9 * 1024); // just under per-item cap
    for (let i = 0; i < 13; i++) batch[`k${i}`] = chunk;
    try {
      await chrome.storage.sync.set(batch);
      return { ok: true };
    } catch (e: any) {
      return { ok: false, message: e.message };
    }
  });

  expect(result.ok).toBe(false);
});

Worked test - callback-path equivalence (per cr-storage, both forms must observe quota):

test('storage.sync callback path also sets runtime.lastError on quota', async ({ context }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  const err = await sw.evaluate(() => new Promise<string | null>(resolve => {
    const oversized = 'x'.repeat(9 * 1024);
    chrome.storage.sync.set({ big: oversized }, () => {
      resolve(chrome.runtime.lastError?.message ?? null);
    });
  }));

  expect(err).not.toBeNull();
  expect(err).toMatch(/quota|QUOTA_BYTES/i);
});

Step 4 - MAX_ITEMS and write-throughput tests

Per cr-storage, storage.sync.MAX_ITEMS = 512. Write 513 unique keys, assert the 513th fails:

test('storage.sync rejects past MAX_ITEMS (512)', async ({ context }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  const result = await sw.evaluate(async () => {
    for (let i = 0; i < 512; i++) {
      await chrome.storage.sync.set({ [`k${i}`]: '1' });
    }
    try {
      await chrome.storage.sync.set({ k512: '1' });
      return { ok: true };
    } catch (e: any) {
      return { ok: false };
    }
  });

  expect(result.ok).toBe(false);
});

Per-minute throughput (120 writes/min per cr-storage) is harder to test deterministically; the conservative path is to assert the extension's own write-batching logic stays well below the cap rather than to drive the cap itself.

Step 5 - storage.onChanged event-payload shape

Per cr-storage, the signature is:

chrome.storage.onChanged.addListener((changes: object, areaName: string) => void)

with changes[key] = { oldValue?, newValue? }. Tests must assert both args + payload shape:

test('storage.onChanged fires with correct shape on local set', async ({ context }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  const event = await sw.evaluate(() => new Promise<any>(resolve => {
    chrome.storage.onChanged.addListener(function listener(changes, area) {
      chrome.storage.onChanged.removeListener(listener);
      resolve({ changes, area });
    });
    chrome.storage.local.set({ theme: 'dark' });
  }));

  expect(event.area).toBe('local');
  expect(event.changes.theme.newValue).toBe('dark');
  expect(event.changes.theme.oldValue).toBeUndefined(); // first write
});

Per mdn-storage, the listener receives the same shape on Firefox; the test runs cross-browser without modification.

Step 6 - Multi-area isolation test

A write to one area must not appear in another:

test('storage.local writes are invisible to storage.sync', async ({ context }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  const result = await sw.evaluate(async () => {
    await chrome.storage.local.set({ isolated: 'localValue' });
    const { isolated } = await chrome.storage.sync.get('isolated');
    return isolated;
  });

  expect(result).toBeUndefined();
});

Step 7 - storage.managed read-only enforcement

Per cr-storage and mdn-storage, storage.managed is read-only; any write attempt rejects. Test:

test('storage.managed rejects writes', async ({ context }) => {
  let [sw] = context.serviceWorkers();
  if (!sw) sw = await context.waitForEvent('serviceworker');

  const result = await sw.evaluate(async () => {
    try {
      await (chrome.storage as any).managed.set({ foo: 'bar' });
      return { ok: true };
    } catch (e: any) {
      return { ok: false, message: e.message };
    }
  });

  expect(result.ok).toBe(false);
});

Per mdn-storage: "Trying to modify this namespace results in an error."

Reading from storage.managed requires a deployed enterprise policy; in CI, mock the read by injecting an extensions.managedStorage policy via the OS-level mechanism (Windows registry / macOS plist / Linux JSON) - out of scope for this skill, but the assertion shape is:

const policy = await chrome.storage.managed.get('apiBaseUrl');
expect(policy.apiBaseUrl).toBe('https://policy-injected-url/');

Step 8 - Firefox-Chrome divergences

Per mdn-storage and cr-storage, the three observable divergences for tests:

Per mdn-storage, Firefox's storage.local "persists even when users clear browsing history/data (unlike localStorage)" - useful when authoring a clear-history regression test.

Step 9 - Emit the suite

Write tests/storage.spec.ts covering all eight cells from Steps 2 - 8. Pair with a YAML manifest mapping each spec to the matrix cell it covers:

# tests/storage-coverage.yaml
matrix:
  area_selection:
    - test: "uses storage.sync only for user-preference-sized data"
      ref: cr-storage QUOTA_BYTES_PER_ITEM
    - test: "no storage.session for cross-restart data"
      ref: cr-storage storage.session lifetime
  quota_exceeded:
    - test: "storage.sync per-item quota (>8 KB)"
      ref: cr-storage QUOTA_BYTES_PER_ITEM = 8192
    - test: "storage.sync total quota (>100 KB)"
      ref: cr-storage QUOTA_BYTES = 102400
    - test: "callback path sets runtime.lastError"
      ref: cr-storage "fail immediately and set"
  throughput:
    - test: "MAX_ITEMS = 512"
      ref: cr-storage MAX_ITEMS = 512
  events:
    - test: "onChanged shape (changes, areaName)"
      ref: cr-storage onChanged signature
  isolation:
    - test: "local invisible to sync"
      ref: cr-storage area separation
  managed:
    - test: "managed write rejects"
      ref: mdn-storage "modify this namespace results in an error"
  firefox_parity:
    - test: "storage.session MV3-only on Firefox"
      ref: mdn-storage storage.session MV3-only

CI gates on every cell having at least one passing test.

Worked example: a 4-row suite for a settings extension

For an extension that stores { theme: 'dark', apiKey: '...', tabsOpenCount: N }:

Each row produces one spec from the templates in Steps 2 - 7.

Note from mdn-storage: "Storage area is not encrypted, and shouldn't store confidential information." If the extension stores credentials at all, the suite must include a separate encryption-at-rest test (out of scope for this storage-API skill).

Anti-patterns

Limitations

• Sync round-trip requires sign-in. Tests asserting that a storage.sync.set propagates to a second device need both profiles signed in to the same Chrome / Firefox account - not testable in headless CI without account credentials.
• storage.session is MV3-only per cr-storage; tests in MV2 contexts must skip or fall back to storage.local with a cleanup hook.
• Throughput caps are server-side. Per cr-storage the MAX_WRITE_OPERATIONS_PER_HOUR = 1800 cap is enforced by sync servers, not the local client; tests can only assert the extension's own batching stays under the cap (Step 4 limitation).
• Encryption-at-rest is out of scope. Per mdn-storage, no area encrypts by default; auditing what the extension stores requires a separate threat-model test.
• storage.managed policy injection differs per OS (Windows registry, macOS plist, Linux JSON) - CI mocking is platform- specific and not covered by this skill's templates.
• Firefox storage.sync quotas are not enumerated as constants on the top-level mdn-storage page; Step 8's assertions assume Chrome-quota parity per the linked StorageArea sub-page - re-verify on Firefox stable before pinning.

References

• Chrome - chrome.storage API reference (quotas, deprecation notices, quota-exceeded behavior) - cr-storage.
• MDN - WebExtensions storage API (Firefox semantics, managed-area read-only quote, encryption caveat) - mdn-storage.
• Composes: manifest-v3-test-surface-reference, playwright-extension-fixtures, mv2-to-mv3-migration-test-checklist.
• Sibling builder: mv2-to-mv3-migration-test-checklist.