ident

32.0 KB

1. // tests/browser/cdp.mjs — a tiny raw-CDP browser driver. ZERO npm dependencies:
2. // node's native WebSocket speaks the Chrome DevTools Protocol directly, so the
3. // real-browser tier needs nothing installed beyond `google-chrome` itself.
4. //
5. // Two connection modes (mission 073 gate 1):
6. // • default — launch a LOCAL `google-chrome --headless=new` on a free debug port.
7. // This is what the suites use: hermetic, no external dependency.
8. // • HL_CDP_URL=http://host:port — attach to an ALREADY-RUNNING Chrome instead
9. // (e.g. the creator's notebook at http://lisbeth.tailfd3886.ts.net:9223).
10. // Nothing is launched or killed in that mode; only the tabs we create are closed.
11. //
12. // Everything a browser test needs and nothing else: navigate, wait-for-selector,
13. // evaluate, REAL mouse/keyboard dispatch (Input domain, not synthetic .click()),
14. // full console + uncaught-exception capture, and teardown that leaves no process.
16. import { spawn } from 'node:child_process';
17. import { mkdtempSync, rmSync } from 'node:fs';
18. import { tmpdir } from 'node:os';
19. import { join } from 'node:path';
20. import { createConnection } from 'node:net';
21. // One definition of "is this port actually usable", shared with the fixture boot
22. // path — the whole of mission 285 is that the tier had two different answers to
23. // that question and neither was the one the kernel gives.
24. import { portBindable, whoHolds } from './ports.mjs';
26. const CHROME_CANDIDATES = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser'];
28. export function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
30. async function portOpen(host, port) {
31. return new Promise(resolve => {
32. const sock = createConnection({ host, port });
33. const done = (ok) => { try { sock.destroy(); } catch {} resolve(ok); };
34. sock.setTimeout(400);
35. sock.on('connect', () => done(true));
36. sock.on('error', () => done(false));
37. sock.on('timeout', () => done(false));
38. });
39. }
41. /**
42. * Wait until `http://host:port/json/version` answers, or throw.
43. *
44. * `giveUp` (mission 285) is asked on every turn for a reason to stop early: waiting
45. * out a full timeout for something that has already announced it will never arrive
46. * is how a port collision came to look like a twenty-second test failure.
47. */
48. async function waitForEndpoint(base, timeoutMs, label, giveUp = () => null) {
49. const deadline = Date.now() + timeoutMs;
50. let lastErr = 'no attempt';
51. while (Date.now() < deadline) {
52. const stop = giveUp();
53. if (stop) throw new Error(stop);
54. try {
55. const res = await fetch(base + '/json/version', { signal: AbortSignal.timeout(2000) });
56. if (res.ok) return await res.json();
57. lastErr = 'HTTP ' + res.status;
58. } catch (e) { lastErr = String(e && e.message || e); }
59. await sleep(100);
60. }
61. throw new Error(`${label} not reachable at ${base} after ${timeoutMs}ms (${lastErr})`);
62. }
64. // --- the protocol connection ------------------------------------------------
66. class Conn {
67. constructor(ws) {
68. this.ws = ws;
69. this.nextId = 1;
70. this.pending = new Map();
71. this.listeners = [];
72. ws.addEventListener('message', (ev) => {
73. let msg;
74. try { msg = JSON.parse(typeof ev.data === 'string' ? ev.data : String(ev.data)); } catch { return; }
75. if (msg.id !== undefined && this.pending.has(msg.id)) {
76. const { resolve, reject } = this.pending.get(msg.id);
77. this.pending.delete(msg.id);
78. if (msg.error) reject(new Error(`${msg.error.message} (CDP ${msg.error.code})`));
79. else resolve(msg.result);
80. return;
81. }
82. for (const fn of this.listeners) fn(msg);
83. });
84. ws.addEventListener('close', () => {
85. for (const { reject } of this.pending.values()) reject(new Error('CDP connection closed'));
86. this.pending.clear();
87. });
88. }
89. onEvent(fn) { this.listeners.push(fn); return () => { this.listeners = this.listeners.filter(f => f !== fn); }; }
90. send(method, params = {}, sessionId) {
91. const id = this.nextId++;
92. const payload = { id, method, params };
93. if (sessionId) payload.sessionId = sessionId;
94. return new Promise((resolve, reject) => {
95. this.pending.set(id, { resolve, reject });
96. const t = setTimeout(() => {
97. if (this.pending.delete(id)) reject(new Error(`CDP timeout: ${method}`));
98. }, 20000);
99. const clear = () => clearTimeout(t);
100. const orig = this.pending.get(id);
101. this.pending.set(id, {
102. resolve: (v) => { clear(); orig.resolve(v); },
103. reject: (e) => { clear(); orig.reject(e); },
104. });
105. try { this.ws.send(JSON.stringify(payload)); } catch (e) { this.pending.delete(id); clear(); reject(e); }
106. });
107. }
108. close() { try { this.ws.close(); } catch {} }
109. }
111. async function connectWs(url) {
112. const ws = new WebSocket(url);
113. await new Promise((resolve, reject) => {
114. const to = setTimeout(() => reject(new Error('WebSocket open timeout: ' + url)), 10000);
115. ws.addEventListener('open', () => { clearTimeout(to); resolve(); }, { once: true });
116. ws.addEventListener('error', (e) => { clearTimeout(to); reject(new Error('WebSocket error: ' + url)); }, { once: true });
117. });
118. return new Conn(ws);
119. }
121. // --- Page -------------------------------------------------------------------
123. /**
124. * One tab. Owns its own console/exception log from the moment it is created,
125. * so nothing that happens during load can be missed.
126. */
127. export class Page {
128. constructor(browser, targetId, sessionId) {
129. this.browser = browser;
130. this.conn = browser.conn;
131. this.targetId = targetId;
132. this.sessionId = sessionId;
133. /** every console message AND uncaught exception, in arrival order */
134. this.messages = [];
135. this.closed = false;
136. }
138. send(method, params) { return this.conn.send(method, params, this.sessionId); }
140. /** console messages whose level is error/warning (what "console clean" means) */
141. problems() { return this.messages.filter(m => m.level === 'error' || m.level === 'warning'); }
143. /** Wait until a captured console message matches — the hydration/apply signals. */
144. async waitForConsoleMatch(re, { timeout = 10000 } = {}) {
145. const deadline = Date.now() + timeout;
146. while (Date.now() < deadline) {
147. const hit = this.messages.find(m => re.test(m.text));
148. if (hit) return hit;
149. await sleep(40);
150. }
151. throw new Error(`waitForConsoleMatch timed out (${re}). Console was:\n${this.dumpConsole()}`);
152. }
153. /** one-line rendering of everything captured — for failure details */
154. dumpConsole() { return this.messages.map(m => `[${m.level}] ${m.text}`).join('\n') || '(no console output)'; }
156. /**
157. * Run `source` in EVERY document this tab loads, BEFORE any page script.
158. * The only way to observe something the app sets up on load — mission 080 uses
159. * it to wrap `EventSource` and capture the raw SSE frames, so the assertion
160. * "this session was told nothing" is made against the wire, not the DOM.
161. */
162. addInitScript(source) { return this.send('Page.addScriptToEvaluateOnNewDocument', { source }); }
164. /**
165. * Capture every SSE frame this page receives into `window.__hlSSE`. Must be
166. * called BEFORE goto(); the wrapper subclasses the real EventSource, so the
167. * app's own `onmessage` is untouched and the transport is not simulated.
168. */
169. captureSse() {
170. return this.addInitScript(`(() => {
171. window.__hlSSE = [];
172. const Native = window.EventSource;
173. if (!Native) return;
174. window.EventSource = class extends Native {
175. constructor(...a) {
176. super(...a);
177. this.addEventListener('message', (e) => {
178. try { window.__hlSSE.push(JSON.parse(e.data)); } catch {}
179. });
180. }
181. };
182. })()`);
183. }
185. /** The SSE frames captured so far (see captureSse), oldest first. */
186. sseFrames() { return this.evaluate('window.__hlSSE || []'); }
188. /**
189. * Mission 090: capture every WebSocket frame this page RECEIVES (`__hlWs`) and
190. * every one it SENDS (`__hlWsOut`). Must be called BEFORE goto(); the wrapper
191. * subclasses the real WebSocket, so the app's own listeners are untouched and
192. * the transport is the real one — "this session was told exactly these bytes"
193. * is then an assertion about the wire, not about the DOM.
194. */
195. captureWs() {
196. return this.addInitScript(`(() => {
197. window.__hlWs = [];
198. window.__hlWsOut = [];
199. // when the LAST frame arrived, on the page's own clock — the ordering
200. // assertion "the DOM moved because of the frame" is made against this
201. window.__hlWsAt = 0;
202. // ...and when the first STATE PATCH arrived. A patch is an ARRAY frame (the
203. // protocol's onPatches); control frames — ack, pong, build — are objects,
204. // and since mission 133 an ack lands right AFTER the patch it belongs to,
205. // so __hlWsAt alone would put "the last frame" after the DOM had already
206. // moved for the patch.
207. window.__hlWsPatchAt = 0;
208. const Native = window.WebSocket;
209. if (!Native) return;
210. window.WebSocket = class extends Native {
211. constructor(...a) {
212. super(...a);
213. this.addEventListener('message', (e) => {
214. window.__hlWs.push(String(e.data));
215. window.__hlWsAt = performance.now();
216. if (!window.__hlWsPatchAt) {
217. try {
218. if (Array.isArray(JSON.parse(String(e.data)))) window.__hlWsPatchAt = window.__hlWsAt;
219. } catch {}
220. }
221. });
222. }
223. send(d) { window.__hlWsOut.push(String(d)); return super.send(d); }
224. };
225. })()`);
226. }
228. /** Frames this page RECEIVED / SENT since load (see captureWs), oldest first. */
229. wsFrames() { return this.evaluate('window.__hlWs || []'); }
230. wsSent() { return this.evaluate('window.__hlWsOut || []'); }
231. resetWs() { return this.evaluate('window.__hlWs = []'); }
233. /**
234. * Mission 093: the cookies the BROWSER holds for `urls`, as the browser sees
235. * them — including the httpOnly ones, which is the whole point. `document.cookie`
236. * cannot see an httpOnly cookie, so "the session id is not reachable from page
237. * script" and "the session id exists" can only be asserted together from here.
238. */
239. async cookies(urls) {
240. await this.send('Network.enable');
241. const { cookies } = await this.send('Network.getCookies', urls ? { urls } : {});
242. return cookies || [];
243. }
245. /** Cut THIS tab off the network, or let it back on (CDP emulation). */
246. async setOffline(offline) {
247. await this.send('Network.enable');
248. await this.send('Network.emulateNetworkConditions', {
249. offline, latency: 0, downloadThroughput: -1, uploadThroughput: -1,
250. });
251. }
253. /**
254. * Mission 081: serve an APP SHELL PRECACHE from the harness — the part mission
255. * 082's generated service worker will play (D29/§10.4: the `offline` target
256. * precaches the shell so a revisit boots with the network down).
257. *
258. * 081 owns the STATE layer — "with the network down the state comes from
259. * IndexedDB" — and that claim is only observable once a document can load at
260. * all. `snapshot` is a url → {status, contentType, body} map the test captured
261. * over HTTP while it was still online; those URLs are fulfilled from it, and
262. * EVERY OTHER request (`?__data=1`, `/emit`, `/events` — all the data
263. * endpoints) is passed on to the network, which is exactly where it dies. So
264. * the shell is precached and the data is genuinely unreachable, which is the
265. * situation §10.2 describes.
266. *
267. * Chrome's own HTTP cache cannot stand in for this: a response replayed
268. * through `Fetch.continueResponse` is not stored in the disk cache (measured),
269. * and `Page.reload` deliberately revalidates, so it fails offline either way.
270. */
271. async servePrecache(snapshot) {
272. this._precache = snapshot;
273. await this.send('Fetch.enable', { patterns: [{ urlPattern: '*' }] });
274. }
276. /** Stop answering from the precache and let every request reach the network. */
277. async stopPrecache() {
278. this._precache = null;
279. await this.send('Fetch.enable', { patterns: [{ urlPattern: '*/favicon.ico' }] });
280. }
282. /**
283. * Mission 087 (gate 2): capture EVERY request the page makes, from the browser
284. * itself. `Network.requestWillBeSent` fires for navigations, subresources,
285. * `fetch`/XHR and beacons alike, so "this interaction cost zero network
286. * requests" is asserted against the wire and cannot be talked around.
287. * The favicon request the browser makes on its own is excluded by URL — it is
288. * the browser's, not the app's (the Fetch handler above already answers it).
289. */
290. async captureNetwork() {
291. this.requests = [];
292. this._netOn = true;
293. await this.send('Network.enable');
294. return this;
295. }
297. /** Every request URL captured since the last `resetNetwork()`, oldest first. */
298. networkUrls() { return (this.requests || []).map(r => r.url); }
300. /** The same requests as `{ url, method, headers }` — mission 090 asserts all three. */
301. networkRequests() { return (this.requests || []).slice(); }
303. /** Forget everything captured so far — the "since this moment" baseline. */
304. resetNetwork() { this.requests = []; return this; }
306. _record(level, text, extra) { this.messages.push({ level, text, ...extra }); }
308. async _init() {
309. this.conn.onEvent((msg) => {
310. if (msg.sessionId !== this.sessionId) return;
311. const p = msg.params || {};
312. if (msg.method === 'Runtime.consoleAPICalled') {
313. const level = p.type === 'error' ? 'error' : p.type === 'warning' || p.type === 'warn' ? 'warning' : p.type === 'debug' ? 'debug' : 'info';
314. this._record(level, (p.args || []).map(describeArg).join(' '), { source: 'console.' + p.type });
315. } else if (msg.method === 'Runtime.exceptionThrown') {
316. const d = p.exceptionDetails || {};
317. const text = (d.exception && (d.exception.description || d.exception.value)) || d.text || 'uncaught exception';
318. this._record('error', String(text), { source: 'exception' });
319. } else if (msg.method === 'Log.entryAdded') {
320. const e = p.entry || {};
321. const level = e.level === 'error' ? 'error' : e.level === 'warning' ? 'warning' : 'info';
322. this._record(level, `${e.source}: ${e.text}${e.url ? ' @ ' + e.url : ''}`, { source: 'log.' + e.source });
323. } else if (msg.method === 'Page.loadEventFired') {
324. this._loaded = true;
325. } else if (msg.method === 'Network.requestWillBeSent' && this._netOn) {
326. const url = (p.request && p.request.url) || '';
327. if (!/\/favicon\.ico$/.test(url)) {
328. this.requests.push({
329. url,
330. method: (p.request && p.request.method) || 'GET',
331. headers: (p.request && p.request.headers) || {},
332. });
333. }
334. } else if (msg.method === 'Fetch.requestPaused' && this._precache
335. && this._precache[(p.request && p.request.url) || '']) {
336. // the harness precache (servePrecache) answers this one, network untouched
337. const hit = this._precache[p.request.url];
338. this.send('Fetch.fulfillRequest', {
339. requestId: p.requestId, responseCode: hit.status || 200,
340. responseHeaders: [{ name: 'Content-Type', value: hit.contentType || 'text/html; charset=utf-8' }],
341. body: Buffer.from(hit.body, 'utf-8').toString('base64'),
342. }).catch(() => {});
343. } else if (msg.method === 'Fetch.requestPaused' && this._precache
344. && !/\/favicon\.ico$/.test((p.request && p.request.url) || '')) {
345. // not precached: let it go to the network — which is where it must fail
346. this.send('Fetch.continueRequest', { requestId: p.requestId }).catch(() => {});
347. } else if (msg.method === 'Fetch.requestPaused') {
348. // The browser fetches /favicon.ico on every navigation all by itself.
349. // A fixture server serves no favicon, so that 404 would show up as a
350. // console error that NO page code caused. Answer it here (empty 200)
351. // instead of filtering it out later: then "zero console errors" means
352. // exactly what it says — nothing is excused after the fact.
353. this.send('Fetch.fulfillRequest', {
354. requestId: p.requestId, responseCode: 200,
355. responseHeaders: [{ name: 'Content-Type', value: 'image/x-icon' }], body: '',
356. }).catch(() => {});
357. }
358. });
359. await this.send('Runtime.enable');
360. await this.send('Log.enable');
361. await this.send('Page.enable');
362. await this.send('DOM.enable');
363. await this.send('Fetch.enable', { patterns: [{ urlPattern: '*/favicon.ico' }] });
364. }
366. /** Navigate and wait for the load event (plus a settled DOM). */
367. async goto(url, { timeout = 15000 } = {}) {
368. this._loaded = false;
369. await this.send('Page.navigate', { url });
370. const deadline = Date.now() + timeout;
371. while (!this._loaded && Date.now() < deadline) await sleep(25);
372. if (!this._loaded) throw new Error(`navigate: load event never fired for ${url}`);
373. return this;
374. }
376. /** Evaluate an expression (or a function body via a plain string) in the page. */
377. async evaluate(expression, { awaitPromise = true } = {}) {
378. const src = typeof expression === 'function' ? `(${expression.toString()})()` : expression;
379. const res = await this.send('Runtime.evaluate', {
380. expression: src, returnByValue: true, awaitPromise, userGesture: true,
381. });
382. if (res.exceptionDetails) {
383. const d = res.exceptionDetails;
384. const text = (d.exception && (d.exception.description || d.exception.value)) || d.text;
385. throw new Error('evaluate threw: ' + text);
386. }
387. return res.result && res.result.value;
388. }
390. /** Poll a JS expression until it is truthy. Returns its value. */
391. async waitFor(expression, { timeout = 10000, interval = 50, label } = {}) {
392. const deadline = Date.now() + timeout;
393. let last;
394. while (Date.now() < deadline) {
395. try { last = await this.evaluate(expression); } catch (e) { last = undefined; }
396. if (last) return last;
397. await sleep(interval);
398. }
399. throw new Error(`waitFor timed out after ${timeout}ms: ${label || String(expression).slice(0, 120)}`);
400. }
402. waitForSelector(selector, opts = {}) {
403. return this.waitFor(`!!document.querySelector(${JSON.stringify(selector)})`, { ...opts, label: `selector ${selector}` });
404. }
406. text(selector) {
407. return this.evaluate(`(document.querySelector(${JSON.stringify(selector)}) || {}).textContent`);
408. }
410. html(selector = 'body') {
411. return this.evaluate(`(document.querySelector(${JSON.stringify(selector)}) || {}).innerHTML`);
412. }
414. /** Element centre in viewport coordinates, or null when it isn't laid out. */
415. async box(selector) {
416. return this.evaluate(`(() => {
417. const el = document.querySelector(${JSON.stringify(selector)});
418. if (!el) return null;
419. // a real click lands at viewport coordinates: an element below the fold is
420. // scrolled into view first, as a user would have to (2026-09-12: a grown
421. // list pushed a heading off-screen and the press hit nothing)
422. el.scrollIntoView({ block: 'center', inline: 'nearest' });
423. const r = el.getBoundingClientRect();
424. if (r.width === 0 && r.height === 0) return null;
425. return { x: r.left + r.width / 2, y: r.top + r.height / 2, w: r.width, h: r.height };
426. })()`);
427. }
429. /**
430. * A REAL click: an Input-domain mouse press/release at the element's centre.
431. * Not `el.click()` — this goes through Chrome's real hit-testing and event path,
432. * so an overlay, a zero-size element or a detached node makes it fail here.
433. */
434. async click(selector, { timeout = 10000 } = {}) {
435. await this.waitForSelector(selector, { timeout });
436. const box = await this.box(selector);
437. if (!box) throw new Error(`click: ${selector} has no layout box (not visible)`);
438. const base = { x: Math.round(box.x), y: Math.round(box.y), button: 'left', clickCount: 1, buttons: 1 };
439. await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...base, buttons: 0 });
440. await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', ...base });
441. await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...base, buttons: 0 });
442. return this;
443. }
445. /**
446. * A REAL DRAG (mission 127): press over `fromSel`, walk the pointer to
447. * `toSel` in `steps` intermediate moves, then release — all through the Input
448. * domain, so Chrome does its own hit-testing and produces the genuine
449. * pointerdown / pointermove / pointerenter / pointerup sequence. Nothing here
450. * is synthesised in page script.
451. *
452. * `hold` is awaited while the button is DOWN over the destination, which is the
453. * only moment a mid-drag assertion (a "dragging: X" label) can be made.
454. * The destination box is measured AFTER the press, because a drag may already
455. * have moved the layout by then.
456. */
457. async drag(fromSel, toSel, { steps = 8, hold = null, onStep = null, timeout = 10000 } = {}) {
458. await this.waitForSelector(fromSel, { timeout });
459. await this.waitForSelector(toSel, { timeout });
460. const from = await this.box(fromSel);
461. if (!from) throw new Error(`drag: ${fromSel} has no layout box (not visible)`);
462. const at = (x, y, extra) => this.send('Input.dispatchMouseEvent', {
463. x: Math.round(x), y: Math.round(y), button: 'left', clickCount: 1, ...extra,
464. });
465. await at(from.x, from.y, { type: 'mouseMoved', buttons: 0 });
466. await at(from.x, from.y, { type: 'mousePressed', buttons: 1 });
467. const to = await this.box(toSel);
468. if (!to) throw new Error(`drag: ${toSel} has no layout box (not visible)`);
469. for (let i = 1; i <= steps; i++) {
470. const t = i / steps;
471. const x = from.x + (to.x - from.x) * t;
472. const y = from.y + (to.y - from.y) * t;
473. await at(x, y, { type: 'mouseMoved', buttons: 1 });
474. // MID-DRAG SAMPLING (mission 134): the only place from which "the row
475. // follows the pointer" can be measured is BETWEEN two moves, while the
476. // button is still down — `hold` runs once, at the end, and so can never
477. // show that the row tracked anything.
478. if (onStep) await onStep(i, x, y);
479. }
480. if (hold) await hold();
481. await at(to.x, to.y, { type: 'mouseReleased', buttons: 0 });
482. return this;
483. }
485. /** Focus an element (real DOM focus, so keystrokes land in it). */
486. async focus(selector) {
487. await this.waitForSelector(selector);
488. const ok = await this.evaluate(`(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) return false; el.focus(); return document.activeElement === el; })()`);
489. if (!ok) throw new Error(`focus: ${selector} did not take focus`);
490. return this;
491. }
493. /**
494. * REAL typing: per-character rawKeyDown/char/keyUp through the Input domain.
495. * The page sees genuine keydown/keypress/input/keyup — an `onInput` binding that
496. * only listens for synthetic events would fail here.
497. */
498. async type(selector, textToType, { clear = false } = {}) {
499. await this.focus(selector);
500. if (clear) {
501. await this.evaluate(`(() => { const el = document.querySelector(${JSON.stringify(selector)}); el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); })()`);
502. }
503. for (const ch of textToType) {
504. await this.send('Input.dispatchKeyEvent', { type: 'keyDown', text: ch, unmodifiedText: ch, key: ch });
505. await this.send('Input.dispatchKeyEvent', { type: 'keyUp', key: ch });
506. }
507. return this;
508. }
510. async close() {
511. if (this.closed) return;
512. this.closed = true;
513. try { await this.conn.send('Target.closeTarget', { targetId: this.targetId }); } catch {}
514. }
515. }
517. function describeArg(a) {
518. if (!a) return '';
519. if ('value' in a) return typeof a.value === 'object' ? JSON.stringify(a.value) : String(a.value);
520. if (a.description) return a.description;
521. if (a.unserializableValue) return a.unserializableValue;
522. return a.type || '';
523. }
525. // --- Browser ----------------------------------------------------------------
527. export class Browser {
528. constructor(conn, { proc = null, userDataDir = null, endpoint }) {
529. this.conn = conn;
530. this.proc = proc;
531. this.userDataDir = userDataDir;
532. this.endpoint = endpoint;
533. this.pages = [];
534. }
536. /** Whether this driver launched the browser (and therefore must kill it). */
537. get owned() { return this.proc !== null; }
539. async newPage() {
540. const { targetId } = await this.conn.send('Target.createTarget', { url: 'about:blank' });
541. const { sessionId } = await this.conn.send('Target.attachToTarget', { targetId, flatten: true });
542. const page = new Page(this, targetId, sessionId);
543. await page._init();
544. this.pages.push(page);
545. return page;
546. }
548. /**
549. * Teardown. Closes every tab we opened; when WE launched the browser it is also
550. * killed by PID and waited for, and its profile dir removed. Resolves only once
551. * the process is actually gone — the run script asserts on that.
552. */
553. async close() {
554. for (const p of this.pages) { try { await p.close(); } catch {} }
555. this.pages = [];
556. if (!this.owned) { this.conn.close(); return; }
557. try { await this.conn.send('Browser.close'); } catch {}
558. this.conn.close();
559. const pid = this.proc.pid;
560. const gone = await waitForExit(this.proc, 5000);
561. if (!gone) {
562. try { process.kill(pid, 'SIGKILL'); } catch {}
563. await waitForExit(this.proc, 3000);
564. }
565. if (this.userDataDir) { try { rmSync(this.userDataDir, { recursive: true, force: true }); } catch {} }
566. const rec = launchedBrowsers.find(r => r.browser === this);
567. if (rec) rec.closed = true;
568. }
569. }
571. function waitForExit(proc, timeoutMs) {
572. if (proc.exitCode !== null || proc.signalCode !== null) return Promise.resolve(true);
573. return new Promise(resolve => {
574. const t = setTimeout(() => resolve(false), timeoutMs);
575. proc.once('exit', () => { clearTimeout(t); resolve(true); });
576. });
577. }
579. /**
580. * MISSION 285 — A PORT IS FREE WHEN IT CAN BE BOUND, NOT WHEN NOTHING ANSWERS.
581. *
582. * This used to ask `portOpen('127.0.0.1', p)`: connect, and if it is refused call
583. * the port free. Chrome then binds it — and when that bind loses, Chrome does NOT
584. * fail. It falls back to IPv6 and says so on stderr, which nothing read:
585. *
586. * ERROR:net/socket/socket_posix.cc:175] bind() failed: Address already in use (98)
587. * DevTools listening on ws://[::1]:53502/devtools/browser/06fcaa25-…
588. *
589. * `waitForEndpoint` only ever polls `http://127.0.0.1:PORT`, so it then spent its
590. * whole 20 000 ms waiting for an endpoint that was up the entire time at a place it
591. * never looked, and the test that happened to be launching a peer browser took the
592. * blame. Measured twice in one tier run (25-sessions and 27-login, both 20 4xx ms,
593. * both on :53502) and reproduced on demand by putting one listener on 127.0.0.1:P
594. * before the launch — same bind error, same ::1 fallback, IPv4 never reachable.
595. *
596. * So: bind-test the candidate (see `portBindable` in ports.mjs for why a bind is
597. * the honest question), and check what Chrome actually did afterwards.
598. */
599. async function findFreePort(from, to) {
600. for (let p = from; p <= to; p++) if (await portBindable(p)) return p;
601. throw new Error(`no bindable port in ${from}-${to}`);
602. }
604. /** Where Chrome says it is listening — the only address that is not a guess. */
605. function announcedEndpoint(stderr) {
606. const m = /DevTools listening on ws:\/\/(\[[^\]]+\]|[^:/]+):(\d+)\//.exec(stderr);
607. return m ? { host: m[1], port: Number(m[2]) } : null;
608. }
610. /**
611. * Launch (or attach to) a browser.
612. * HL_CDP_URL set → attach, never spawn, never kill.
613. * otherwise → spawn local headless Chrome on a free port in PORT_BASE+200..+209
614. * (8800-8809 by default; `HL_PORT_BASE` moves the block so two
615. * worktrees can run the tier at once).
616. * Optional HL_CHROME overrides the binary; HL_HEADFUL=1 shows the window.
617. *
618. * THE OFFSET HAS NOW MOVED TWICE FOR THE SAME REASON. It was +40 until the tier's
619. * fixture ports grew past forty and the last test was handed the debug port
620. * itself; it became +100, and on 2026-09-06 the tier's 101st fixture port was
621. * handed 8700 — the running Chrome's debug endpoint — and that test could not
622. * start at all ("PORT COLLISION, not a server fault: :8700 could not be bound").
623. * +200 buys the next hundred. See run.mjs's PORT_BASE comment.
624. */
625. const DEBUG_PORT_BASE = (Number(process.env.HL_PORT_BASE) || 8600) + 200;
627. /** The debug block this process may spawn into — the runner audits ALL of it. */
628. export const DEBUG_PORT_RANGE = [DEBUG_PORT_BASE, DEBUG_PORT_BASE + 9];
630. /**
631. * EVERY browser this process launched, whoever asked for it.
632. *
633. * The teardown audit used to know only about the ONE browser run.mjs launched,
634. * so a peer browser started inside a test (25-sessions and 45-server-face-emit
635. * each launch a second one for a second session) could survive while the audit
636. * reported "no orphan chrome/servers" — measured 2026-08-23 with a deliberate
637. * leak, which the audit passed clean. `launchBrowser` is the one choke point
638. * every browser goes through, so the registry belongs here rather than in the
639. * runner, and it catches a leak no matter who caused it.
640. */
641. export const launchedBrowsers = [];
642. export async function launchBrowser({ debugPortRange = [DEBUG_PORT_BASE, DEBUG_PORT_BASE + 9] } = {}) {
643. const attach = process.env.HL_CDP_URL;
644. if (attach) {
645. const base = attach.replace(/\/$/, '');
646. const info = await waitForEndpoint(base, 8000, 'HL_CDP_URL browser');
647. const conn = await connectWs(info.webSocketDebuggerUrl);
648. return new Browser(conn, { endpoint: base });
649. }
651. const bin = process.env.HL_CHROME || (await firstOnPath(CHROME_CANDIDATES));
652. if (!bin) throw new Error(`no Chrome binary found (tried ${CHROME_CANDIDATES.join(', ')}); set HL_CHROME or HL_CDP_URL`);
653. const port = await findFreePort(debugPortRange[0], debugPortRange[1]);
654. const userDataDir = mkdtempSync(join(tmpdir(), 'hl-browser-tier-'));
655. const args = [
656. process.env.HL_HEADFUL ? '--headless=false' : '--headless=new',
657. `--remote-debugging-port=${port}`,
658. `--user-data-dir=${userDataDir}`,
659. '--no-first-run', '--no-default-browser-check', '--disable-extensions',
660. // WPAD proxy auto-detection stalls the FIRST http navigation for ~20s on this
661. // machine (measured: data: URL instant, first http nav 20s, later navs instant).
662. // Going straight-to-direct removes the stall — localhost fixtures need no proxy.
663. '--no-proxy-server', "--proxy-server=direct://", '--proxy-bypass-list=*',
664. '--password-store=basic', '--use-mock-keychain',
665. '--disable-background-networking', '--disable-component-update',
666. '--disable-default-apps', '--disable-sync', '--metrics-recording-only',
667. '--mute-audio', '--disable-gpu', '--disable-dev-shm-usage',
668. '--window-size=1280,900', 'about:blank',
669. ].filter(a => a !== '--headless=false');
670. const proc = spawn(bin, args, { stdio: ['ignore', 'ignore', 'pipe'] });
671. const stderr = [];
672. proc.stderr.on('data', d => { if (stderr.length < 50) stderr.push(String(d)); });
673. const base = `http://127.0.0.1:${port}`;
674. const die = (msg) => {
675. try { process.kill(proc.pid, 'SIGKILL'); } catch {}
676. rmSync(userDataDir, { recursive: true, force: true });
677. throw new Error(msg);
678. };
679. let info;
680. try {
681. // MISSION 285 — stop the moment Chrome says it went somewhere else, instead of
682. // polling an address it has already told us it is not on. A launch that lost the
683. // port is a PORT COLLISION and must read as one; twenty silent seconds followed
684. // by "not reachable" reads as a broken browser or a broken test.
685. info = await waitForEndpoint(base, 20000, 'headless Chrome', () => {
686. const said = announcedEndpoint(stderr.join(''));
687. if (said && said.host !== '127.0.0.1') {
688. return `PORT COLLISION, not a browser fault: Chrome could not bind 127.0.0.1:${port} and listened on ${said.host}:${said.port} instead, so nothing was ever going to answer at ${base}.\n sockets: ${whoHolds(port)}\n chrome said: ${stderr.join('').split('\n').filter(l => /bind\(\) failed|DevTools listening/.test(l)).join(' | ')}`;
689. }
690. return null;
691. });
692. } catch (e) {
693. die(e.message + '\nchrome stderr:\n' + stderr.join(''));
694. }
695. const conn = await connectWs(info.webSocketDebuggerUrl);
696. const browser = new Browser(conn, { proc, userDataDir, endpoint: base });
697. launchedBrowsers.push({ pid: proc.pid, port, userDataDir, closed: false, browser });
698. return browser;
699. }
701. async function firstOnPath(names) {
702. const { execFile } = await import('node:child_process');
703. for (const n of names) {
704. const found = await new Promise(res => execFile('which', [n], (err, out) => res(err ? null : String(out).trim())));
705. if (found) return found;
706. }
707. return null;
708. }