browser-extension-manager 1.3.49 → 1.4.0

package/dist/test/runner.js

@@ -0,0 +1,407 @@
+// Test runner — discovers + runs suites, reports BXM-style.
+//
+// Discovery: globs for `test/**/*.js` (recursively, excluding directories starting with `_`)
+// in two locations:
+//   1. The framework itself (browser-extension-manager/dist/test/suites/...) — default suites.
+//   2. The consumer project's CWD (./test/...) — consumer suites.
+//
+// Each test file is a CommonJS module that exports a test definition (see ./index.js).
+// Three forms supported:
+//
+//   - Standalone:  module.exports = { layer, description, run, cleanup, timeout, skip };
+//   - Suite:       module.exports = { type: 'suite', layer, description, tests: [...], cleanup, stopOnFailure };
+//   - Group:       module.exports = { type: 'group', layer, description, tests: [...], cleanup };
+//   - Array form:  module.exports = [ {name, run}, ... ];   // implicit group
+//
+// `tests[]` items are { name, run(ctx), cleanup?, skip?, timeout? }.
+//
+// Suites stop on first failure (sequential, share state). Groups run all tests regardless.
+//
+// Layers:
+//   - 'build'      runs in plain Node (this file).
+//   - 'background' spawns Chromium via runners/chromium.js, runs in the extension's service worker.
+//   - 'view'       runs in a Chromium tab loading the harness extension's popup/options/sidepanel HTML.
+//   - 'boot'       spawns Chromium with the consumer's actual built `dist/` loaded as unpacked.
+
+const path = require('path');
+const glob = require('glob').globSync;
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+
+const expect = require('./assert.js');
+
+// Chromium / boot runners are lazy-loaded so a missing puppeteer doesn't prevent build-layer
+// tests from running. The dispatch points below require() them only when those layers exist.
+
+class SkipError extends Error {
+  constructor(reason) { super(reason); this.name = 'SkipError'; }
+}
+
+async function run(options = {}) {
+  options.layer    = options.layer    || 'all';
+  options.filter   = options.filter   || null;
+  options.reporter = options.reporter || 'pretty';
+
+  const startTime = Date.now();
+
+  const sources = discoverTestFiles();
+
+  console.log('');
+  console.log(chalk.bold('  Browser Extension Manager Tests'));
+
+  const results = { passed: 0, failed: 0, skipped: 0, tests: [] };
+
+  if (sources.framework.length > 0) {
+    console.log('');
+    console.log(chalk.bold('  Framework Tests'));
+    await runSource(sources.framework, 'framework', options, results);
+  }
+
+  if (sources.project.length > 0) {
+    console.log('');
+    console.log(chalk.bold('  Project Tests'));
+    await runSource(sources.project, 'project', options, results);
+  }
+
+  if (sources.framework.length === 0 && sources.project.length === 0) {
+    console.log(chalk.gray('  No test files found.'));
+  }
+
+  reportResults(results, Date.now() - startTime);
+
+  return results;
+}
+
+async function runSource(files, source, options, results) {
+  // Partition by layer (peek at module.exports without invoking run functions).
+  const byLayer = { build: [], background: [], view: [], boot: [] };
+  for (const file of files) {
+    const layer = peekLayer(file) || 'build';
+    if (byLayer[layer]) byLayer[layer].push(file);
+  }
+
+  // Build layer — run inline.
+  if ((options.layer === 'all' || options.layer === 'build') && byLayer.build.length > 0) {
+    for (const file of byLayer.build) {
+      await runBuildFile(file, source, options, results);
+    }
+  }
+
+  // Background + view share one Chromium instance — background suites first, then view
+  // suites in tabs against the harness extension.
+  const wantsBackground = (options.layer === 'all' || options.layer === 'background') && byLayer.background.length > 0;
+  const wantsView       = (options.layer === 'all' || options.layer === 'view')       && byLayer.view.length       > 0;
+
+  if (wantsBackground || wantsView) {
+    let runChromiumTests;
+    try {
+      ({ runChromiumTests } = require('./runners/chromium.js'));
+    } catch (e) {
+      console.log(chalk.yellow(`    ○ background + view tests skipped (chromium runner not available: ${e.message})`));
+      const skipCount = (wantsBackground ? byLayer.background.length : 0)
+        + (wantsView ? byLayer.view.length : 0);
+      results.skipped += skipCount;
+    }
+    if (runChromiumTests) {
+      const projectRoot = process.cwd();
+      const counts = await runChromiumTests({
+        backgroundSuiteFiles: wantsBackground ? byLayer.background : [],
+        viewSuiteFiles:       wantsView       ? byLayer.view       : [],
+        filter: options.filter,
+        projectRoot,
+        bxmDistRoot: path.resolve(__dirname, '..'),
+      });
+      results.passed  += counts.passed;
+      results.failed  += counts.failed;
+      results.skipped += counts.skipped;
+    }
+  }
+
+  // Boot layer — spawn Chromium with the consumer's actual built `dist/` and inspect.
+  if ((options.layer === 'all' || options.layer === 'boot') && byLayer.boot.length > 0) {
+    await runBootLayer(byLayer.boot, source, options, results);
+  }
+}
+
+async function runBootLayer(files, source, options, results) {
+  // Aggregate every boot test (whether standalone or inside a suite) into one flat list.
+  // The boot harness runs them sequentially in a single Chromium process to keep startup
+  // cost amortized. State doesn't carry across boot tests — each runs against a single
+  // shared `extension` from the consumer's actual built `dist/`.
+  const tests = [];
+
+  for (const file of files) {
+    let mod;
+    try {
+      delete require.cache[require.resolve(file)];
+      mod = require(file);
+    } catch (e) {
+      const rel = relativizePath(file, source);
+      console.log(chalk.red(`    ✗ ${rel}`));
+      console.log(chalk.red(`      Failed to load: ${e.message}`));
+      results.failed += 1;
+      continue;
+    }
+
+    if (Array.isArray(mod))                      mod = { type: 'group', tests: mod };
+    if (Array.isArray(mod.tests))                {/* multi-test */ }
+    else if (typeof mod.inspect === 'function')  mod = { tests: [mod] };
+
+    const baseDescription = mod.description || relativizePath(file, source);
+
+    for (const t of (mod.tests || [])) {
+      if (typeof t.inspect !== 'function') continue;
+      if (options.filter && !(t.description || baseDescription).includes(options.filter)) continue;
+      tests.push({
+        description: t.description || baseDescription,
+        timeout:     t.timeout || mod.timeout || 20000,
+        inspect:     t.inspect,
+      });
+    }
+  }
+
+  if (tests.length === 0) return;
+
+  let runBootTests;
+  try {
+    ({ runBootTests } = require('./runners/boot.js'));
+  } catch (e) {
+    console.log(chalk.yellow(`    ○ boot tests skipped (boot runner not available: ${e.message})`));
+    results.skipped += tests.length;
+    return;
+  }
+
+  console.log(chalk.cyan('    ⤷ boot tests (consumer dist/)'));
+
+  const projectRoot = process.cwd();
+  const counts = await runBootTests({
+    tests,
+    projectRoot,
+    bxmDistRoot: path.resolve(__dirname, '..'),
+  });
+  results.passed  += counts.passed;
+  results.failed  += counts.failed;
+  results.skipped += counts.skipped;
+}
+
+function peekLayer(file) {
+  try {
+    delete require.cache[require.resolve(file)];
+    const mod = require(file);
+    if (Array.isArray(mod)) return 'build';
+    return mod.layer || 'build';
+  } catch (e) {
+    return null;
+  }
+}
+
+async function runBuildFile(file, source, options, results) {
+  let mod;
+  try {
+    delete require.cache[require.resolve(file)];
+    mod = require(file);
+  } catch (e) {
+    const rel = relativizePath(file, source);
+    console.log(chalk.red(`    ✗ ${rel}`));
+    console.log(chalk.red(`      Failed to load: ${e.message}`));
+    results.failed += 1;
+    return;
+  }
+
+  if (Array.isArray(mod)) {
+    mod = { type: 'group', tests: mod };
+  }
+
+  const rel = relativizePath(file, source);
+
+  if (mod.skip) {
+    const reason = typeof mod.skip === 'string' ? mod.skip : '';
+    console.log(chalk.yellow(`    ○ ${mod.description || rel}`) + chalk.gray(` (skipped${reason ? ': ' + reason : ''})`));
+    const count = Array.isArray(mod.tests) ? mod.tests.length : 1;
+    results.skipped += count;
+    return;
+  }
+
+  if (mod.type === 'suite' || mod.type === 'group' || Array.isArray(mod.tests)) {
+    await runSuite(mod, rel, options, results);
+  } else {
+    await runStandalone(mod, rel, options, results);
+  }
+}
+
+async function runSuite(suite, rel, options, results) {
+  const description = suite.description || rel;
+  const isGroup = suite.type === 'group';
+  const stopOnFailure = !isGroup && suite.stopOnFailure !== false;
+  const tests = suite.tests || [];
+
+  console.log(chalk.cyan(`    ⤷ ${description}`));
+
+  const state = {};
+
+  for (let i = 0; i < tests.length; i += 1) {
+    const t = tests[i];
+    const name = t.name || `step-${i + 1}`;
+
+    if (options.filter && !name.includes(options.filter) && !description.includes(options.filter)) continue;
+
+    if (t.skip) {
+      const reason = typeof t.skip === 'string' ? t.skip : '';
+      console.log(chalk.yellow(`      ○ ${name}`) + chalk.gray(` (skipped${reason ? ': ' + reason : ''})`));
+      results.skipped += 1;
+      continue;
+    }
+
+    const ctx = createContext({ state, layer: suite.layer || 'build' });
+    const timeout = t.timeout || suite.timeout || 30000;
+
+    const start = Date.now();
+    try {
+      await Promise.race([
+        Promise.resolve(t.run(ctx)),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Test timeout')), timeout)),
+      ]);
+      const duration = Date.now() - start;
+      console.log(chalk.green(`      ✓ ${name}`) + chalk.gray(` (${duration}ms)`));
+      results.passed += 1;
+
+      if (t.cleanup) {
+        try { await t.cleanup(ctx); } catch (e) {
+          console.log(chalk.yellow(`        ⚠ Cleanup failed: ${e.message}`));
+        }
+      }
+    } catch (e) {
+      const duration = Date.now() - start;
+      if (e.name === 'SkipError') {
+        console.log(chalk.yellow(`      ○ ${name}`) + chalk.gray(` (skipped: ${e.message})`));
+        results.skipped += 1;
+        continue;
+      }
+      console.log(chalk.red(`      ✗ ${name}`) + chalk.gray(` (${duration}ms)`));
+      console.log(chalk.red(`        ${e.message || e}`));
+      results.failed += 1;
+
+      if (stopOnFailure) {
+        const remaining = tests.length - i - 1;
+        if (remaining > 0) {
+          console.log(chalk.yellow(`        Skipping ${remaining} remaining test(s) in suite`));
+          results.skipped += remaining;
+        }
+        break;
+      }
+    }
+  }
+
+  if (suite.cleanup) {
+    try {
+      const ctx = createContext({ state, layer: suite.layer || 'build' });
+      await suite.cleanup(ctx);
+    } catch (e) {
+      console.log(chalk.yellow(`      ⚠ Suite cleanup failed: ${e.message}`));
+    }
+  }
+}
+
+async function runStandalone(mod, rel, options, results) {
+  const description = mod.description || rel;
+  if (options.filter && !description.includes(options.filter)) return;
+
+  const ctx = createContext({ state: {}, layer: mod.layer || 'build' });
+  const timeout = mod.timeout || 30000;
+
+  const start = Date.now();
+  try {
+    await Promise.race([
+      Promise.resolve(mod.run(ctx)),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('Test timeout')), timeout)),
+    ]);
+    const duration = Date.now() - start;
+    console.log(chalk.green(`    ✓ ${description}`) + chalk.gray(` (${duration}ms)`));
+    results.passed += 1;
+
+    if (mod.cleanup) {
+      try { await mod.cleanup(ctx); } catch (e) {
+        console.log(chalk.yellow(`      ⚠ Cleanup failed: ${e.message}`));
+      }
+    }
+  } catch (e) {
+    const duration = Date.now() - start;
+    if (e.name === 'SkipError') {
+      console.log(chalk.yellow(`    ○ ${description}`) + chalk.gray(` (skipped: ${e.message})`));
+      results.skipped += 1;
+      return;
+    }
+    console.log(chalk.red(`    ✗ ${description}`) + chalk.gray(` (${duration}ms)`));
+    console.log(chalk.red(`      ${e.message || e}`));
+    results.failed += 1;
+  }
+}
+
+function createContext({ state, layer }) {
+  return {
+    expect,
+    state,
+    layer,
+    skip(reason) { throw new SkipError(reason || 'skipped at runtime'); },
+  };
+}
+
+function reportResults(results, durationMs) {
+  const total = results.passed + results.failed + results.skipped;
+  console.log('');
+  console.log('  ' + chalk.bold('Results'));
+  console.log(`    ${chalk.green(`${results.passed} passing`)}`);
+  if (results.failed > 0)  console.log(`    ${chalk.red(`${results.failed} failing`)}`);
+  if (results.skipped > 0) console.log(`    ${chalk.yellow(`${results.skipped} skipped`)}`);
+  console.log(chalk.gray(`\n    Total: ${total} tests in ${durationMs}ms\n`));
+}
+
+function discoverTestFiles() {
+  const framework = [];
+  const project = [];
+
+  // Detect whether we're running BXM's own framework self-tests, vs a consumer
+  // who installed BXM and is running their own tests. Used below to filter the
+  // boot/ layer of framework suites — those target BXM's internal fixture
+  // extension, so they only make sense when BXM tests itself.
+  const isFrameworkSelfTest = (() => {
+    try {
+      const cwdPkg = require(path.join(process.cwd(), 'package.json'));
+      return cwdPkg.name === 'browser-extension-manager';
+    } catch (_) { return false; }
+  })();
+
+  // Framework default suites (relative to this file: dist/test/runner.js).
+  // For consumers, we exclude boot/ — those suites assert on BXM's own fixture
+  // extension (BXM Fixture Consumer, #main-content, fixture:hello message) and
+  // would fail noisily when run against a real consumer's packaged extension.
+  // Consumers write their own boot tests under <cwd>/test/boot/.
+  const frameworkSuitesDir = path.join(__dirname, 'suites');
+  if (jetpack.exists(frameworkSuitesDir)) {
+    const ignore = ['_**'];
+    if (!isFrameworkSelfTest) ignore.push('boot/**');
+    glob('**/*.js', { cwd: frameworkSuitesDir, ignore }).sort().forEach((rel) => {
+      framework.push(path.join(frameworkSuitesDir, rel));
+    });
+  }
+
+  // Consumer project suites — CWD/test/**/*.js. Skip when running from inside the
+  // framework's own dist tree (where consumer-tests-dir === framework-tests-parent).
+  const projectTestsDir = path.join(process.cwd(), 'test');
+  if (jetpack.exists(projectTestsDir) && projectTestsDir !== path.dirname(frameworkSuitesDir)) {
+    glob('**/*.js', { cwd: projectTestsDir, ignore: ['_**'] }).sort().forEach((rel) => {
+      project.push(path.join(projectTestsDir, rel));
+    });
+  }
+
+  return { framework, project };
+}
+
+function relativizePath(file, source) {
+  if (source === 'framework') {
+    return path.relative(path.join(__dirname, 'suites'), file);
+  }
+  return path.relative(path.join(process.cwd(), 'test'), file);
+}
+
+module.exports = { run, SkipError };

package/dist/test/runners/boot.js

@@ -0,0 +1,201 @@
+// Boot-runner — spawns Chromium with the consumer's actual built `dist/` loaded
+// as an unpacked extension, runs `inspect` functions against the live extension,
+// then closes cleanly.
+//
+// Differences from runners/chromium.js:
+//   - chromium.js spawns the harness extension and tests BXM's framework surface.
+//   - boot.js spawns the CONSUMER'S `dist/` (their real production extension) and
+//     verifies it boots end-to-end: manifest is valid, SW starts, popup loads, etc.
+//
+// Why both? `background` + `view` layers cover framework / lib code fast. `boot`
+// layer covers integration — does the consumer's actual extension boot with their
+// real manifest + brand config + scaffolds? Replaces shell-level smoke tests.
+//
+// `inspect` functions receive { extension, page, expect, projectRoot } where:
+//   extension.id        — the loaded extension's chrome-extension://<id>
+//   extension.manifest  — parsed manifest.json
+//   extension.popupUrl  — chrome-extension://<id>/<action.default_popup>
+//   extension.optionsUrl— chrome-extension://<id>/<options_ui.page>
+//   extension.swTarget  — Puppeteer ServiceWorker target (may be null)
+//   page                — Puppeteer Page (fresh per test; popup not auto-loaded)
+//   projectRoot         — absolute path to the consumer project root
+//   expect              — same Jest-compatible expect() as build/background/view
+
+const path  = require('path');
+const fs    = require('fs');
+const chalk = require('chalk').default;
+
+async function runBootTests({ tests, projectRoot, bxmDistRoot }) {
+  if (tests.length === 0) return { passed: 0, failed: 0, skipped: 0 };
+
+  let puppeteer;
+  try {
+    puppeteer = require('puppeteer');
+  } catch (e) {
+    console.log(chalk.yellow(`    ○ boot tests skipped (puppeteer not installed)`));
+    return { passed: 0, failed: 0, skipped: tests.length };
+  }
+
+  // Locate the Chrome-loadable build of the consumer extension. BXM's gulp
+  // pipeline produces multiple outputs:
+  //   - `dist/`                       — intermediate (JSON5 manifest, raw bundles)
+  //   - `packaged/<browser>/raw/`     — per-browser, strict JSON manifest, Chrome-loadable
+  //   - `packaged/<browser>/<name>.zip` — store-upload zip
+  //
+  // Boot tests run against `packaged/chromium/raw/` because that's the directory
+  // a developer would point Chrome's "Load unpacked" at (and what zips for the
+  // Web Store). It's the actual production-equivalent surface.
+  //
+  // Discovery order:
+  //   1. BXM_TEST_BOOT_DIR (explicit absolute path) — full override
+  //   2. <projectRoot>/packaged/chromium/raw   — default for BXM consumers
+  //   3. <projectRoot>/dist                    — fallback for non-standard pipelines
+  //
+  // BXM's own framework boot tests use a fixture extension under
+  // src/test/fixtures/consumer-extension/dist (no `packaged/` step needed — the
+  // fixture is already strict JSON), so BXM_TEST_BOOT_PROJECT points there and
+  // the discovery falls through to `dist`.
+  const effectiveRoot = process.env.BXM_TEST_BOOT_PROJECT
+    ? path.resolve(process.env.BXM_TEST_BOOT_PROJECT)
+    : projectRoot;
+
+  const candidates = [];
+  if (process.env.BXM_TEST_BOOT_DIR) candidates.push(path.resolve(process.env.BXM_TEST_BOOT_DIR));
+  candidates.push(path.join(effectiveRoot, 'packaged', 'chromium', 'raw'));
+  candidates.push(path.join(effectiveRoot, 'dist'));
+
+  let consumerDist = null;
+  let manifestPath = null;
+  for (const dir of candidates) {
+    const mp = path.join(dir, 'manifest.json');
+    if (fs.existsSync(mp)) {
+      consumerDist = dir;
+      manifestPath = mp;
+      break;
+    }
+  }
+  if (!consumerDist) {
+    console.log(chalk.yellow(`    ○ boot tests skipped (no manifest.json found in any of:`));
+    for (const c of candidates) console.log(chalk.yellow(`        ${c}`));
+    console.log(chalk.yellow(`      — run \`npm run build\` first to produce packaged/chromium/raw/)`));
+    return { passed: 0, failed: 0, skipped: tests.length };
+  }
+
+  // Chrome requires manifest.json to be STRICT JSON (no comments, no trailing
+  // commas, no single quotes). If we matched a directory but its manifest is
+  // still JSON5, the user picked the wrong dir — surface that clearly. This is
+  // the difference between BXM's intermediate `dist/` (JSON5) and the packaged
+  // `packaged/chromium/raw/` (normalized JSON).
+  let manifestRaw;
+  try {
+    manifestRaw = fs.readFileSync(manifestPath, 'utf8');
+    JSON.parse(manifestRaw);
+  } catch (e) {
+    console.log(chalk.red(`    ✗ boot tests aborted: ${manifestPath} is not strict JSON.`));
+    console.log(chalk.gray(`      Chrome requires manifest.json to have no comments, no trailing commas, no single quotes.`));
+    console.log(chalk.gray(`      Parser error: ${e.message}`));
+    console.log(chalk.gray(`      If you see this, the runner picked an intermediate dist/ output instead of a`));
+    console.log(chalk.gray(`      packaged/<browser>/raw/ output. Run \`npm run build\` to produce the packaged dir,`));
+    console.log(chalk.gray(`      or set BXM_TEST_BOOT_DIR to the directory that has strict-JSON manifest.json.`));
+    return { passed: 0, failed: tests.length, skipped: 0 };
+  }
+  if (process.env.BXM_TEST_DEBUG) {
+    console.log(chalk.gray(`      [boot] loading extension from ${consumerDist}`));
+  }
+
+  const expect = require('../assert.js');
+  const counts = { passed: 0, failed: 0, skipped: 0 };
+
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: [
+      `--disable-extensions-except=${consumerDist}`,
+      `--load-extension=${consumerDist}`,
+      '--no-sandbox',
+      '--disable-dev-shm-usage',
+    ],
+  });
+
+  try {
+    // Discover the loaded extension. Most consumer extensions have an MV3 SW
+    // — wait up to 5s for it. If the consumer extension is service-worker-less
+    // (rare in MV3 but allowed for action-only extensions), we still get the
+    // chrome-extension://<id> via browser targets and the manifest gives us
+    // the popup URL.
+    const swTarget = await waitForTarget(browser, (t) => t.type() === 'service_worker' && t.url().startsWith('chrome-extension://'), 5000);
+
+    let extId;
+    let manifest;
+    if (swTarget) {
+      extId = swTarget.url().split('/')[2];
+    } else {
+      // No SW — find any chrome-extension target.
+      const anyExtTarget = browser.targets().find((t) => t.url().startsWith('chrome-extension://'));
+      if (!anyExtTarget) {
+        console.log(chalk.red(`    ✗ Boot aborted — Chromium loaded but no chrome-extension target appeared.`));
+        console.log(chalk.gray(`      Likely cause: the extension failed to load. Common reasons:`));
+        console.log(chalk.gray(`        - manifest.json missing required field (e.g. manifest_version: 3)`));
+        console.log(chalk.gray(`        - default_locale is set but _locales/<locale>/messages.json is missing`));
+        console.log(chalk.gray(`        - __MSG_*__ placeholders used without default_locale + _locales/`));
+        console.log(chalk.gray(`        - referenced files (background.service_worker, content_scripts) don't exist on disk`));
+        return { passed: 0, failed: tests.length, skipped: 0 };
+      }
+      extId = anyExtTarget.url().split('/')[2];
+    }
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (e) {
+      console.log(chalk.red(`    ✗ Boot aborted — failed to parse manifest: ${e.message}`));
+      return { passed: 0, failed: tests.length, skipped: 0 };
+    }
+
+    const popupRel   = (manifest.action && manifest.action.default_popup) || null;
+    const optionsRel = (manifest.options_ui && manifest.options_ui.page)  || (manifest.options_page || null);
+
+    const extension = {
+      id:         extId,
+      manifest,
+      swTarget,
+      popupUrl:   popupRel   ? `chrome-extension://${extId}/${popupRel}`   : null,
+      optionsUrl: optionsRel ? `chrome-extension://${extId}/${optionsRel}` : null,
+    };
+
+    for (const t of tests) {
+      const start = Date.now();
+      const page = await browser.newPage();
+      try {
+        await Promise.race([
+          t.inspect({ extension, page, expect, projectRoot: effectiveRoot }),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('Boot test timeout')), t.timeout || 20000)),
+        ]);
+        const duration = Date.now() - start;
+        console.log(chalk.green(`      ✓ ${t.description}`) + chalk.gray(` (${duration}ms)`));
+        counts.passed += 1;
+      } catch (e) {
+        const duration = Date.now() - start;
+        console.log(chalk.red(`      ✗ ${t.description}`) + chalk.gray(` (${duration}ms)`));
+        console.log(chalk.red(`        ${(e && e.message) || String(e)}`));
+        counts.failed += 1;
+      } finally {
+        try { await page.close(); } catch (_) { /* ignore */ }
+      }
+    }
+  } finally {
+    try { await browser.close(); } catch (_) { /* ignore */ }
+  }
+
+  return counts;
+}
+
+async function waitForTarget(browser, predicate, timeoutMs) {
+  const found = browser.targets().find(predicate);
+  if (found) return found;
+  return new Promise((resolve) => {
+    const done = (t) => { browser.off('targetcreated', handle); resolve(t); };
+    const handle = (t) => { if (predicate(t)) done(t); };
+    browser.on('targetcreated', handle);
+    setTimeout(() => done(null), timeoutMs);
+  });
+}
+
+module.exports = { runBootTests };