@askjo/camoufox-browser 1.0.0

package/tests/e2e/tabLifecycle.test.js

@@ -0,0 +1,149 @@
+const { startJoBrowser, stopJoBrowser, getServerUrl } = require('../helpers/startJoBrowser');
+const { startTestSite, stopTestSite, getTestSiteUrl } = require('../helpers/testSite');
+const { createClient } = require('../helpers/client');
+
+describe('Tab Lifecycle', () => {
+  let serverUrl;
+  let testSiteUrl;
+  
+  beforeAll(async () => {
+    const port = await startJoBrowser();
+    serverUrl = getServerUrl();
+    
+    const testPort = await startTestSite();
+    testSiteUrl = getTestSiteUrl();
+  }, 120000);
+  
+  afterAll(async () => {
+    await stopTestSite();
+    await stopJoBrowser();
+  }, 30000);
+  
+  test('health check returns camoufox engine', async () => {
+    const client = createClient(serverUrl);
+    const health = await client.health();
+    
+    expect(health.ok).toBe(true);
+    expect(health.engine).toBe('camoufox');
+  });
+  
+  test('create tab without URL', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const result = await client.createTab();
+      
+      expect(result.tabId).toBeDefined();
+      expect(typeof result.tabId).toBe('string');
+      expect(result.url).toBe('about:blank');
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('create tab with URL', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const result = await client.createTab(`${testSiteUrl}/pageA`);
+      
+      expect(result.tabId).toBeDefined();
+      expect(result.url).toContain('/pageA');
+      
+      const snapshot = await client.getSnapshot(result.tabId);
+      expect(snapshot.snapshot).toContain('Page A');
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('create multiple tabs in same group', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const tab1 = await client.createTab(`${testSiteUrl}/pageA`);
+      const tab2 = await client.createTab(`${testSiteUrl}/pageB`);
+      
+      expect(tab1.tabId).not.toBe(tab2.tabId);
+      
+      const snapshot1 = await client.getSnapshot(tab1.tabId);
+      const snapshot2 = await client.getSnapshot(tab2.tabId);
+      
+      expect(snapshot1.snapshot).toContain('Page A');
+      expect(snapshot2.snapshot).toContain('Page B');
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('close individual tab', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const tab1 = await client.createTab(`${testSiteUrl}/pageA`);
+      const tab2 = await client.createTab(`${testSiteUrl}/pageB`);
+      
+      await client.closeTab(tab1.tabId);
+      
+      // Tab 1 should be gone
+      await expect(client.getSnapshot(tab1.tabId)).rejects.toThrow();
+      
+      // Tab 2 should still work
+      const snapshot2 = await client.getSnapshot(tab2.tabId);
+      expect(snapshot2.snapshot).toContain('Page B');
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('close tab group', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const tab1 = await client.createTab(`${testSiteUrl}/pageA`);
+      const tab2 = await client.createTab(`${testSiteUrl}/pageB`);
+      
+      await client.closeTabGroup();
+      
+      // Both tabs should be gone
+      await expect(client.getSnapshot(tab1.tabId)).rejects.toThrow();
+      await expect(client.getSnapshot(tab2.tabId)).rejects.toThrow();
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('close session clears all tabs', async () => {
+    const client = createClient(serverUrl);
+    
+    const tab = await client.createTab(`${testSiteUrl}/pageA`);
+    
+    await client.closeSession();
+    
+    // Tab should be gone after session close
+    await expect(client.getSnapshot(tab.tabId)).rejects.toThrow();
+  });
+  
+  test('tab stats are tracked correctly', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const { tabId } = await client.createTab(`${testSiteUrl}/pageA`);
+      
+      // Make some operations
+      await client.getSnapshot(tabId);
+      await client.navigate(tabId, `${testSiteUrl}/pageB`);
+      await client.getSnapshot(tabId);
+      
+      const stats = await client.getStats(tabId);
+      
+      expect(stats.tabId).toBe(tabId);
+      expect(stats.listItemId).toBe(client.listItemId);
+      expect(stats.url).toContain('/pageB');
+      expect(stats.toolCalls).toBeGreaterThan(0);
+      expect(stats.visitedUrls).toContain(`${testSiteUrl}/pageA`);
+    } finally {
+      await client.cleanup();
+    }
+  });
+});

package/tests/e2e/typingEnter.test.js

@@ -0,0 +1,147 @@
+const { startJoBrowser, stopJoBrowser, getServerUrl } = require('../helpers/startJoBrowser');
+const { startTestSite, stopTestSite, getTestSiteUrl } = require('../helpers/testSite');
+const { createClient } = require('../helpers/client');
+
+describe('Typing and Enter', () => {
+  let serverUrl;
+  let testSiteUrl;
+  
+  beforeAll(async () => {
+    const port = await startJoBrowser();
+    serverUrl = getServerUrl();
+    
+    const testPort = await startTestSite();
+    testSiteUrl = getTestSiteUrl();
+  }, 120000);
+  
+  afterAll(async () => {
+    await stopTestSite();
+    await stopJoBrowser();
+  }, 30000);
+  
+  test('type text into input field', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const { tabId } = await client.createTab(`${testSiteUrl}/typing`);
+      
+      // Type using selector
+      const result = await client.type(tabId, {
+        selector: '#input',
+        text: 'Hello World'
+      });
+      
+      expect(result.ok).toBe(true);
+      
+      // Verify the text appears in preview
+      const snapshot = await client.waitForSnapshotContains(tabId, 'Preview: Hello World');
+      expect(snapshot.snapshot).toContain('Hello World');
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('type text using ref', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const { tabId } = await client.createTab(`${testSiteUrl}/typing`);
+      
+      // Get snapshot to find the input ref
+      const snapshot = await client.getSnapshot(tabId);
+      
+      // Find a ref for the textbox (look for pattern like [e1] textbox)
+      const match = snapshot.snapshot.match(/\[(e\d+)\].*textbox/i);
+      if (!match) {
+        // Try by selector if ref not found
+        await client.type(tabId, { selector: '#input', text: 'Test via selector' });
+      } else {
+        const ref = match[1];
+        await client.type(tabId, { ref, text: 'Test via ref' });
+      }
+      
+      const updatedSnapshot = await client.getSnapshot(tabId);
+      expect(updatedSnapshot.snapshot).toMatch(/Preview: Test via (ref|selector)/);
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('type and press Enter navigates page', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const { tabId } = await client.createTab(`${testSiteUrl}/enter`);
+      
+      // Type and press Enter
+      await client.type(tabId, {
+        selector: '#searchInput',
+        text: 'test query',
+        pressEnter: true
+      });
+      
+      // Wait for navigation to /entered
+      const snapshot = await client.waitForUrl(tabId, '/entered');
+      
+      expect(snapshot.url).toContain('/entered');
+      expect(snapshot.url).toContain('value=test%20query');
+      expect(snapshot.snapshot).toContain('Entered: test query');
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('type without Enter does not navigate', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const { tabId } = await client.createTab(`${testSiteUrl}/enter`);
+      
+      // Type without pressing Enter
+      await client.type(tabId, {
+        selector: '#searchInput',
+        text: 'should not navigate',
+        pressEnter: false
+      });
+      
+      // Wait a bit to ensure no navigation happened
+      await new Promise(r => setTimeout(r, 500));
+      
+      const snapshot = await client.getSnapshot(tabId);
+      expect(snapshot.url).toContain('/enter');
+      expect(snapshot.url).not.toContain('/entered');
+    } finally {
+      await client.cleanup();
+    }
+  });
+  
+  test('type replaces existing content', async () => {
+    const client = createClient(serverUrl);
+    
+    try {
+      const { tabId } = await client.createTab(`${testSiteUrl}/typing`);
+      
+      // Type first text
+      await client.type(tabId, {
+        selector: '#input',
+        text: 'First text'
+      });
+      
+      let snapshot = await client.waitForSnapshotContains(tabId, 'Preview: First text');
+      expect(snapshot.snapshot).toContain('First text');
+      
+      // Type second text (should replace due to clear behavior)
+      await client.type(tabId, {
+        selector: '#input',
+        text: 'Second text',
+        clear: true
+      });
+      
+      snapshot = await client.waitForSnapshotContains(tabId, 'Preview: Second text');
+      expect(snapshot.snapshot).toContain('Second text');
+      expect(snapshot.snapshot).not.toContain('First text');
+    } finally {
+      await client.cleanup();
+    }
+  });
+});

package/tests/helpers/client.js

@@ -0,0 +1,222 @@
+const crypto = require('crypto');
+
+class BrowserClient {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+    this.userId = crypto.randomUUID();
+    this.listItemId = crypto.randomUUID();
+    this.tabs = [];
+    this.timeout = 30000; // 30 second default timeout
+  }
+  
+  async request(method, path, body = null, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), options.timeout || this.timeout);
+    
+    try {
+      const fetchOptions = {
+        method,
+        headers: { 'Content-Type': 'application/json' },
+        signal: controller.signal
+      };
+      
+      if (body) {
+        fetchOptions.body = JSON.stringify(body);
+      }
+      
+      const response = await fetch(url, fetchOptions);
+      clearTimeout(timeoutId);
+      
+      const contentType = response.headers.get('content-type');
+      if (contentType?.includes('application/json')) {
+        const data = await response.json();
+        if (!response.ok) {
+          const error = new Error(data.error || `HTTP ${response.status}`);
+          error.status = response.status;
+          error.data = data;
+          throw error;
+        }
+        return data;
+      } else if (contentType?.includes('image/')) {
+        return await response.arrayBuffer();
+      } else {
+        return await response.text();
+      }
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err.name === 'AbortError') {
+        throw new Error(`Request timeout after ${options.timeout || this.timeout}ms: ${method} ${path}`);
+      }
+      throw err;
+    }
+  }
+  
+  // Health check
+  async health() {
+    return this.request('GET', '/health');
+  }
+  
+  // Tab management
+  async createTab(url = null) {
+    const body = { userId: this.userId, listItemId: this.listItemId };
+    if (url) body.url = url;
+    
+    const result = await this.request('POST', '/tabs', body);
+    if (result.tabId) {
+      this.tabs.push(result.tabId);
+    }
+    return result;
+  }
+  
+  async navigate(tabId, urlOrMacro) {
+    // Support both regular URLs and @macro syntax
+    if (urlOrMacro.startsWith('@')) {
+      const [macro, ...queryParts] = urlOrMacro.split(' ');
+      const query = queryParts.join(' ');
+      return this.request('POST', `/tabs/${tabId}/navigate`, { userId: this.userId, macro, query });
+    }
+    return this.request('POST', `/tabs/${tabId}/navigate`, { userId: this.userId, url: urlOrMacro });
+  }
+  
+  async getSnapshot(tabId) {
+    return this.request('GET', `/tabs/${tabId}/snapshot?userId=${this.userId}`);
+  }
+  
+  async click(tabId, options) {
+    return this.request('POST', `/tabs/${tabId}/click`, { userId: this.userId, ...options });
+  }
+  
+  async type(tabId, options) {
+    const { pressEnter, clear, ...typeOptions } = options;
+    
+    // Handle clear by selecting all first
+    if (clear && (options.selector || options.ref)) {
+      // Click to focus, then select all and type to replace
+      await this.click(tabId, { selector: options.selector, ref: options.ref });
+      await this.press(tabId, 'Control+a');
+    }
+    
+    const result = await this.request('POST', `/tabs/${tabId}/type`, { userId: this.userId, ...typeOptions });
+    
+    // Handle Enter key press after typing
+    if (pressEnter) {
+      await this.press(tabId, 'Enter');
+    }
+    
+    return result;
+  }
+  
+  async press(tabId, key) {
+    return this.request('POST', `/tabs/${tabId}/press`, { userId: this.userId, key });
+  }
+  
+  async scroll(tabId, options) {
+    return this.request('POST', `/tabs/${tabId}/scroll`, { userId: this.userId, ...options });
+  }
+  
+  async back(tabId) {
+    return this.request('POST', `/tabs/${tabId}/back`, { userId: this.userId });
+  }
+  
+  async forward(tabId) {
+    return this.request('POST', `/tabs/${tabId}/forward`, { userId: this.userId });
+  }
+  
+  async refresh(tabId) {
+    return this.request('POST', `/tabs/${tabId}/refresh`, { userId: this.userId });
+  }
+  
+  async getLinks(tabId, options = {}) {
+    const params = new URLSearchParams({ userId: this.userId });
+    if (options.limit) params.append('limit', options.limit);
+    if (options.offset) params.append('offset', options.offset);
+    return this.request('GET', `/tabs/${tabId}/links?${params}`);
+  }
+  
+  async getStats(tabId) {
+    return this.request('GET', `/tabs/${tabId}/stats?userId=${this.userId}`);
+  }
+  
+  async screenshot(tabId, fullPage = false) {
+    return this.request('GET', `/tabs/${tabId}/screenshot?userId=${this.userId}&fullPage=${fullPage}`);
+  }
+  
+  async closeTab(tabId) {
+    const result = await this.request('DELETE', `/tabs/${tabId}`, { userId: this.userId });
+    this.tabs = this.tabs.filter(t => t !== tabId);
+    return result;
+  }
+  
+  async closeTabGroup(listItemId = null) {
+    return this.request('DELETE', `/tabs/group/${listItemId || this.listItemId}`, { userId: this.userId });
+  }
+  
+  async closeSession() {
+    return this.request('DELETE', `/sessions/${this.userId}`);
+  }
+  
+  // Cleanup all tabs created by this client
+  async cleanup() {
+    for (const tabId of [...this.tabs]) {
+      try {
+        await this.closeTab(tabId);
+      } catch (e) {
+        // Tab may already be closed
+      }
+    }
+    try {
+      await this.closeSession();
+    } catch (e) {
+      // Session may already be closed
+    }
+  }
+  
+  // Wait for snapshot to contain specific text (polling)
+  async waitForSnapshotContains(tabId, text, options = {}) {
+    const maxWait = options.maxWait || 10000;
+    const interval = options.interval || 500;
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < maxWait) {
+      const snapshot = await this.getSnapshot(tabId);
+      if (snapshot.snapshot && snapshot.snapshot.includes(text)) {
+        return snapshot;
+      }
+      await new Promise(r => setTimeout(r, interval));
+    }
+    
+    throw new Error(`Timeout waiting for snapshot to contain "${text}"`);
+  }
+  
+  // Wait for URL to match pattern
+  async waitForUrl(tabId, pattern, options = {}) {
+    const maxWait = options.maxWait || 10000;
+    const interval = options.interval || 500;
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < maxWait) {
+      const snapshot = await this.getSnapshot(tabId);
+      const url = snapshot.url;
+      
+      if (typeof pattern === 'string' && url.includes(pattern)) {
+        return snapshot;
+      } else if (pattern instanceof RegExp && pattern.test(url)) {
+        return snapshot;
+      }
+      
+      await new Promise(r => setTimeout(r, interval));
+    }
+    
+    throw new Error(`Timeout waiting for URL to match ${pattern}`);
+  }
+}
+
+function createClient(baseUrl) {
+  return new BrowserClient(baseUrl);
+}
+
+module.exports = {
+  BrowserClient,
+  createClient
+};

package/tests/helpers/startJoBrowser.js

@@ -0,0 +1,95 @@
+const { spawn } = require('child_process');
+const path = require('path');
+
+let serverProcess = null;
+let serverPort = null;
+
+async function waitForServer(port, maxRetries = 30, interval = 1000) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const response = await fetch(`http://localhost:${port}/health`);
+      if (response.ok) {
+        return true;
+      }
+    } catch (e) {
+      // Server not ready yet
+    }
+    await new Promise(r => setTimeout(r, interval));
+  }
+  throw new Error(`Server failed to start on port ${port} after ${maxRetries} attempts`);
+}
+
+async function startJoBrowser(port = 0) {
+  // Use a random available port if not specified
+  const usePort = port || Math.floor(3100 + Math.random() * 900);
+  
+  const serverPath = path.join(__dirname, '../../server-camoufox.js');
+  
+  serverProcess = spawn('node', [serverPath], {
+    env: { ...process.env, PORT: usePort.toString(), DEBUG_RESPONSES: 'false' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: false
+  });
+  
+  serverProcess.stdout.on('data', (data) => {
+    if (process.env.DEBUG_SERVER) {
+      console.log(`[server] ${data.toString().trim()}`);
+    }
+  });
+  
+  serverProcess.stderr.on('data', (data) => {
+    if (process.env.DEBUG_SERVER) {
+      console.error(`[server:err] ${data.toString().trim()}`);
+    }
+  });
+  
+  serverProcess.on('error', (err) => {
+    console.error('Failed to start server:', err);
+  });
+  
+  serverPort = usePort;
+  
+  // Wait for server to be ready
+  await waitForServer(usePort);
+  
+  console.log(`jo-browser server started on port ${usePort}`);
+  return usePort;
+}
+
+async function stopJoBrowser() {
+  if (serverProcess) {
+    return new Promise((resolve) => {
+      serverProcess.on('close', () => {
+        serverProcess = null;
+        serverPort = null;
+        resolve();
+      });
+      
+      // Send SIGTERM for graceful shutdown
+      serverProcess.kill('SIGTERM');
+      
+      // Force kill after 5 seconds if still running
+      setTimeout(() => {
+        if (serverProcess) {
+          serverProcess.kill('SIGKILL');
+        }
+      }, 5000);
+    });
+  }
+}
+
+function getServerUrl() {
+  if (!serverPort) throw new Error('Server not started');
+  return `http://localhost:${serverPort}`;
+}
+
+function getServerPort() {
+  return serverPort;
+}
+
+module.exports = {
+  startJoBrowser,
+  stopJoBrowser,
+  getServerUrl,
+  getServerPort
+};