1 +import test from 'node:test';
2 +import assert from 'node:assert/strict';
3 +import { createServer } from 'node:http';
4 +import { createHash, randomBytes } from 'node:crypto';
5 +import { chmod, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
6 +import { existsSync } from 'node:fs';
7 +import { tmpdir } from 'node:os';
8 +import { dirname, join, resolve } from 'node:path';
9 +import { fileURLToPath } from 'node:url';
10 +import { spawn } from 'node:child_process';
12 +const __dirname = dirname(fileURLToPath(import.meta.url));
13 +const SCRIPT = resolve(__dirname, 'bidi.mjs');
14 +const CONTEXT_ID = '12345678-90ab-cdef-1234-567890abcdef';
15 +const CONTEXT_PREFIX = CONTEXT_ID.slice(0, 8);
16 +const PNG_1X1 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
19 + if (value === undefined) return { type: 'undefined' };
20 + if (value === null) return { type: 'null' };
21 + if (Array.isArray(value)) return { type: 'array', value: value.map(rv) };
22 + if (typeof value === 'object') return { type: 'object', value: Object.entries(value).map(([k, v]) => [k, rv(v)]) };
23 + return { type: typeof value, value };
26 +function encodeFrame(text) {
27 + const payload = Buffer.from(text);
28 + if (payload.length < 126) return Buffer.concat([Buffer.from([0x81, payload.length]), payload]);
29 + if (payload.length <= 0xffff) {
30 + const head = Buffer.alloc(4);
31 + head[0] = 0x81; head[1] = 126; head.writeUInt16BE(payload.length, 2);
32 + return Buffer.concat([head, payload]);
34 + const head = Buffer.alloc(10);
35 + head[0] = 0x81; head[1] = 127; head.writeBigUInt64BE(BigInt(payload.length), 2);
36 + return Buffer.concat([head, payload]);
39 +function decodeFrames(buffer) {
40 + const messages = [];
42 + while (offset + 2 <= buffer.length) {
43 + const b1 = buffer[offset];
44 + const b2 = buffer[offset + 1];
45 + let len = b2 & 0x7f;
47 + if (len === 126) { if (offset + 4 > buffer.length) break; len = buffer.readUInt16BE(offset + 2); header = 4; }
48 + else if (len === 127) { if (offset + 10 > buffer.length) break; len = Number(buffer.readBigUInt64BE(offset + 2)); header = 10; }
49 + const masked = (b2 & 0x80) !== 0;
50 + const maskOffset = offset + header;
51 + const payloadOffset = maskOffset + (masked ? 4 : 0);
52 + const end = payloadOffset + len;
53 + if (end > buffer.length) break;
54 + const payload = Buffer.from(buffer.subarray(payloadOffset, end));
56 + const mask = buffer.subarray(maskOffset, payloadOffset);
57 + for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i % 4];
59 + if ((b1 & 0x0f) === 0x1) messages.push(payload.toString('utf8'));
62 + return { messages, rest: buffer.subarray(offset) };
65 +async function startFakeBidiServer() {
66 + const state = { methods: [], actions: [], loadMoreRemaining: 2, sessions: 0 };
67 + const sockets = new Set();
68 + const server = createServer();
69 + server.on('upgrade', (req, socket) => {
70 + sockets.add(socket);
71 + socket.on('error', () => {});
72 + socket.on('close', () => sockets.delete(socket));
73 + const accept = createHash('sha1').update(req.headers['sec-websocket-key'] + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11').digest('base64');
74 + socket.write(['HTTP/1.1 101 Switching Protocols', 'Upgrade: websocket', 'Connection: Upgrade', `Sec-WebSocket-Accept: ${accept}`, '', ''].join('\r\n'));
75 + let buf = Buffer.alloc(0);
76 + socket.on('data', chunk => {
77 + buf = Buffer.concat([buf, chunk]);
78 + const decoded = decodeFrames(buf);
80 + for (const message of decoded.messages) handleRequest(socket, JSON.parse(message), state);
83 + await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
84 + const { port } = server.address();
88 + wsUrl: `ws://127.0.0.1:${port}/session`,
90 + for (const socket of sockets) socket.destroy();
91 + await new Promise(resolve => server.close(resolve));
96 +function send(socket, payload) {
97 + if (socket.destroyed || !socket.writable) return;
98 + try { socket.write(encodeFrame(JSON.stringify(payload))); } catch {}
101 +function evalResult(expression, state) {
102 + if (expression === 'document.title') return 'Firefox Fake Title';
103 + if (expression === 'document.documentElement.outerHTML') return '<html><body><button id="go">Go</button><div class="card">Card</div></body></html>';
104 + if (expression.includes('document.querySelector(".card")?.outerHTML')) return '<div class="card">Card</div>';
105 + if (expression.includes('performance.getEntriesByType')) return JSON.stringify([{ name: 'https://example.test/app.js', type: 'script', duration: 12, size: 2048 }]);
106 + if (expression.includes('querySelectorAll(sel)')) return '[button #go] Go\n[a → https://example.test/] Link';
107 + if (expression.includes('const query = "#go"') && expression.includes('const mode = "css"')) {
108 + return { ok: true, x: 15, y: 25, tag: 'BUTTON', text: 'Go', via: 'css', hit: '<BUTTON#go> Go' };
110 + if (expression.includes('const query = "Go"') && expression.includes('const mode = "text"')) {
111 + return { ok: true, x: 15, y: 25, tag: 'BUTTON', text: 'Go', via: 'text', hit: '<BUTTON#go> Go' };
113 + if (expression.includes('document.querySelector("#more")') && expression.includes('exists: true')) {
114 + if (state.loadMoreRemaining > 0) { state.loadMoreRemaining--; return { exists: true, clicked: true }; }
115 + return { exists: false, clicked: false };
120 +function handleRequest(socket, req, state) {
121 + state.methods.push(req.method);
122 + switch (req.method) {
123 + case 'session.new':
125 + return send(socket, { id: req.id, type: 'success', result: { sessionId: `session-${state.sessions}`, capabilities: {} } });
126 + case 'session.end':
127 + return send(socket, { id: req.id, type: 'success', result: {} });
128 + case 'browsingContext.getTree':
129 + return send(socket, { id: req.id, type: 'success', result: { contexts: [
130 + { context: CONTEXT_ID, url: 'https://example.test/', title: 'Firefox Fake Title', children: [] },
132 + case 'script.evaluate':
133 + send(socket, { id: req.id, type: 'success', result: { realm: 'realm-1', result: rv(evalResult(req.params.expression, state)) } });
134 + if (req.params.expression?.includes('console.')) {
135 + setTimeout(() => send(socket, { type: 'event', method: 'log.entryAdded', params: { type: 'console', level: 'info', method: 'log', text: 'console probe', timestamp: Date.now() } }), 5);
138 + case 'session.subscribe':
139 + return send(socket, { id: req.id, type: 'success', result: { subscription: 'sub-1' } });
140 + case 'script.addPreloadScript':
141 + return send(socket, { id: req.id, type: 'success', result: { script: 'preload-1' } });
142 + case 'browsingContext.navigate':
143 + send(socket, { id: req.id, type: 'success', result: { navigation: 'nav-1', url: req.params.url } });
145 + send(socket, { type: 'event', method: 'log.entryAdded', params: { type: 'console', level: 'warn', method: 'warn', text: 'nav warning', timestamp: Date.now() } });
146 + send(socket, { type: 'event', method: 'network.responseCompleted', params: { request: { method: 'GET', url: 'https://example.test/blocked' }, response: { status: 403, statusText: 'Forbidden' }, timestamp: Date.now() } });
149 + case 'browsingContext.captureScreenshot':
150 + return send(socket, { id: req.id, type: 'success', result: { data: PNG_1X1 } });
151 + case 'input.performActions':
152 + state.actions.push(req.params.actions);
153 + return send(socket, { id: req.id, type: 'success', result: {} });
154 + case 'input.releaseActions':
155 + return send(socket, { id: req.id, type: 'success', result: {} });
156 + case 'browser.getClientWindows':
157 + return send(socket, { id: req.id, type: 'success', result: { clientWindows: [{ active: true }] } });
159 + return send(socket, { id: req.id, type: 'error', error: 'unknown command', message: req.method });
163 +function cleanEnv(extra) {
164 + const env = { ...process.env, ...extra };
165 + for (const key of ['PI_FIREFOX_BIDI_WS_URL', 'WEBDRIVER_BIDI_WS_URL', 'PI_FIREFOX_BIDI_PORT', 'PI_FIREFOX_BIDI_BIN']) {
166 + if (!(key in extra)) delete env[key];
171 +function runBidi(args, env) {
172 + return new Promise((resolve, reject) => {
173 + const child = spawn(process.execPath, [SCRIPT, ...args], { cwd: __dirname, env: cleanEnv(env), stdio: ['ignore', 'pipe', 'pipe'] });
176 + child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
177 + child.stdout.on('data', chunk => { stdout += chunk; });
178 + child.stderr.on('data', chunk => { stderr += chunk; });
179 + child.on('error', reject);
180 + child.on('close', code => resolve({ code, stdout, stderr }));
184 +async function expectOk(args, env) {
185 + const result = await runBidi(args, env);
186 + assert.equal(result.code, 0, `${args.join(' ')}\nstdout=${result.stdout}\nstderr=${result.stderr}`);
187 + return result.stdout.trimEnd();
190 +test('bidi CLI covers explicit endpoint commands and agent-friendly batch', async () => {
191 + const server = await startFakeBidiServer();
192 + const stateDir = await mkdtemp(join(tmpdir(), 'pi-firefox-bidi-test-'));
193 + const env = { PI_FIREFOX_BIDI_WS_URL: server.wsUrl, PI_FIREFOX_BIDI_STATE_DIR: stateDir };
195 + const ensure = await expectOk(['ensure'], env);
196 + assert.equal(ensure, server.wsUrl);
198 + const list = await expectOk(['list'], env);
199 + assert.match(list, new RegExp(`^${CONTEXT_PREFIX}\\s+Firefox Fake Title\\s+https://example\\.test/`));
200 + assert.equal((await stat(stateDir)).mode & 0o777, 0o700);
201 + assert.ok(existsSync(join(stateDir, 'contexts.json')));
203 + assert.match(await expectOk(['snap', CONTEXT_PREFIX], env), /\[button #go\] Go/);
204 + assert.equal(await expectOk(['eval', CONTEXT_PREFIX, 'document.title'], env), 'Firefox Fake Title');
205 + assert.equal(await expectOk(['html', CONTEXT_PREFIX, '.card'], env), '<div class="card">Card</div>');
206 + assert.match(await expectOk(['nav', CONTEXT_PREFIX, 'https://example.test/next'], env), /Navigated to https:\/\/example\.test\/next/);
207 + const navConsole = await expectOk(['navconsole', CONTEXT_PREFIX, 'https://example.test/next', '50'], env);
208 + assert.match(navConsole, /nav warning/);
209 + assert.match(navConsole, /HTTP 403 Forbidden/);
210 + assert.ok(!server.state.methods.includes('script.addPreloadScript'));
211 + assert.match(await expectOk(['net', CONTEXT_PREFIX], env), /script\s+https:\/\/example\.test\/app\.js/);
213 + const defaultShot = await expectOk(['shot', CONTEXT_PREFIX], env);
214 + const defaultScreenshot = join(stateDir, 'screenshot.png');
215 + assert.match(defaultShot, new RegExp(defaultScreenshot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
216 + assert.equal(await readFile(defaultScreenshot, 'base64'), PNG_1X1);
218 + assert.equal(await expectOk(['click', CONTEXT_PREFIX, '#go'], env), 'Clicked <BUTTON> "Go" at CSS (15, 25)');
219 + assert.equal(await expectOk(['clicktext', CONTEXT_PREFIX, 'Go'], env), 'Clicked <BUTTON> "Go" at CSS (15, 25)');
220 + assert.equal(await expectOk(['clickxy', CONTEXT_PREFIX, '10', '20'], env), 'Clicked at CSS (10, 20)');
221 + assert.equal(await expectOk(['type', CONTEXT_PREFIX, 'hi'], env), 'Typed 2 characters');
222 + assert.equal(await expectOk(['loadall', CONTEXT_PREFIX, '#more', '1'], env), 'Clicked "#more" 2 time(s) until it disappeared');
223 + assert.match(await expectOk(['raw', 'browser.getClientWindows', '{}'], env), /"active": true/);
224 + assert.match(await expectOk(['console', CONTEXT_PREFIX, 'console.log("probe")', '50'], env), /console probe/);
226 + const batch = JSON.parse(await expectOk(['batch', CONTEXT_PREFIX, JSON.stringify([
227 + { cmd: 'eval', args: ['document.title'] },
228 + { cmd: 'html', args: ['.card'] },
230 + assert.deepEqual(batch.map(item => item.ok), [true, true]);
231 + assert.equal(batch[0].result, 'Firefox Fake Title');
232 + assert.equal(batch[1].result, '<div class="card">Card</div>');
234 + assert.ok(server.state.actions.length >= 2);
236 + await rm(stateDir, { recursive: true, force: true });
237 + await server.close();
241 +test('bidi CLI auto-starts managed Firefox from port 0 stderr and reuses state', async () => {
242 + const server = await startFakeBidiServer();
243 + const stateDir = await mkdtemp(join(tmpdir(), 'pi-firefox-bidi-start-test-'));
244 + const fakeFirefox = join(stateDir, 'fake-firefox');
245 + const argsFile = join(stateDir, 'firefox-args.txt');
246 + await writeFile(fakeFirefox, `#!/usr/bin/env bash\nprintf '%s\\n' \"$@\" > ${JSON.stringify(argsFile)}\ntrap 'exit 0' TERM INT\nprintf 'WebDriver BiDi listening on ${server.wsUrl}\\n' >&2\nwhile true; do sleep 1 & wait $!; done\n`);
247 + await chmod(fakeFirefox, 0o755);
248 + const env = { PI_FIREFOX_BIDI_BIN: fakeFirefox, PI_FIREFOX_BIDI_STATE_DIR: stateDir, PI_FIREFOX_BIDI_START_TIMEOUT_MS: '3000' };
250 + const list = await expectOk(['list'], env);
251 + assert.match(list, /Firefox Fake Title/);
252 + const state = JSON.parse(await readFile(join(stateDir, 'state.json'), 'utf8'));
253 + assert.equal(state.wsUrl, server.wsUrl);
254 + assert.equal(state.managed, true);
255 + assert.ok(state.pid > 0);
256 + const launchedArgs = (await readFile(argsFile, 'utf8')).trim().split('\n');
257 + if (process.platform !== 'win32') {
258 + assert.ok(launchedArgs.includes('--name'));
259 + assert.ok(launchedArgs.includes('pi-firefox-debug'));
262 + const reused = await expectOk(['ensure'], env);
263 + assert.equal(reused, server.wsUrl);
264 + await expectOk(['stop'], env);
266 + await runBidi(['stop'], env).catch(() => {});
267 + await rm(stateDir, { recursive: true, force: true });
268 + await server.close();
272 +test('bidi CLI safety caps are tunable and explicit', async () => {
273 + const server = await startFakeBidiServer();
274 + const stateDir = await mkdtemp(join(tmpdir(), 'pi-firefox-bidi-caps-test-'));
276 + PI_FIREFOX_BIDI_WS_URL: server.wsUrl,
277 + PI_FIREFOX_BIDI_STATE_DIR: stateDir,
278 + PI_FIREFOX_BIDI_MAX_HTML_CHARS: '20',
279 + PI_FIREFOX_BIDI_MAX_NET_ENTRIES: '0',
282 + const html = await expectOk(['html', CONTEXT_PREFIX, ''], env);
283 + assert.match(html, /page HTML truncated/);
284 + const net = await expectOk(['net', CONTEXT_PREFIX], env);
285 + assert.doesNotMatch(net, /network entries truncated/);
287 + await rm(stateDir, { recursive: true, force: true });
288 + await server.close();