Skip to content

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.

11.3 KB
Raw Blame
import { readFileSync } from 'node:fs';
import { afterEach, describe, expect, test, vi } from 'vitest';
import type { AndroidState } from '@/lib/phone/types';
import type { AdbFound } from './adb';
import { AdbServerError, type AdbServer } from './adb-server';
import { INSTALL_CHROME_COMMAND, launchChromeCommand } from './launch';
import { FACTS_COMMAND } from './phone-facts';
import { startAndroid, type Android, type AndroidDeps } from './service';

const fixture = (name: string) => readFileSync(new URL(`./fixtures/${name}`, import.meta.url), 'utf8');
const ADB: AdbFound = { path: '/sdk/platform-tools/adb', version: '37.0.0-14910828' };
const SOCKET_LINE = '0000000000000000: 00000002 00000000 00010000 0001 01 50526 @chrome_devtools_remote\n';

/** adb's server held in memory: a phone whose state the test sets, and a record of everything asked of it. */
class MemoryAdb implements AdbServer {
  running = true;
  list = fixture('devices-emulator.txt');
  /** Null is a phone that does not answer in time. */
  facts: string | null = fixture('facts-chrome-open.txt');
  readonly shells: string[] = [];
  trackers = 0;
  private onList?: (list: string) => void;
  private onEnd?: (error: AdbServerError) => void;

  private serving<T>(value: T): Promise<T> {
    return this.running ? Promise.resolve(value) : Promise.reject(new AdbServerError('NO_SERVER', 'connect ECONNREFUSED'));
  }

  version = () => this.serving(41);
  devices = () => this.serving(this.list);

  track(onList: (list: string) => void, onEnd: (error: AdbServerError) => void): () => void {
    this.trackers++;
    this.onList = onList;
    this.onEnd = onEnd;
    queueMicrotask(() => onList(this.list));
    return () => {
      this.trackers--;
      this.onList = this.onEnd = undefined;
    };
  }

  async shell(_serial: string, command: string): Promise<string> {
    this.shells.push(command);
    if (command === FACTS_COMMAND) {
      if (this.facts === null) throw new AdbServerError('TIMEOUT', 'adb did not answer within 5000 ms');
      return this.facts;
    }
    if (command.startsWith('am start -n') || command.includes('-n com.android.chrome/')) this.facts = fixture('facts-chrome-open.txt');
    if (command.startsWith('grep')) return this.facts?.includes('@chrome_devtools_remote') ? SOCKET_LINE : '';
    return '';
  }

  forward = () => Promise.resolve(50_000);
  removeForward = () => Promise.resolve();

  plug(list: string): void {
    this.list = list;
    this.onList?.(list);
  }

  die(): void {
    this.running = false;
    this.onEnd?.(new AdbServerError('CLOSED', 'adb closed the connection'));
  }
}

let adb: MemoryAdb;
let android: Android;
let deps: AndroidDeps & { locate: ReturnType<typeof vi.fn>; startServer: ReturnType<typeof vi.fn> };

function start(overrides: Partial<AndroidDeps> = {}): Android {
  adb = new MemoryAdb();
  deps = {
    settings: () => ({ enabled: true }),
    locate: vi.fn(async () => ADB),
    startServer: vi.fn(async () => {
      adb.running = true;
      return true;
    }),
    server: adb,
    platform: 'darwin',
    ...overrides,
  } as typeof deps;
  android = startAndroid(deps);
  return android;
}

afterEach(async () => {
  await android?.stop();
  vi.useRealTimers();
});

const heard = () => {
  const states: AndroidState[] = [];
  return { states, listener: (state: AndroidState) => states.push(state) };
};

const until = async (done: () => boolean) => {
  for (let tries = 0; !done(); tries++) {
    if (tries > 200) throw new Error('timed out waiting');
    await new Promise((resolve) => setTimeout(resolve, 2));
  }
};

describe('the Bridge\'s view of the phones', () => {
  test('asked with nobody watching, it lists the phones once and tracks nothing', async () => {
    const state = await start().state();
    expect(state).toMatchObject({ ready: true, adb: { found: true, path: ADB.path } });
    expect([adb.trackers, adb.shells]).toEqual([0, [FACTS_COMMAND]]);
  });

  test('a watcher hears the state, then each change the device list brings, and letting go stops the tracking', async () => {
    start();
    const { states, listener } = heard();
    const release = android.watch(listener);
    await until(() => states.length === 1);
    expect(states[0].ready).toBe(true);
    expect(adb.trackers).toBe(1);

    adb.plug(fixture('devices-offline.txt'));
    await until(() => states.length === 2);
    expect(states[1].problem?.code).toBe('DEVICE_OFFLINE');

    adb.plug(fixture('devices-none.txt'));
    await until(() => states.length === 3);
    expect(states[2].problem?.code).toBe('NO_DEVICE');

    release();
    expect(adb.trackers).toBe(0);
  });

  test('every five seconds the phone is asked again, and an unchanged answer is not sent again', async () => {
    vi.useFakeTimers();
    start();
    const { states, listener } = heard();
    android.watch(listener);
    await vi.advanceTimersByTimeAsync(10);
    const asked = adb.shells.length;
    await vi.advanceTimersByTimeAsync(5_000);
    expect(adb.shells.length).toBe(asked + 1);
    expect(states).toHaveLength(1);

    adb.facts = fixture('facts-chrome-closed.txt');
    await vi.advanceTimersByTimeAsync(5_000);
    expect(states.map((state) => state.problem?.code)).toEqual([undefined, 'CHROME_NOT_RUNNING']);
  });

  test('a second watcher hears what is known at once, without asking the phone again', async () => {
    start();
    const first = heard();
    android.watch(first.listener);
    await until(() => first.states.length === 1);
    const asked = adb.shells.length;
    const second = heard();
    android.watch(second.listener);
    await until(() => second.states.length === 1);
    expect(second.states[0]).toEqual(first.states[0]);
    expect(adb.shells.length).toBe(asked);
  });

  test('switched off, it never looks for adb', async () => {
    const state = await start({ settings: () => ({ enabled: false }) }).state();
    expect(state).toMatchObject({ enabled: false, problem: { code: 'ANDROID_OFF' } });
    expect(deps.locate).not.toHaveBeenCalled();
    expect(adb.shells).toEqual([]);
  });

  test('with no adb server running, it starts one with the adb it found, once', async () => {
    start();
    adb.running = false;
    expect((await android.state()).ready).toBe(true);
    expect(deps.startServer.mock.calls).toEqual([[ADB.path]]);
  });

  test('a server that will not start is reported against adb', async () => {
    start({ startServer: vi.fn(async () => false) });
    adb.running = false;
    expect(await android.state()).toMatchObject({ ready: false, problem: { code: 'ADB_BROKEN' } });
  });

  test('a missing adb is looked for again each time, and one installed later is used', async () => {
    start();
    deps.locate.mockResolvedValueOnce(null);
    expect((await android.state()).problem?.code).toBe('ADB_MISSING');
    expect((await android.state()).ready).toBe(true);
    expect(deps.locate).toHaveBeenCalledTimes(2);
    await android.state();
    expect(deps.locate).toHaveBeenCalledTimes(2);
  });

  test('letting go while the watch is still starting leaves nothing tracking, so a later look reads the phone again', async () => {
    start();
    let answer: (() => void) | undefined;
    adb.version = () => new Promise((resolve) => (answer = () => resolve(41)));
    const release = android.watch(() => {});
    await until(() => answer !== undefined);
    release();
    answer?.();
    await android.state();
    expect([adb.trackers, android.peek()]).toEqual([0, null]);

    adb.facts = fixture('facts-chrome-closed.txt');
    expect((await android.state()).problem?.code).toBe('CHROME_NOT_RUNNING');
  });

  test('when adb\'s server goes away while watched, it watches again', async () => {
    vi.useFakeTimers();
    start();
    const { states, listener } = heard();
    android.watch(listener);
    await vi.advanceTimersByTimeAsync(10);
    adb.die();
    expect(adb.trackers).toBe(1);
    await vi.advanceTimersByTimeAsync(2_000);
    expect(deps.startServer).toHaveBeenCalledTimes(1);
    expect(adb.trackers).toBe(2);
    expect(states.at(-1)?.ready).toBe(true);
  });
});

describe('opening Chrome on the phone', () => {
  test('a closed Chrome is started, and the answer is the state once its socket is open', async () => {
    start();
    adb.facts = fixture('facts-chrome-closed.txt');
    const result = await android.launch('emulator-5554');
    expect(result).toMatchObject({ ok: true, data: { ready: true } });
    expect(adb.shells).toContain(launchChromeCommand());
  });

  test('a URL rides along with the start', async () => {
    start();
    adb.facts = fixture('facts-chrome-closed.txt');
    await android.launch('emulator-5554', 'https://example.com/a');
    expect(adb.shells).toContain(launchChromeCommand('https://example.com/a'));
    expect(launchChromeCommand('https://example.com/a')).toMatch(/-a android\.intent\.action\.VIEW -d 'https:\/\/example\.com\/a' -n /);
    expect(launchChromeCommand("https://example.com/it's")).toContain("'https://example.com/it'\\''s'");
    expect(launchChromeCommand('javascript:alert(1)')).toBe(launchChromeCommand());
  });

  test('an open Chrome is left alone, unless a page was asked for, which opens in a new tab', async () => {
    start();
    await android.launch('emulator-5554');
    expect(adb.shells.filter((command) => command.startsWith('am start'))).toEqual([]);
    await android.launch('emulator-5554', 'https://example.com/');
    expect(adb.shells.filter((command) => command.startsWith('am start'))).toEqual([launchChromeCommand('https://example.com/')]);
  });

  test('a peek knows nothing until someone watches, and never asks the phone', async () => {
    start();
    expect(android.peek()).toBeNull();
    const { states, listener } = heard();
    const release = android.watch(listener);
    await until(() => states.length === 1);
    const asked = adb.shells.length;
    expect(android.peek()).toEqual(states[0]);
    expect(adb.shells.length).toBe(asked);
    release();
    expect(android.peek()).toBeNull();
  });

  test('a missing Chrome opens its Play Store page instead', async () => {
    start();
    adb.facts = fixture('facts-chrome-open.txt').replace(/(@@browsentic:chrome\n)(package:[^\n]*\n)+/, '$1');
    await android.launch('emulator-5554');
    expect(adb.shells).toContain(INSTALL_CHROME_COMMAND);
  });

  test('a phone that does not answer, or is still starting, is refused rather than sent to the Play Store', async () => {
    start();
    adb.facts = null;
    expect(await android.launch('emulator-5554')).toMatchObject({ ok: false, error: { code: 'DEVICE_OFFLINE' } });
    adb.facts = fixture('facts-chrome-open.txt').replace('@@browsentic:booted\n1\n', '@@browsentic:booted\n').replace(/(@@browsentic:chrome\n)(package:[^\n]*\n)+/, '$1');
    expect(await android.launch('emulator-5554')).toMatchObject({ ok: false, error: { code: 'DEVICE_BOOTING' } });
    expect(adb.shells.filter((command) => command.startsWith('am start'))).toEqual([]);
  });

  test('a phone that is not connected, or not ready, is refused with its reason', async () => {
    start();
    expect(await android.launch('R5CT1234567')).toMatchObject({ ok: false, error: { code: 'NO_DEVICE' } });
    adb.list = fixture('devices-unauthorized.handwritten.txt');
    expect(await android.launch('R5CT1234567')).toMatchObject({ ok: false, error: { code: 'DEVICE_UNAUTHORIZED' } });
    adb.list = fixture('devices-none.txt');
    expect(await android.launch('R5CT1234567')).toMatchObject({ ok: false, error: { code: 'NO_DEVICE' } });
  });
});