351 lines
13 KiB
JavaScript
351 lines
13 KiB
JavaScript
// A zero-dependency Chrome DevTools Protocol driver for verifying the web client
|
|
// in a real browser.
|
|
//
|
|
// It launches the installed Google Chrome in headless mode and talks to it over
|
|
// the DevTools WebSocket, using only Node's built-in `fetch` and global
|
|
// `WebSocket` (Node 22+). There is deliberately no npm dependency: the UI
|
|
// verification a pipeline stage runs must work from a clean checkout with no
|
|
// install step and no network.
|
|
//
|
|
// Usage:
|
|
// const browser = await launchChrome(); // { port, close() }
|
|
// const page = await browser.openPage(url); // navigate + await load
|
|
// await page.fill("#url", "ws://127.0.0.1:8090/connect");
|
|
// await page.click("#connectBtn");
|
|
// await page.waitForSelector(".row-title");
|
|
// await page.screenshot("/path/to/out.png");
|
|
// await page.close(); await browser.close();
|
|
//
|
|
// Chrome path: CHROME_PATH, else the macOS app bundle, else `google-chrome`.
|
|
import { spawn } from "node:child_process";
|
|
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
|
import { tmpdir } from "node:os";
|
|
import { join } from "node:path";
|
|
|
|
const CHROME_CANDIDATES = [
|
|
process.env.CHROME_PATH,
|
|
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
|
|
"/Applications/Chromium.app/Contents/MacOS/Chromium",
|
|
"/usr/bin/google-chrome",
|
|
"/usr/bin/chromium",
|
|
].filter(Boolean);
|
|
|
|
async function resolveChrome() {
|
|
for (const candidate of CHROME_CANDIDATES) {
|
|
try {
|
|
await readFile(candidate);
|
|
return candidate;
|
|
} catch {
|
|
// try the next candidate
|
|
}
|
|
}
|
|
throw new Error(
|
|
"no Chrome/Chromium found; set CHROME_PATH to a browser binary to run UI verification",
|
|
);
|
|
}
|
|
|
|
/** Poll `check` until it returns a truthy value or the timeout elapses. */
|
|
export async function eventually(check, { timeout = 20000, interval = 100, what = "condition" } = {}) {
|
|
const deadline = Date.now() + timeout;
|
|
let lastError = null;
|
|
while (Date.now() < deadline) {
|
|
try {
|
|
const value = await check();
|
|
if (value) return value;
|
|
} catch (error) {
|
|
lastError = error;
|
|
}
|
|
await new Promise((resolve) => setTimeout(resolve, interval));
|
|
}
|
|
throw new Error(`timed out waiting for ${what}${lastError ? `: ${lastError.message}` : ""}`);
|
|
}
|
|
|
|
/** One CDP connection: id-matched commands plus method listeners. */
|
|
class Cdp {
|
|
constructor(ws) {
|
|
this.ws = ws;
|
|
this.nextId = 0;
|
|
this.pending = new Map();
|
|
this.listeners = new Map();
|
|
ws.addEventListener("message", (event) => {
|
|
const message = JSON.parse(event.data);
|
|
if (message.id != null) {
|
|
const entry = this.pending.get(message.id);
|
|
this.pending.delete(message.id);
|
|
if (!entry) return;
|
|
if (message.error) entry.reject(new Error(`${message.error.message}`));
|
|
else entry.resolve(message.result ?? {});
|
|
return;
|
|
}
|
|
for (const listener of this.listeners.get(message.method) ?? []) listener(message);
|
|
});
|
|
}
|
|
|
|
opened() {
|
|
if (this.ws.readyState === 1) return Promise.resolve();
|
|
return new Promise((resolve, reject) => {
|
|
this.ws.addEventListener("open", () => resolve(), { once: true });
|
|
this.ws.addEventListener("error", () => reject(new Error("devtools websocket failed")), {
|
|
once: true,
|
|
});
|
|
});
|
|
}
|
|
|
|
on(method, listener) {
|
|
const list = this.listeners.get(method) ?? [];
|
|
list.push(listener);
|
|
this.listeners.set(method, list);
|
|
}
|
|
|
|
send(method, params = {}, sessionId) {
|
|
const id = ++this.nextId;
|
|
const frame = { id, method, params };
|
|
if (sessionId) frame.sessionId = sessionId;
|
|
return new Promise((resolve, reject) => {
|
|
this.pending.set(id, { resolve, reject });
|
|
this.ws.send(JSON.stringify(frame));
|
|
});
|
|
}
|
|
|
|
close() {
|
|
try {
|
|
this.ws.close();
|
|
} catch {
|
|
// already gone
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Launch headless Chrome with a fresh profile and remote debugging on an
|
|
* ephemeral port (read back from the profile's `DevToolsActivePort`).
|
|
*/
|
|
export async function launchChrome({ width = 1440, height = 900, chromePath } = {}) {
|
|
const chrome = chromePath ?? (await resolveChrome());
|
|
const profile = await mkdtemp(join(tmpdir(), "pipelines-web-cdp-"));
|
|
const child = spawn(
|
|
chrome,
|
|
[
|
|
"--headless=new",
|
|
"--disable-gpu",
|
|
"--no-first-run",
|
|
"--no-default-browser-check",
|
|
"--disable-extensions",
|
|
"--hide-scrollbars",
|
|
"--mute-audio",
|
|
`--user-data-dir=${profile}`,
|
|
"--remote-debugging-port=0",
|
|
`--window-size=${width},${height}`,
|
|
"about:blank",
|
|
],
|
|
{ stdio: ["ignore", "ignore", "pipe"] },
|
|
);
|
|
let stderr = "";
|
|
child.stderr.on("data", (chunk) => {
|
|
stderr += chunk.toString();
|
|
});
|
|
|
|
const port = await eventually(
|
|
async () => {
|
|
if (child.exitCode != null) {
|
|
throw new Error(`chrome exited early (${child.exitCode}): ${stderr.trim().slice(-400)}`);
|
|
}
|
|
const text = await readFile(join(profile, "DevToolsActivePort"), "utf8").catch(() => "");
|
|
const first = text.split("\n")[0]?.trim();
|
|
return first ? Number(first) : 0;
|
|
},
|
|
{ what: "chrome devtools port", timeout: 30000 },
|
|
);
|
|
|
|
let cdp = null;
|
|
const openCdp = async () => {
|
|
if (cdp) return cdp;
|
|
const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json();
|
|
const ws = new WebSocket(version.webSocketDebuggerUrl);
|
|
cdp = new Cdp(ws);
|
|
await cdp.opened();
|
|
return cdp;
|
|
};
|
|
|
|
return {
|
|
port,
|
|
chrome,
|
|
async openPage(url, { width: w = width, height: h = height } = {}) {
|
|
const conn = await openCdp();
|
|
const { targetId } = await conn.send("Target.createTarget", { url: "about:blank" });
|
|
const { sessionId } = await conn.send("Target.attachToTarget", { targetId, flatten: true });
|
|
const session = (method, params) => conn.send(method, params, sessionId);
|
|
await session("Page.enable");
|
|
await session("Runtime.enable");
|
|
await session("Emulation.setDeviceMetricsOverride", {
|
|
width: w,
|
|
height: h,
|
|
deviceScaleFactor: 1,
|
|
mobile: false,
|
|
});
|
|
|
|
const api = {
|
|
targetId,
|
|
/** Emulate pointer capability only; this is not an OS keyboard test. */
|
|
async emulateTouch(enabled = true) {
|
|
await session("Emulation.setTouchEmulationEnabled", { enabled, maxTouchPoints: 1 });
|
|
},
|
|
/** Resize the emulated viewport at the driver's fixed device scale. */
|
|
async resize(width, height) {
|
|
await session("Emulation.setDeviceMetricsOverride", {
|
|
width,
|
|
height,
|
|
deviceScaleFactor: 1,
|
|
mobile: false,
|
|
});
|
|
},
|
|
async evaluate(expression) {
|
|
const result = await session("Runtime.evaluate", {
|
|
expression,
|
|
awaitPromise: true,
|
|
returnByValue: true,
|
|
});
|
|
if (result.exceptionDetails) {
|
|
const text =
|
|
result.exceptionDetails.exception?.description ??
|
|
result.exceptionDetails.text ??
|
|
"evaluation failed";
|
|
throw new Error(text);
|
|
}
|
|
return result.result?.value;
|
|
},
|
|
async goto(nextUrl) {
|
|
await session("Page.navigate", { url: nextUrl });
|
|
await eventually(
|
|
async () => (await api.evaluate("document.readyState")) === "complete",
|
|
{ what: `load of ${nextUrl}` },
|
|
);
|
|
},
|
|
/**
|
|
* Install a script that runs in every document created from now on, before
|
|
* the page's own scripts — the CDP hook a UI check uses to wrap a global
|
|
* (for example to record the page's WebSocket) before the app boots.
|
|
*/
|
|
async addInitScript(source) {
|
|
await session("Page.addScriptToEvaluateOnNewDocument", { source });
|
|
},
|
|
/** Set an input's value and fire input/change so the app sees it. */
|
|
async fill(selector, value) {
|
|
const ok = await api.evaluate(`(() => {
|
|
const el = document.querySelector(${JSON.stringify(selector)});
|
|
if (!el) return false;
|
|
el.focus();
|
|
el.value = ${JSON.stringify(value)};
|
|
el.dispatchEvent(new Event("input", { bubbles: true }));
|
|
el.dispatchEvent(new Event("change", { bubbles: true }));
|
|
return true;
|
|
})()`);
|
|
if (!ok) throw new Error(`fill: no element for ${selector}`);
|
|
},
|
|
async rect(selector) {
|
|
return api.evaluate(`(() => {
|
|
const el = document.querySelector(${JSON.stringify(selector)});
|
|
if (!el) return null;
|
|
// CSS smooth scrolling is asynchronous; measuring immediately after
|
|
// it can click outside the viewport instead of the target control.
|
|
el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
|
|
const r = el.getBoundingClientRect();
|
|
return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
|
|
})()`);
|
|
},
|
|
/** A real mouse click at the element's centre. */
|
|
async click(selector) {
|
|
const point = await api.rect(selector);
|
|
if (!point) throw new Error(`click: no element for ${selector}`);
|
|
const base = { x: point.x, y: point.y, button: "left", clickCount: 1 };
|
|
await session("Input.dispatchMouseEvent", { type: "mouseMoved", x: point.x, y: point.y });
|
|
await session("Input.dispatchMouseEvent", { type: "mousePressed", ...base });
|
|
await session("Input.dispatchMouseEvent", { type: "mouseReleased", ...base });
|
|
},
|
|
/** Click the first element matching `selector` whose text contains `text`. */
|
|
async clickText(selector, text) {
|
|
const found = await api.evaluate(`(() => {
|
|
const wanted = ${JSON.stringify(text)};
|
|
const all = [...document.querySelectorAll(${JSON.stringify(selector)})];
|
|
const el = all.find((node) => (node.textContent ?? "").includes(wanted));
|
|
if (!el) return false;
|
|
el.scrollIntoView({ block: "center", behavior: "instant" });
|
|
el.setAttribute("data-test-click", "1");
|
|
return true;
|
|
})()`);
|
|
if (!found) throw new Error(`clickText: no ${selector} containing ${JSON.stringify(text)}`);
|
|
await api.click("[data-test-click='1']");
|
|
await api.evaluate(
|
|
`document.querySelector("[data-test-click='1']")?.removeAttribute("data-test-click")`,
|
|
);
|
|
},
|
|
async waitForSelector(selector, { timeout = 20000 } = {}) {
|
|
return eventually(() => api.evaluate(`!!document.querySelector(${JSON.stringify(selector)})`), {
|
|
timeout,
|
|
what: selector,
|
|
});
|
|
},
|
|
async waitForText(text, { timeout = 20000 } = {}) {
|
|
return eventually(
|
|
() => api.evaluate(`document.body.innerText.includes(${JSON.stringify(text)})`),
|
|
{ timeout, what: `text ${JSON.stringify(text)}` },
|
|
);
|
|
},
|
|
/**
|
|
* Dispatch one real key event pair (Input.dispatchKeyEvent), so the page
|
|
* sees the same trusted Tab/Escape/Enter a keyboard operator produces.
|
|
*/
|
|
async pressKey(key, { shift = false } = {}) {
|
|
const keys = {
|
|
Tab: { code: "Tab", windowsVirtualKeyCode: 9 },
|
|
Escape: { code: "Escape", windowsVirtualKeyCode: 27 },
|
|
Enter: { code: "Enter", windowsVirtualKeyCode: 13, text: "\r", unmodifiedText: "\r" },
|
|
" ": { code: "Space", windowsVirtualKeyCode: 32, text: " ", unmodifiedText: " " },
|
|
ArrowDown: { code: "ArrowDown", windowsVirtualKeyCode: 40 },
|
|
ArrowUp: { code: "ArrowUp", windowsVirtualKeyCode: 38 },
|
|
};
|
|
const info = keys[key] ?? { code: key, windowsVirtualKeyCode: 0 };
|
|
const base = {
|
|
key,
|
|
code: info.code,
|
|
windowsVirtualKeyCode: info.windowsVirtualKeyCode,
|
|
nativeVirtualKeyCode: info.windowsVirtualKeyCode,
|
|
modifiers: shift ? 8 : 0,
|
|
...(info.text ? { text: info.text, unmodifiedText: info.unmodifiedText } : {}),
|
|
};
|
|
await session("Input.dispatchKeyEvent", { type: "keyDown", ...base });
|
|
await session("Input.dispatchKeyEvent", { type: "keyUp", ...base });
|
|
},
|
|
async text() {
|
|
return api.evaluate("document.body.innerText");
|
|
},
|
|
async screenshot(path) {
|
|
const { data } = await session("Page.captureScreenshot", { format: "png" });
|
|
await writeFile(path, Buffer.from(data, "base64"));
|
|
return path;
|
|
},
|
|
async close() {
|
|
await conn.send("Target.closeTarget", { targetId }).catch(() => {});
|
|
},
|
|
};
|
|
|
|
if (url) await api.goto(url);
|
|
return api;
|
|
},
|
|
async close() {
|
|
try {
|
|
await fetch(`http://127.0.0.1:${port}/json/close/${""}`).catch(() => {});
|
|
} catch {
|
|
// ignore
|
|
}
|
|
cdp?.close();
|
|
child.kill("SIGTERM");
|
|
await eventually(async () => child.exitCode != null || child.signalCode != null, {
|
|
timeout: 5000,
|
|
what: "chrome exit",
|
|
}).catch(() => {});
|
|
await rm(profile, { recursive: true, force: true }).catch(() => {});
|
|
},
|
|
};
|
|
}
|