@omega.js/desktop 0.1.0

package/dist/test/harness/main-entry.js

@@ -0,0 +1,494 @@
+// Main-process test harness — runs inside a spawned Electron main process.
+//
+// Started by ../runners/electron.js with:
+//   electron <em>/dist/test/harness/main-entry.js -- --suites <json>
+//
+// Reports results to the parent runner via stdout JSON-lines:
+//   { event: 'start',   name, total }
+//   { event: 'result',  name, passed, duration, error? }
+//   { event: 'skip',    name, reason }
+//   { event: 'end',     passed, failed, skipped }
+//
+// The parent runner reads stdout, renders the @omega.js/backend-style output, and the harness
+// exits 0 on success / 1 on any failure.
+
+const path = require('path');
+const { app, BrowserWindow, ipcMain } = require('electron');
+
+// macOS: suppress app activation BEFORE ready — launching a regular-policy app
+// steals keyboard focus app-wide even when no window is ever focused. This file
+// only initializes its Manager after whenReady (too late: activation fires when
+// the app finishes launching), so flip the accessory policy here at require time.
+// This process is always a test run (runners/electron.js sets OMEGA_TEST_MODE), so
+// the shared predicate needs no Manager. OMEGA_TEST_SHOW=1 opts back into normal
+// activation along with visible windows.
+if (process.platform === 'darwin' && require('../../utils/test-stealth.js')()) {
+  app.dock.hide();
+}
+
+// CDP endpoint for consumer suites that drive real browser automation against
+// the harness Electron (e.g. playwright-core connectOverCDP). Port 0 = an
+// OS-assigned loopback-only port; Chromium writes the resolved port to
+// DevToolsActivePort inside the userData dir that's CURRENT when the DevTools
+// server starts — captured here at require time, because Manager.initialize()
+// re-paths userData later (post-ready in this harness). runSuites() resolves
+// the port from that file and publishes it as process.env.OMEGA_CDP_PORT.
+if (!app.commandLine.hasSwitch('remote-debugging-port')) {
+  app.commandLine.appendSwitch('remote-debugging-port', '0');
+}
+const devtoolsPortDir = app.getPath('userData');
+
+// Suites to run come in via process.argv after `--`
+const argv = process.argv.slice(2);
+const sepIdx = argv.indexOf('--');
+const positional = sepIdx >= 0 ? argv.slice(sepIdx + 1) : argv;
+
+let suiteFiles = [];
+const suiteFlagIdx = positional.indexOf('--suites');
+if (suiteFlagIdx >= 0 && positional[suiteFlagIdx + 1]) {
+  try {
+    suiteFiles = JSON.parse(positional[suiteFlagIdx + 1]);
+  } catch (e) {
+    emit({ event: 'fatal', message: `Failed to parse --suites: ${e.message}` });
+    app.exit(1);
+  }
+}
+
+// Optional renderer suites — run in a hidden BrowserWindow after main suites finish.
+let rendererSuiteFiles = [];
+const rendererFlagIdx = positional.indexOf('--renderer-suites');
+if (rendererFlagIdx >= 0 && positional[rendererFlagIdx + 1]) {
+  try {
+    rendererSuiteFiles = JSON.parse(positional[rendererFlagIdx + 1]);
+  } catch (e) {
+    emit({ event: 'fatal', message: `Failed to parse --renderer-suites: ${e.message}` });
+    app.exit(1);
+  }
+}
+
+const filter = (() => {
+  const idx = positional.indexOf('--filter');
+  return idx >= 0 ? positional[idx + 1] : null;
+})();
+
+function emit(obj) {
+  process.stdout.write(`__EM_TEST__${JSON.stringify(obj)}\n`);
+}
+
+class SkipError extends Error {
+  constructor(reason) { super(reason); this.name = 'SkipError'; }
+}
+
+async function runSuites() {
+  // Publish the harness's resolved DevTools port (see the appendSwitch block at
+  // the top of this file) for suites to consume. OVERWRITES any inherited
+  // OMEGA_CDP_PORT — a value from the developer's shell points at their dev app,
+  // not at this harness. Best-effort short poll: the file is written when
+  // Chromium starts the DevTools server during app startup, normally well
+  // before whenReady resolves.
+  for (let i = 0; i < 20; i += 1) {
+    try {
+      const port = Number(require('fs').readFileSync(path.join(devtoolsPortDir, 'DevToolsActivePort'), 'utf8').split('\n')[0]);
+      if (port > 0) {
+        process.env.OMEGA_CDP_PORT = String(port);
+        break;
+      }
+    } catch (_e) { /* not written yet */ }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  const Manager = require('../../main.js');
+  const manager = new Manager();
+
+  // Test mode: load default config from @omega.js/desktop defaults (since the harness CWD won't have
+  // one), resolved for the desktop target via @omega.js/config, and skip window creation
+  // so we don't pop a UI during tests.
+  const fs = require('fs');
+  const JSON5 = require('json5');
+  const { loadConfig } = require('../../vendor/config/index.js');
+  const defaultConfig = loadConfig(path.join(__dirname, '..', '..', 'defaults'), 'desktop').config;
+
+  await manager.initialize(defaultConfig, { skipWindowCreation: true });
+
+  // Consumer-scheme containment. Main-layer suites exercise consumer code that
+  // loads `<brand.id>://` URLs (tab managers, internal pages), but the consumer's
+  // main.js — where the real protocol handler is registered — never runs in this
+  // harness. Chromium treats a load on an UNHANDLED scheme as an external
+  // protocol and hands it to the OS; if an installed copy of the app owns the
+  // scheme (e.g. /Applications/Brand.app on macOS), Launch Services LAUNCHES it
+  // mid-test-run. Two test-scoped layers:
+  //   1. A stub handler for the consumer's brand scheme on the default session —
+  //      brand:// loads commit in-process (blank page) instead of escaping.
+  //   2. Deny the 'openExternal' permission on every session (partitions
+  //      included) — no navigation can hand ANY scheme to the OS during tests.
+  try {
+    const { session, protocol } = require('electron');
+
+    const denyOpenExternal = (ses) => {
+      ses.setPermissionRequestHandler((_wc, permission, callback) => {
+        callback(permission !== 'openExternal');
+      });
+    };
+    denyOpenExternal(session.defaultSession);
+    app.on('session-created', denyOpenExternal);
+
+    // Raw JSON5 read is fine here — `brand` is a shared section, top-level in the raw file.
+    const consumerConfigPath = path.join(process.cwd(), 'config', 'omega.json5');
+    if (fs.existsSync(consumerConfigPath)) {
+      const brandId = (JSON5.parse(fs.readFileSync(consumerConfigPath, 'utf8')).brand || {}).id;
+      if (brandId && !protocol.isProtocolHandled(brandId)) {
+        protocol.handle(brandId, () => new Response('<!doctype html><html><body></body></html>', {
+          headers: { 'Content-Type': 'text/html' },
+        }));
+      }
+    }
+  } catch (e) {
+    console.log(`test harness: consumer-scheme containment failed — ${e.message}`);
+  }
+
+  const ctxBase = (state) => ({
+    expect: require('../assert.js'),
+    state,
+    layer: 'main',
+    manager,
+    skip(reason) { throw new SkipError(reason); },
+  });
+
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+
+  for (const file of suiteFiles) {
+    let mod;
+    try {
+      delete require.cache[require.resolve(file)];
+      mod = require(file);
+    } catch (e) {
+      emit({ event: 'result', name: file, passed: false, duration: 0, error: `Failed to load: ${e.message}` });
+      failed += 1;
+      continue;
+    }
+
+    if (Array.isArray(mod)) {
+      mod = { type: 'group', tests: mod };
+    }
+
+    if (mod.layer !== 'main') continue;
+
+    if (mod.skip) {
+      const reason = typeof mod.skip === 'string' ? mod.skip : 'skipped';
+      const count = Array.isArray(mod.tests) ? mod.tests.length : 1;
+      emit({ event: 'skip', name: mod.description || file, reason, count });
+      skipped += count;
+      continue;
+    }
+
+    if (mod.type === 'suite' || mod.type === 'group' || Array.isArray(mod.tests)) {
+      const result = await runSuite(mod, ctxBase, filter);
+      passed += result.passed;
+      failed += result.failed;
+      skipped += result.skipped;
+    } else {
+      const result = await runStandalone(mod, ctxBase, filter);
+      passed += result.passed;
+      failed += result.failed;
+      skipped += result.skipped;
+    }
+  }
+
+  // After main suites finish, optionally run renderer suites in a hidden BrowserWindow.
+  if (rendererSuiteFiles.length > 0) {
+    try {
+      const r = await runRendererSuites(rendererSuiteFiles, manager);
+      passed  += r.passed;
+      failed  += r.failed;
+      skipped += r.skipped;
+    } catch (e) {
+      emit({ event: 'fatal', message: `renderer harness: ${e.message}`, stack: e.stack });
+      failed += 1;
+    }
+  }
+
+  emit({ event: 'end', passed, failed, skipped });
+  app.exit(failed > 0 ? 1 : 0);
+}
+
+// Spawn a hidden BrowserWindow and run each renderer suite inside it. Each suite file is
+// loaded via require() in main, then its tests are serialized to { name, runSource } and
+// shipped over IPC for the renderer to reconstruct + execute.
+async function runRendererSuites(files, manager) {
+  // Serialize suites for transport. We can't ship functions directly via IPC, so we extract
+  // the function body of each test's `run` and ship that as a string. The renderer rebuilds
+  // it with `new Function('ctx', body)`.
+  const suites = [];
+  for (const file of files) {
+    let mod;
+    try {
+      delete require.cache[require.resolve(file)];
+      mod = require(file);
+    } catch (e) {
+      emit({ event: 'result', name: file, passed: false, duration: 0, error: `Failed to load: ${e.message}` });
+      continue;
+    }
+
+    if (Array.isArray(mod)) mod = { type: 'group', tests: mod };
+    if (mod.layer !== 'renderer') continue;
+    if (mod.skip) {
+      const reason = typeof mod.skip === 'string' ? mod.skip : 'skipped';
+      const count = Array.isArray(mod.tests) ? mod.tests.length : 1;
+      emit({ event: 'skip', name: mod.description || file, reason, count });
+      continue;
+    }
+
+    const tests = (mod.tests || []).map((t) => ({
+      name:    t.name,
+      skip:    t.skip,
+      timeout: t.timeout,
+      runSource: extractFnBody(t.run),
+    }));
+
+    suites.push({
+      description: mod.description || path.basename(file),
+      isGroup:     mod.type === 'group',
+      timeout:     mod.timeout,
+      tests,
+    });
+  }
+
+  if (suites.length === 0) {
+    return { passed: 0, failed: 0, skipped: 0 };
+  }
+
+  const harnessDir = __dirname;
+  // Tell the renderer-preload (running in the BrowserWindow's preload) where to
+  // require() the renderer Manager from. We resolve by absolute path because the
+  // preload runs with the renderer's module resolution scope, not main's.
+  process.env.OMEGA_TEST_RENDERER_MANAGER_PATH = path.resolve(__dirname, '..', '..', 'renderer.js');
+
+  // Register test-only IPC channels so renderer-layer tests can verify round-trip
+  // behavior end-to-end (renderer.invoke → main handler → response). Idempotent:
+  // unregister first in case a previous renderer suite registered the same channel.
+  try { ipcMain.removeHandler('desktop:__test:echo'); } catch (_) { /* ignore */ }
+  ipcMain.handle('desktop:__test:echo', (_evt, payload) => ({ echoed: payload, ts: Date.now() }));
+  // Forwarded log capture — renderer logger.log(...) sends 'desktop:log:forward'; we
+  // accumulate the most recent payload so the renderer test can verify it landed.
+  global.__emTestLastForwardedLog = null;
+  ipcMain.removeAllListeners('desktop:__test:forwarded-log-tap');
+  ipcMain.on('desktop:log:forward', (_evt, payload) => {
+    global.__emTestLastForwardedLog = payload;
+  });
+  // Test-only handler the renderer can call to read back the most recently
+  // forwarded log payload. Returns null if none yet.
+  try { ipcMain.removeHandler('desktop:__test:read-last-log'); } catch (_) { /* ignore */ }
+  ipcMain.handle('desktop:__test:read-last-log', () => global.__emTestLastForwardedLog);
+  // Analytics sender tap ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)):
+  // renderer-originated omega.analytics() calls forward over IPC and must fire
+  // through main's ONE sender, so a renderer suite needs to read back what that
+  // sender was handed. The harness boots with no GA credentials (the sender is
+  // disabled), so enable it with harness ones — and replace the Measurement
+  // Protocol POST with a recorder FIRST, because a test run must never reach a
+  // real GA property. Everything upstream of that one transport call is the real
+  // path: the catalog resolution, main's client id, main's session enrichment.
+  //
+  // The recorder builds the WIRE payload the way the transport does (the same
+  // shared `core.buildPayload` the real `_send` calls, with the sender's own
+  // identity fields), so a suite asserts on `client_id` as GA would receive it
+  // rather than on a field the tap made up.
+  const analyticsCore = require('../../vendor/analytics/core.js');
+  global.__emTestAnalyticsSends = [];
+  manager.analytics.shutdown();
+  manager.analytics._send = (descriptor) => {
+    global.__emTestAnalyticsSends.push({
+      provider: descriptor.provider,
+      name:     descriptor.name,
+      payload:  descriptor.payload,
+      body:     analyticsCore.buildPayload({
+        clientId:       manager.analytics._clientId,
+        userId:         manager.analytics._userId,
+        userProperties: manager.analytics._userProperties,
+        eventName:      descriptor.name,
+        params:         descriptor.payload,
+      }),
+    });
+    return true;
+  };
+  process.env.GOOGLE_ANALYTICS_SECRET = 'harness-secret';
+  manager.config.analytics = { providers: { google: { id: 'G-HARNESS1' } } };
+  manager.analytics.initialize(manager);
+  try { ipcMain.removeHandler('desktop:__test:read-analytics-sends'); } catch (_) { /* ignore */ }
+  ipcMain.handle('desktop:__test:read-analytics-sends', () => global.__emTestAnalyticsSends);
+  const win = new BrowserWindow({
+    show:           false,
+    width:          800,
+    height:         600,
+    webPreferences: {
+      preload:           path.join(harnessDir, 'renderer-preload.js'),
+      contextIsolation:  true,
+      nodeIntegration:   false,
+      sandbox:           false,
+    },
+  });
+
+  return new Promise((resolve, reject) => {
+    const counts = { passed: 0, failed: 0, skipped: 0 };
+    let resolved = false;
+    const finish = (val, err) => {
+      if (resolved) return;
+      resolved = true;
+      try { win.destroy(); } catch (_e) { /* noop */ }
+      ipcMain.removeAllListeners('__emTest:ready');
+      ipcMain.removeAllListeners('__emTest:result');
+      if (err) reject(err); else resolve(val);
+    };
+
+    ipcMain.on('__emTest:ready', () => {
+      win.webContents.send('__emTest:suites', suites);
+    });
+
+    ipcMain.on('__emTest:result', (_e, evt) => {
+      // Forward verbatim to stdout — same envelope as main-process events.
+      emit(evt);
+      if (evt.event === 'result') {
+        if (evt.passed) counts.passed += 1;
+        else            counts.failed += 1;
+      } else if (evt.event === 'skip') {
+        counts.skipped += (evt.count || 1);
+      } else if (evt.event === 'end') {
+        finish(counts);
+      } else if (evt.event === 'fatal') {
+        counts.failed += 1;
+        finish(counts);
+      }
+    });
+
+    win.webContents.once('did-fail-load', (_e, code, desc) => {
+      finish(null, new Error(`renderer load failed: ${desc} (${code})`));
+    });
+
+    win.loadFile(path.join(harnessDir, 'renderer.html')).catch((e) => finish(null, e));
+
+    // Belt-and-suspenders: hard timeout in case the renderer never emits 'end'.
+    setTimeout(() => finish(null, new Error('renderer harness timed out (no end event in 60s)')), 60000);
+  });
+}
+
+// Extract the body of a function as a string so it can be reconstructed in the renderer.
+// Preserves async semantics (the renderer wraps in `async () => { ... }`).
+function extractFnBody(fn) {
+  if (typeof fn !== 'function') return 'throw new Error("test has no run() function");';
+  const src = fn.toString();
+  // Match: `async (ctx) => { ... }` / `(ctx) => { ... }` / `function(ctx) { ... }` / `async function (ctx) { ... }`
+  const arrow = src.match(/^\s*async\s*\([^)]*\)\s*=>\s*\{([\s\S]*)\}\s*$/) || src.match(/^\s*\([^)]*\)\s*=>\s*\{([\s\S]*)\}\s*$/);
+  if (arrow) return arrow[1];
+  const named = src.match(/^\s*async\s+function\s*[a-zA-Z0-9_]*\s*\([^)]*\)\s*\{([\s\S]*)\}\s*$/) || src.match(/^\s*function\s*[a-zA-Z0-9_]*\s*\([^)]*\)\s*\{([\s\S]*)\}\s*$/);
+  if (named) return named[1];
+  // Single-expression arrow: `(ctx) => ctx.expect(...).toBe(...)`
+  const exprArrow = src.match(/^\s*async\s*\([^)]*\)\s*=>\s*([\s\S]+)$/) || src.match(/^\s*\([^)]*\)\s*=>\s*([\s\S]+)$/);
+  if (exprArrow) return `return ${exprArrow[1].trim()};`;
+  // Fallback: just inject the source as-is and hope for the best.
+  return `return (${src})(ctx);`;
+}
+
+async function runSuite(suite, ctxBase, filter) {
+  const description = suite.description || '(suite)';
+  const isGroup = suite.type === 'group';
+  const stopOnFailure = !isGroup && suite.stopOnFailure !== false;
+  const tests = suite.tests || [];
+
+  emit({ event: 'suite-start', name: description });
+
+  const state = {};
+  let passed = 0, failed = 0, skipped = 0;
+
+  for (let i = 0; i < tests.length; i += 1) {
+    const t = tests[i];
+    const name = t.name || `step-${i + 1}`;
+
+    if (filter && !name.includes(filter) && !description.includes(filter)) continue;
+
+    if (t.skip) {
+      emit({ event: 'skip', name: `${description} → ${name}`, reason: typeof t.skip === 'string' ? t.skip : 'skipped' });
+      skipped += 1;
+      continue;
+    }
+
+    const ctx = ctxBase(state);
+    const start = Date.now();
+    try {
+      const timeout = t.timeout || suite.timeout || 30000;
+      await Promise.race([
+        Promise.resolve(t.run(ctx)),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Test timeout')), timeout)),
+      ]);
+      const duration = Date.now() - start;
+      emit({ event: 'result', suite: description, name, passed: true, duration });
+      passed += 1;
+
+      if (t.cleanup) {
+        try { await t.cleanup(ctx); } catch (e) {
+          emit({ event: 'cleanup-warn', name, message: e.message });
+        }
+      }
+    } catch (e) {
+      const duration = Date.now() - start;
+      if (e.name === 'SkipError') {
+        emit({ event: 'skip', name: `${description} → ${name}`, reason: e.message });
+        skipped += 1;
+        continue;
+      }
+      emit({ event: 'result', suite: description, name, passed: false, duration, error: e.message });
+      failed += 1;
+      if (stopOnFailure) {
+        const remaining = tests.length - i - 1;
+        if (remaining > 0) {
+          emit({ event: 'suite-stopped', name: description, remaining });
+          skipped += remaining;
+        }
+        break;
+      }
+    }
+  }
+
+  if (suite.cleanup) {
+    try { await suite.cleanup(ctxBase(state)); }
+    catch (e) { emit({ event: 'cleanup-warn', name: description, message: e.message }); }
+  }
+
+  return { passed, failed, skipped };
+}
+
+async function runStandalone(mod, ctxBase, filter) {
+  const description = mod.description || '(test)';
+  if (filter && !description.includes(filter)) return { passed: 0, failed: 0, skipped: 0 };
+
+  const ctx = ctxBase({});
+  const start = Date.now();
+  try {
+    const timeout = mod.timeout || 30000;
+    await Promise.race([
+      Promise.resolve(mod.run(ctx)),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('Test timeout')), timeout)),
+    ]);
+    const duration = Date.now() - start;
+    emit({ event: 'result', name: description, passed: true, duration });
+    if (mod.cleanup) {
+      try { await mod.cleanup(ctx); } catch (e) {
+        emit({ event: 'cleanup-warn', name: description, message: e.message });
+      }
+    }
+    return { passed: 1, failed: 0, skipped: 0 };
+  } catch (e) {
+    const duration = Date.now() - start;
+    if (e.name === 'SkipError') {
+      emit({ event: 'skip', name: description, reason: e.message });
+      return { passed: 0, failed: 0, skipped: 1 };
+    }
+    emit({ event: 'result', name: description, passed: false, duration, error: e.message });
+    return { passed: 0, failed: 1, skipped: 0 };
+  }
+}
+
+app.whenReady().then(runSuites).catch((e) => {
+  emit({ event: 'fatal', message: e.message, stack: e.stack });
+  app.exit(1);
+});

package/dist/test/harness/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "desktop-test-harness",
+  "version": "0.0.0",
+  "private": true,
+  "main": "main-entry.js"
+}

package/dist/test/harness/renderer-entry.js

@@ -0,0 +1,173 @@
+// Renderer test-harness entry. Runs inside the hidden BrowserWindow.
+//
+// Lifecycle:
+//   1. window load → __emTest.ready()
+//   2. main sends suites via __emTest:suites
+//   3. renderer reconstructs each test fn via new Function('ctx', body), runs it sequentially
+//   4. emits { event, ... } for each result; emits { event: 'end' } when done
+//
+// Tests get a `ctx` object with:
+//   - expect: a tiny assert helper (chained, like the build/main layer)
+//   - skip(reason): throws a SkipError
+//   - state: per-suite shared object
+//   - layer: 'renderer'
+//
+// Test source is sent as a stringified function body. We reconstruct the function inside
+// the renderer with `new Function('ctx', body)`.
+
+(function () {
+  'use strict';
+
+  const log = (...args) => {
+    const el = document.getElementById('log');
+    if (el) el.textContent += args.join(' ') + '\n';
+  };
+
+  function emit(evt) {
+    try { window.__emTest.emit(evt); } catch (e) { /* harness gone */ }
+  }
+
+  // Tiny inline expect — mirrors src/test/assert.js minimal surface used by tests.
+  function expect(actual) {
+    return {
+      toBe(expected) {
+        if (actual !== expected) {
+          throw new Error(`expected ${JSON.stringify(actual)} to be ${JSON.stringify(expected)}`);
+        }
+      },
+      toEqual(expected) {
+        const a = JSON.stringify(actual);
+        const b = JSON.stringify(expected);
+        if (a !== b) throw new Error(`expected ${a} to equal ${b}`);
+      },
+      toBeDefined() {
+        if (actual === undefined) throw new Error(`expected value to be defined`);
+      },
+      toBeNull() {
+        if (actual !== null) throw new Error(`expected ${JSON.stringify(actual)} to be null`);
+      },
+      toBeTruthy() {
+        if (!actual) throw new Error(`expected ${JSON.stringify(actual)} to be truthy`);
+      },
+      toBeFalsy() {
+        if (actual) throw new Error(`expected ${JSON.stringify(actual)} to be falsy`);
+      },
+      toContain(needle) {
+        if (typeof actual === 'string') {
+          if (!actual.includes(needle)) throw new Error(`expected "${actual}" to contain "${needle}"`);
+        } else if (Array.isArray(actual)) {
+          if (!actual.includes(needle)) throw new Error(`expected array to contain ${JSON.stringify(needle)}`);
+        } else {
+          throw new Error(`toContain only supports string/array, got ${typeof actual}`);
+        }
+      },
+      toMatch(re) {
+        if (!re.test(actual)) throw new Error(`expected "${actual}" to match ${re}`);
+      },
+    };
+  }
+
+  class SkipError extends Error {
+    constructor(reason) { super(reason); this.name = 'SkipError'; }
+  }
+
+  function makeCtx(state) {
+    return {
+      expect,
+      state,
+      layer: 'renderer',
+      skip(reason) { throw new SkipError(reason || 'skipped at runtime'); },
+    };
+  }
+
+  async function runSuite(suite) {
+    const description = suite.description || '(suite)';
+    const isGroup     = suite.isGroup;
+    const stopOnFailure = !isGroup;
+    const tests       = suite.tests || [];
+
+    emit({ event: 'suite-start', name: description });
+
+    const state = {};
+    let passed = 0, failed = 0, skipped = 0;
+
+    for (let i = 0; i < tests.length; i += 1) {
+      const t = tests[i];
+      const name = t.name || `step-${i + 1}`;
+
+      if (t.skip) {
+        const reason = typeof t.skip === 'string' ? t.skip : 'skipped';
+        emit({ event: 'skip', name: `${description} → ${name}`, reason });
+        skipped += 1;
+        continue;
+      }
+
+      let fn;
+      try {
+        // eslint-disable-next-line no-new-func
+        fn = new Function('ctx', `return (async () => { ${t.runSource} })();`);
+      } catch (e) {
+        emit({ event: 'result', suite: description, name, passed: false, duration: 0, error: `Failed to compile: ${e.message}` });
+        failed += 1;
+        if (stopOnFailure) {
+          const remaining = tests.length - i - 1;
+          if (remaining > 0) emit({ event: 'suite-stopped', name: description, remaining });
+          skipped += remaining;
+          break;
+        }
+        continue;
+      }
+
+      const ctx = makeCtx(state);
+      const start = Date.now();
+      try {
+        const timeout = t.timeout || suite.timeout || 30000;
+        await Promise.race([
+          fn(ctx),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('Test timeout')), timeout)),
+        ]);
+        const duration = Date.now() - start;
+        emit({ event: 'result', suite: description, name, passed: true, duration });
+        passed += 1;
+      } catch (e) {
+        const duration = Date.now() - start;
+        if (e.name === 'SkipError') {
+          emit({ event: 'skip', name: `${description} → ${name}`, reason: e.message });
+          skipped += 1;
+          continue;
+        }
+        emit({ event: 'result', suite: description, name, passed: false, duration, error: e.message });
+        failed += 1;
+        if (stopOnFailure) {
+          const remaining = tests.length - i - 1;
+          if (remaining > 0) emit({ event: 'suite-stopped', name: description, remaining });
+          skipped += remaining;
+          break;
+        }
+      }
+    }
+
+    return { passed, failed, skipped };
+  }
+
+  async function runAll(suites) {
+    log(`Running ${suites.length} renderer suite(s)...`);
+    let passed = 0, failed = 0, skipped = 0;
+    for (const suite of suites) {
+      const r = await runSuite(suite);
+      passed  += r.passed;
+      failed  += r.failed;
+      skipped += r.skipped;
+    }
+    emit({ event: 'end', passed, failed, skipped });
+  }
+
+  window.__emTest.onSuites((suites) => {
+    runAll(suites).catch((e) => {
+      emit({ event: 'fatal', message: e.message, stack: e.stack });
+    });
+  });
+
+  // Signal ready as soon as the page is parsed.
+  window.__emTest.ready();
+})();