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, it, vi } from 'vitest';
import { fakeBrowser } from 'wxt/testing';
import type { DeviceNotice } from '@/lib/notices';
const socket = vi.hoisted(() => ({ sendNotice: vi.fn(), opened: null as ((noticeId: string) => void) | null }));
const toast = vi.hoisted(() => ({ goToTab: vi.fn() }));
vi.mock('./socket', () => ({
sendNotice: socket.sendNotice,
onOpenNotice: (listener: (noticeId: string) => void) => {
socket.opened = listener;
return () => undefined;
},
}));
vi.mock('./toast', () => ({ goToTab: toast.goToTab }));
const { browserInFront, noticeOnDevice, serveDeviceNotices } = await import('./device-notices');
const done: DeviceNotice = { id: 'monitor:build', kind: 'monitor', title: 'Done: build', body: 'Finished after 3:12.', tone: 'live' };
type Window = { id: number; focused: boolean; state: string };
function windows(list: Window[], tabs: { id: number; windowId: number }[] = []): void {
(fakeBrowser.windows as unknown as { getAll: () => Promise<Window[]> }).getAll = async () => list;
(fakeBrowser.windows as unknown as { get: (id: number) => Promise<Window | undefined> }).get = async (id) => list.find((window) => window.id === id);
(fakeBrowser.windows as unknown as { update: (id: number, change: object) => Promise<object> }).update = vi.fn(async () => ({}));
(fakeBrowser.tabs as unknown as { get: (id: number) => Promise<object> }).get = async (id) => {
const tab = tabs.find((candidate) => candidate.id === id);
if (!tab) throw new Error('No tab');
return tab;
};
}
beforeEach(() => {
fakeBrowser.reset();
vi.stubEnv('FIREFOX', '');
socket.sendNotice.mockReset();
toast.goToTab.mockReset();
});
describe('browserInFront', () => {
it('is true only while some window is focused and not minimized', async () => {
windows([{ id: 1, focused: true, state: 'normal' }]);
expect(await browserInFront()).toBe(true);
windows([{ id: 1, focused: false, state: 'normal' }]);
expect(await browserInFront()).toBe(false);
windows([{ id: 1, focused: true, state: 'minimized' }]);
expect(await browserInFront()).toBe(false);
windows([]);
expect(await browserInFront()).toBe(false);
});
});
describe('noticeOnDevice', () => {
it('leaves the notice to the page while someone is looking at the browser', async () => {
windows([{ id: 1, focused: true, state: 'maximized' }]);
expect(await noticeOnDevice(done, 7)).toBe(false);
expect(socket.sendNotice).not.toHaveBeenCalled();
});
it('hands it to the app while the browser is behind, and falls back when the app will not take it', async () => {
windows([{ id: 1, focused: false, state: 'normal' }]);
socket.sendNotice.mockResolvedValueOnce(true).mockResolvedValueOnce(false);
expect(await noticeOnDevice(done, 7)).toBe(true);
expect(await noticeOnDevice({ ...done, id: 'monitor:other' }, 8)).toBe(false);
});
it('brings the notice’s own tab forward when it is clicked, restoring a minimized window first', async () => {
windows([{ id: 4, focused: false, state: 'minimized' }, { id: 5, focused: false, state: 'minimized' }], [{ id: 7, windowId: 5 }]);
serveDeviceNotices();
socket.sendNotice.mockResolvedValue(true);
await noticeOnDevice(done, 7);
socket.opened!(done.id);
await vi.waitFor(() => expect(toast.goToTab).toHaveBeenCalledWith(7));
expect(fakeBrowser.windows.update).toHaveBeenNthCalledWith(1, 5, { state: 'normal' });
expect(fakeBrowser.windows.update).toHaveBeenNthCalledWith(2, 5, { focused: true });
});
it('leaves Firefox to restore a minimized window as it was, maximized or not, by focusing it', async () => {
vi.stubEnv('FIREFOX', 'true');
windows([{ id: 5, focused: false, state: 'minimized' }], [{ id: 7, windowId: 5 }]);
serveDeviceNotices();
socket.sendNotice.mockResolvedValue(true);
await noticeOnDevice(done, 7);
socket.opened!(done.id);
await vi.waitFor(() => expect(toast.goToTab).toHaveBeenCalledWith(7));
expect(vi.mocked(fakeBrowser.windows.update).mock.calls).toEqual([[5, { focused: true }]]);
});
it('keeps the tab of a notice that repeats, however many others came between', async () => {
windows([{ id: 4, focused: false, state: 'normal' }], [{ id: 7, windowId: 4 }]);
serveDeviceNotices();
socket.sendNotice.mockResolvedValue(true);
await noticeOnDevice({ ...done, id: 'timer:t1' }, 99);
for (let index = 0; index < 29; index++) await noticeOnDevice({ ...done, id: `monitor:m${index}` }, 100 + index);
await noticeOnDevice({ ...done, id: 'timer:t1' }, 7);
await noticeOnDevice({ ...done, id: 'monitor:last' }, 200);
socket.opened!('timer:t1');
await vi.waitFor(() => expect(toast.goToTab).toHaveBeenCalledWith(7));
});
it('brings a window forward for a notice that had no tab', async () => {
windows([{ id: 4, focused: false, state: 'normal' }]);
serveDeviceNotices();
socket.sendNotice.mockResolvedValue(true);
await noticeOnDevice({ ...done, id: 'task:t1' });
socket.opened!('task:t1');
await vi.waitFor(() => expect(fakeBrowser.windows.update).toHaveBeenCalledWith(4, { focused: true }));
expect(fakeBrowser.windows.update).not.toHaveBeenCalledWith(4, { state: 'normal' });
expect(toast.goToTab).not.toHaveBeenCalled();
});
});