An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
import { beforeEach, describe, expect, test, vi } from 'vitest';
import { fakeBrowser } from 'wxt/testing';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import type { PhoneSession } from './phone';
const TARGET = 'A'.repeat(32);
const phone = vi.hoisted(() => ({
sent: [] as { method: string; params?: Record<string, unknown> }[],
contexts: 0,
answer: (_expression: string): unknown => ({ ok: true, data: {} }),
goneOnce: false,
missingOnce: false,
viewport: { offsetX: 0, offsetY: 50, clientWidth: 411, clientHeight: 675 },
events: [] as ((event: unknown) => void)[],
}));
vi.mock('./socket', () => ({
DAEMON_STATE_KEY: 'browsentic/daemon',
sendCdp: async (_serial: string, method: string, params?: Record<string, unknown>) => {
phone.sent.push({ method, params });
if (method === 'Page.getFrameTree') {
return success({ frameTree: { frame: { id: 'TOP', url: 'http://localhost:8080/now' }, childFrames: [{ frame: { id: 'AD', url: 'https://ads.example/slot' } }] } });
}
if (method === 'DOM.describeNode') return success({ node: { frameId: 'AD' } });
if (method === 'Runtime.evaluate' && String(params?.expression).startsWith('__browsenticPhone.frame')) return success({ result: { objectId: 'IFRAME' } });
if (method === 'Page.createIsolatedWorld') return success({ executionContextId: ++phone.contexts });
if (method === 'Page.getLayoutMetrics') return success({ cssVisualViewport: phone.viewport, cssLayoutViewport: { pageX: 0, pageY: 300, clientWidth: 411, clientHeight: 675 } });
if (method === 'Page.captureScreenshot') return success({ data: 'SHOT' });
if (method === 'Runtime.evaluate' && String(params?.expression).startsWith('__browsenticPhone.dispatch')) {
if (phone.goneOnce) {
phone.goneOnce = false;
return failure('CDP_ERROR', 'Cannot find context with specified id');
}
if (phone.missingOnce) {
phone.missingOnce = false;
return success({ exceptionDetails: { text: 'Uncaught', exception: { description: 'ReferenceError: __browsenticPhone is not defined\n at <anonymous>:1:1' } } });
}
return success({ result: { value: await phone.answer(String(params?.expression)) } });
}
if (method === 'Runtime.evaluate' && String(params?.expression).includes('scrollY')) return success({ result: { value: { scrollX: 0, scrollY: 574 } } });
return success({});
},
onCdpEvent: (listener: (event: unknown) => void) => phone.events.push(listener),
onPhoneClosed: () => undefined,
onDaemonClosed: () => undefined,
}));
const mirror = vi.hoisted(() => ({ steer: null as ((command: unknown) => Promise<void>) | null }));
vi.mock('./phone-mirror', () => ({
attachedSession: async () => 'session-1',
steerLensFromMirror: (_targetId: string, steer: (command: unknown) => Promise<void>) => {
mirror.steer = steer;
return () => (mirror.steer = null);
},
}));
const { pageSideOnPhone, phoneUrls, pickClip, servePhoneBackend, shotClip } = await import('./phone-backend');
servePhoneBackend();
const SESSION: PhoneSession = {
serial: 'emulator-5554',
mirrorTabId: 9,
windowId: 1,
openedAt: 0,
activeTargetId: TARGET,
targets: [{ targetId: TARGET, url: 'http://localhost:8080/', title: 'Spike page' }],
};
const methods = () => phone.sent.map(({ method }) => method);
const input = (type: string) => phone.sent.filter(({ method, params }) => method === 'Input.dispatchTouchEvent' && params?.type === type);
beforeEach(() => {
fakeBrowser.reset();
phone.sent.length = 0;
phone.goneOnce = false;
phone.missingOnce = false;
phone.viewport = { offsetX: 0, offsetY: 50, clientWidth: 411, clientHeight: 675 };
phone.answer = () => ({ ok: true, data: {} });
vi.stubGlobal('fetch', async () => new Response('/* the bundle */'));
});
describe('page-side tools on the phone', () => {
test('run in an isolated world that is made, and given the bundle, once', async () => {
phone.answer = () => ({ ok: true, data: { title: 'Spike page' } });
const first = await pageSideOnPhone('page.getPageInfo', {}, SESSION);
await pageSideOnPhone('page.extractText', {}, SESSION);
expect(first).toEqual({ ok: true, data: { title: 'Spike page' } });
expect(methods().filter((method) => method === 'Page.createIsolatedWorld')).toHaveLength(1);
expect(phone.sent.filter(({ params }) => params?.expression === '/* the bundle */')).toHaveLength(1);
});
test('a navigation that killed the world makes it again and retries once', async () => {
await pageSideOnPhone('page.getPageInfo', {}, SESSION);
const before = methods().filter((method) => method === 'Page.createIsolatedWorld').length;
phone.goneOnce = true;
expect((await pageSideOnPhone('page.getPageInfo', {}, SESSION)).ok).toBe(true);
expect(methods().filter((method) => method === 'Page.createIsolatedWorld').length - before).toBe(1);
});
test('a stale context that lands somewhere without the bundle makes the world again too', async () => {
await pageSideOnPhone('page.getPageInfo', {}, SESSION);
const before = methods().filter((method) => method === 'Page.createIsolatedWorld').length;
phone.missingOnce = true;
expect((await pageSideOnPhone('page.getPageInfo', {}, SESSION)).ok).toBe(true);
expect(methods().filter((method) => method === 'Page.createIsolatedWorld').length - before).toBe(1);
});
});
const navigated = (frame: { id: string; parentId?: string }) => phone.events.forEach((listener) => listener({ t: 'cdpEvent', serial: 'emulator-5554', method: 'Page.frameNavigated', params: { frame }, sessionId: 'session-1' }));
describe('the phone tab as it is now', () => {
const leave = () => pageSideOnPhone('page.switchFrame', {}, SESSION);
test('is the address it last reported, the one it has now, and every frame on the focused path', async () => {
await leave();
expect(await phoneUrls(SESSION)).toEqual(['http://localhost:8080/', 'http://localhost:8080/now']);
expect(await pageSideOnPhone('page.switchFrame', { frame: { selector: 'iframe' } }, SESSION)).toMatchObject({ ok: true, data: { frame: { frameId: 'AD' } } });
expect(await phoneUrls(SESSION)).toEqual(['http://localhost:8080/', 'http://localhost:8080/now', 'https://ads.example/slot']);
});
test('a document that navigates forgets the frame it was in and its isolated worlds, as a desktop tab that loads does', async () => {
await pageSideOnPhone('page.switchFrame', { frame: { selector: 'iframe' } }, SESSION);
await pageSideOnPhone('page.getPageInfo', {}, SESSION);
const worlds = () => methods().filter((method) => method === 'Page.createIsolatedWorld').length;
const before = worlds();
navigated({ id: 'TOP' });
expect(await phoneUrls(SESSION)).toEqual(['http://localhost:8080/', 'http://localhost:8080/now']);
await pageSideOnPhone('page.getPageInfo', {}, SESSION);
expect(worlds() - before).toBe(1);
});
test('a frame that navigates forgets only its own world', async () => {
await leave();
await pageSideOnPhone('page.getPageInfo', {}, SESSION);
const before = methods().filter((method) => method === 'Page.createIsolatedWorld').length;
navigated({ id: 'AD', parentId: 'TOP' });
await pageSideOnPhone('page.getPageInfo', {}, SESSION);
expect(methods().filter((method) => method === 'Page.createIsolatedWorld').length).toBe(before);
});
});
describe('touch on the phone', () => {
test('a click is a tap at the page’s point less the visual viewport’s offset, reported like a click', async () => {
phone.answer = () => ({ ok: true, data: { tag: 'a', text: 'Go to second', point: { x: 100, y: 200 }, from: { x: 90, y: 190 }, button: 'left', submits: false } });
const clicked = (await pageSideOnPhone('page.clickElement', { target: { selector: '#link' } }, SESSION)) as ActionResult<Record<string, unknown>>;
expect(clicked).toEqual({ ok: true, data: { tag: 'a', text: 'Go to second', submits: false } });
expect(input('touchStart')[0].params?.touchPoints).toEqual([{ x: 100, y: 150 }]);
expect(input('touchEnd')[0].params?.touchPoints).toEqual([]);
});
test('a point off the visible screen is not touched, and says why', async () => {
phone.answer = () => ({ ok: true, data: { point: { x: 100, y: 2000 } } });
expect(await pageSideOnPhone('page.clickElement', { target: { selector: '#far' } }, SESSION)).toMatchObject({ ok: false, error: { code: 'TAP_MISSED' } });
expect(input('touchStart')).toEqual([]);
});
test('scrolling a screen down is wheel steps at the middle of the screen, adding up to 85% of it', async () => {
const scrolled = await pageSideOnPhone('page.scrollTo', { direction: 'down' }, SESSION);
const wheels = phone.sent.filter(({ params }) => params?.type === 'mouseWheel');
expect(wheels.reduce((sum, { params }) => sum + Number(params?.deltaY), 0)).toBe(Math.round(675 * 0.85));
expect(wheels[0].params).toMatchObject({ x: 205.5, y: 337.5 });
expect(scrolled).toEqual({ ok: true, data: { direction: 'down', scrollX: 0, scrollY: 574 } });
});
test('typing focuses the field in the page, selects what it held, and inserts the text', async () => {
phone.answer = () => ({ ok: true, data: { tag: 'input' } });
await pageSideOnPhone('page.typeText', { target: { selector: '#inp' }, text: 'hello\nworld' }, SESSION);
const typed = phone.sent.filter(({ method }) => method === 'Input.insertText' || method === 'Input.dispatchKeyEvent').map(({ params }) => params?.text ?? params?.type);
expect(typed).toEqual(['hello', '\r', 'keyUp', 'world']);
expect(phone.sent.some(({ params }) => String(params?.expression).includes('page.focusInput'))).toBe(true);
expect(phone.sent.some(({ params }) => String(params?.expression).includes('select()'))).toBe(true);
});
});
describe('a screenshot on the phone', () => {
const plan = { mode: 'viewport' as const, dpr: 2.625, viewport: { w: 411, h: 675 }, region: { x: 0, y: 300, w: 411, h: 675 }, format: 'jpeg' as const, maxLongSide: 675 };
test('clips in CSS px and scales against device pixels, so one image pixel is one CSS pixel', () => {
expect(shotClip(plan)).toEqual({ clip: { x: 0, y: 300, width: 411, height: 675, scale: 1 / 2.625 }, width: 411, height: 675, truncated: false });
});
test('a long page is cut at eight screens and fitted to the longest side asked for', () => {
const shot = shotClip({ ...plan, mode: 'fullPage', region: { x: 0, y: 0, w: 411, h: 11_000 }, maxLongSide: 1600 });
expect(shot.truncated).toBe(true);
expect(shot.clip.height).toBe(5400);
expect([shot.width, shot.height]).toEqual([Math.round(411 * (1600 / 5400)), 1600]);
});
});
describe('A-Eye on the phone', () => {
const capture = { region: { x: 20, y: 100, w: 200, h: 40 }, viewport: { w: 411, h: 675 }, dpr: 2.625 };
const layout = { pageX: 0, pageY: 300, clientWidth: 411, clientHeight: 675 };
test('the photograph is the element’s box, padded and kept on screen, in document coordinates at device resolution', () => {
expect(pickClip({ x: 20, y: 100 }, capture, layout)).toEqual({
clip: { x: 4, y: 384, width: 232, height: 72, scale: 1 },
width: Math.round(232 * 2.625),
height: Math.round(72 * 2.625),
});
});
test('a big element is shrunk to the longest side the desktop pick allows', () => {
const planned = pickClip({ x: 0, y: 0 }, { ...capture, region: { x: 0, y: 0, w: 411, h: 675 } }, layout)!;
expect(Math.max(planned.width, planned.height)).toBe(1200);
});
test('the pick runs in the page with a wait the relay allows, and comes back with the element’s photograph', async () => {
phone.answer = () => ({ ok: true, data: { element: { tag: 'button', selector: '#buy' }, content: 'Buy', truncated: false, url: 'https://shop.example/', title: 'Shop', capture } });
const picked = await pageSideOnPhone('page.pickElement', { timeoutMs: 300_000 }, SESSION);
expect(picked).toMatchObject({ ok: true, data: { element: { selector: '#buy' }, shot: { dataUrl: 'data:image/jpeg;base64,SHOT' } } });
expect(String(phone.sent.find(({ params }) => String(params?.expression).includes('page.pickElement'))?.params?.expression)).toContain('"timeoutMs":170000');
expect(phone.sent.find(({ method }) => method === 'Page.captureScreenshot')?.params?.clip).toEqual({ x: 4, y: 384, width: 232, height: 72, scale: 1 });
});
test('while the pick waits, the mirror steers the lens at the page point under a touch, and lets go once it is answered', async () => {
let answer: (value: unknown) => void = () => undefined;
phone.answer = () => new Promise((resolve) => (answer = resolve));
phone.viewport = { offsetX: 30, offsetY: 50, clientWidth: 205, clientHeight: 337 };
const picking = pageSideOnPhone('page.pickElement', {}, SESSION);
await vi.waitFor(() => expect(mirror.steer).not.toBeNull());
await mirror.steer!({ op: 'aim', x: 100, y: 200 });
await mirror.steer!({ op: 'wider' });
const steered = phone.sent.filter(({ params }) => String(params?.expression).startsWith('__browsenticPhone.lens')).map(({ params }) => params?.expression);
expect(steered).toEqual(['__browsenticPhone.lens({"op":"aim","x":130,"y":250})', '__browsenticPhone.lens({"op":"wider"})']);
answer(failure('PICK_CANCELLED', 'dismissed'));
await picking;
expect(mirror.steer).toBeNull();
});
});