feuerwerk/tools/lib/harness.mjs

/**
 * Headless-Chromium harness for the check scripts (e2e.mjs, smoke-jumprun.mjs).
 *
 * Starts chromium with remote debugging, opens a CDP session and hands a set of helpers to
 * the body function. Widgets are located through `window.__gm.locate(text)` (installed by
 * the editor), so checks never depend on pixel coordinates.
 *
 *   await runChecks({ projectId, baseUrl, port, shotPrefix }, async (t) => { ... });
 *
 * The harness always waits for chromium to actually exit (a SwiftShader GPU process kept
 * rendering at full CPU once when only SIGTERM was sent) and exits with code 1 on failures.
 */
import { spawn } from 'node:child_process';
import { writeFileSync } from 'node:fs';

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

/** Structural equality for the small plain values the checks compare (arrays of ids, selections). */
export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);

/** Keys the checks press, with the codes Chromium needs to route them like a real keyboard. */
const KEYS = {
  Enter: { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 },
  Escape: { key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 },
  Space: { key: ' ', code: 'Space', windowsVirtualKeyCode: 32 },
  ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', windowsVirtualKeyCode: 37 },
  ArrowRight: { key: 'ArrowRight', code: 'ArrowRight', windowsVirtualKeyCode: 39 },
  Delete: { key: 'Delete', code: 'Delete', windowsVirtualKeyCode: 46 },
  a: { key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65 },
  z: { key: 'z', code: 'KeyZ', windowsVirtualKeyCode: 90 },
};

/** CDP modifier bitmask: 2 = Ctrl, 8 = Shift. */
const modifierBits = ({ ctrl = false, shift = false } = {}) => (ctrl ? 2 : 0) | (shift ? 8 : 0);

class CDP {
  constructor(ws) {
    this.ws = ws;
    this.id = 0;
    this.pending = new Map();
    this.listeners = [];
    ws.addEventListener('message', (ev) => {
      const msg = JSON.parse(ev.data);
      if (msg.id && this.pending.has(msg.id)) {
        const { resolve, reject } = this.pending.get(msg.id);
        this.pending.delete(msg.id);
        msg.error ? reject(new Error(msg.error.message)) : resolve(msg.result);
      } else if (msg.method) {
        for (const l of this.listeners) l(msg);
      }
    });
  }

  send(method, params = {}) {
    const id = ++this.id;
    this.ws.send(JSON.stringify({ id, method, params }));
    return new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
  }

  on(fn) {
    this.listeners.push(fn);
  }
}

async function waitForChrome(port) {
  for (let i = 0; i < 50; i++) {
    try {
      const res = await fetch(`http://127.0.0.1:${port}/json/version`);
      if (res.ok) return res.json();
    } catch {}
    await sleep(200);
  }
  throw new Error('chromium did not start');
}

/** The toolbox handed to a check body – everything a step needs to drive and inspect the editor. */
function makeTools({ cdp, projectId, baseUrl, consoleLog, check, shotPrefix }) {
  const evaluate = async (expression) => (await cdp.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true })).result.value;
  /** Evaluates an expression in the page and returns it as plain JSON; `undefined` comes back as null. */
  const json = async (expression) => JSON.parse(await evaluate(`JSON.stringify((${expression}) ?? null)`));
  const locate = async (text, last = false) => {
    const p = await evaluate(`window.__gm && window.__gm.locate(${JSON.stringify(text)}, ${last})`);
    if (!p) throw new Error(`widget with text "${text}" not found`);
    return p;
  };
  const shot = async (name) => {
    const { data } = await cdp.send('Page.captureScreenshot', { format: 'png' });
    writeFileSync(`/tmp/${shotPrefix}-${name}.png`, Buffer.from(data, 'base64'));
  };

  // --- mouse ---------------------------------------------------------------------------------

  const mouse = (type, x, y, button = 'left', extra = {}) =>
    cdp.send('Input.dispatchMouseEvent', { type, x, y, button, clickCount: type === 'mousePressed' || type === 'mouseReleased' ? 1 : 0, ...extra });
  const click = async (x, y, button = 'left', modifiers = {}) => {
    const extra = { modifiers: modifierBits(modifiers) };
    await mouse('mouseMoved', x, y);
    await mouse('mousePressed', x, y, button, extra);
    await mouse('mouseReleased', x, y, button, extra);
    await sleep(150);
  };
  const clickText = async (text, button = 'left') => {
    const p = await locate(text);
    await click(p.x, p.y, button);
  };
  const drag = async (x1, y1, x2, y2, steps = 12) => {
    await mouse('mouseMoved', x1, y1);
    await mouse('mousePressed', x1, y1);
    for (let i = 1; i <= steps; i++) {
      await mouse('mouseMoved', x1 + ((x2 - x1) * i) / steps, y1 + ((y2 - y1) * i) / steps, 'left', { buttons: 1 });
      await sleep(16);
    }
    await mouse('mouseReleased', x2, y2);
    await sleep(150);
  };

  // --- keyboard ------------------------------------------------------------------------------

  const keyEvent = (type, name, modifiers) => {
    const key = KEYS[name];
    if (!key) throw new Error(`unknown key "${name}"`);
    return cdp.send('Input.dispatchKeyEvent', { type, ...key, modifiers: modifierBits(modifiers) });
  };
  /** Press and release a key from `KEYS`, optionally with `{ ctrl, shift }`. */
  const press = async (name, modifiers = {}) => {
    await keyEvent('keyDown', name, modifiers);
    await keyEvent('keyUp', name, modifiers);
  };
  /** Hold a key for `ms` milliseconds (arrow keys while playing). */
  const holdKey = async (name, ms) => {
    await keyEvent('keyDown', name);
    await sleep(ms);
    await keyEvent('keyUp', name);
  };
  const typeText = async (text) => {
    for (const ch of text) await cdp.send('Input.insertText', { text: ch });
  };
  const undo = async () => {
    await press('z', { ctrl: true });
    await sleep(200);
  };
  const redo = async () => {
    await press('z', { ctrl: true, shift: true });
    await sleep(200);
  };

  // --- editor state --------------------------------------------------------------------------

  /** Selection, mode, save status and notice – the facts most checks look at. */
  const state = () => json('{ selection: __gm.state.selection, mode: __gm.state.mode, save: __gm.state.saveStatus, notice: __gm.state.notice }');
  const objects = () => json('__gm.state.activeScene.objects');
  const object = (id) => json(`__gm.state.activeScene.objects.find((o) => o.id === ${JSON.stringify(id)})`);
  const asset = (id) => json(`__gm.state.project.assets.find((a) => a.id === ${JSON.stringify(id)})`);
  const world = () => json('__gm.world()');
  const entity = async (objectId) => (await world()).entities.find((e) => e.objectId === objectId);
  const select = (selection) => evaluate(`__gm.state.select(${JSON.stringify(selection)})`);
  /**
   * Runs `body` (JavaScript source) against the page's model and previews the result, the way a
   * scrub or a command would – for putting the scene into a known state between checks.
   */
  const mutate = async (body) => {
    await evaluate(`(() => { ${body}; __gm.state.preview(); })()`);
    await sleep(200);
  };
  const play = async () => {
    await clickText('▶  Play');
    await sleep(300);
  };
  const stop = async () => {
    await press('Escape');
    await sleep(300);
  };

  // --- server ----------------------------------------------------------------------------------

  const api = async (route) => (await fetch(`${baseUrl}api/index.php?r=${route}`)).json();
  const sceneOf = (doc) => doc.project.assets.find((a) => a.type === 'scene');
  const exceptions = () => consoleLog.filter((l) => l.startsWith('EXCEPTION'));
  /** Opens the project and asserts the page came up cleanly with the test hook installed. */
  const navigate = async () => {
    await cdp.send('Page.navigate', { url: `${baseUrl}?project=${projectId}` });
    await sleep(4000);
    check('page loaded without exceptions', exceptions().length === 0, exceptions().join(' | '));
    check('debug hook present', Boolean(await evaluate('Boolean(window.__gm)')));
  };

  return {
    cdp, projectId, baseUrl, consoleLog, exceptions, check, sleep,
    evaluate, json, locate, shot,
    mouse, click, clickText, drag,
    press, holdKey, typeText, undo, redo,
    state, objects, object, asset, world, entity, select, mutate, play, stop,
    api, sceneOf, navigate,
  };
}

export async function runChecks(options, body) {
  const { projectId, baseUrl, port = 9333, shotPrefix = 'gm-e2e', width = 1280, height = 800 } = options;
  const chrome = spawn('chromium', [
    '--headless', '--no-sandbox', '--disable-gpu', '--use-gl=swiftshader', '--enable-unsafe-swiftshader',
    `--remote-debugging-port=${port}`, `--window-size=${width},${height}`, '--hide-scrollbars', 'about:blank',
  ], { stdio: 'ignore' });

  const consoleLog = [];
  let failures = 0;
  function check(name, ok, detail = '') {
    console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ' – ' + detail : ''}`);
    if (!ok) failures++;
  }

  try {
    await waitForChrome(port);
    const target = await (await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: 'PUT' })).json();
    const ws = new WebSocket(target.webSocketDebuggerUrl);
    await new Promise((r) => ws.addEventListener('open', r));
    const cdp = new CDP(ws);
    await cdp.send('Page.enable');
    await cdp.send('Runtime.enable');
    await cdp.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
    cdp.on((msg) => {
      if (msg.method === 'Runtime.consoleAPICalled') consoleLog.push(msg.params.args.map((a) => a.value ?? a.description).join(' '));
      if (msg.method === 'Runtime.exceptionThrown') consoleLog.push('EXCEPTION ' + (msg.params.exceptionDetails.exception?.description ?? msg.params.exceptionDetails.text));
    });
    await body(makeTools({ cdp, projectId, baseUrl, consoleLog, check, shotPrefix }));
    ws.close();
  } catch (error) {
    console.error(error);
    failures++;
  } finally {
    await new Promise((resolve) => {
      if (chrome.exitCode !== null) return resolve();
      const timer = setTimeout(() => chrome.kill('SIGKILL'), 5000);
      chrome.once('exit', () => { clearTimeout(timer); resolve(); });
      chrome.kill('SIGTERM');
    });
  }
  if (consoleLog.length) console.log('--- console ---\n' + consoleLog.slice(0, 20).join('\n'));
  console.log(failures ? `${failures} FAILED` : 'ALL PASSED');
  process.exit(failures ? 1 : 0);
}