illuma-agents 1.0.18 → 1.0.19

package/src/tools/BrowserTools.test.ts

@@ -0,0 +1,528 @@
+import {
+  createBrowserClickTool,
+  createBrowserTypeTool,
+  createBrowserNavigateTool,
+  createBrowserScrollTool,
+  createBrowserExtractTool,
+  createBrowserHoverTool,
+  createBrowserWaitTool,
+  createBrowserGoBackTool,
+  createBrowserScreenshotTool,
+  createBrowserTools,
+  EBrowserTools,
+  BROWSER_TOOL_NAMES,
+  isBrowserToolCall,
+  hasBrowserCapability,
+  type BrowserToolsConfig,
+} from './BrowserTools';
+
+describe('BrowserTools', () => {
+  // ============================================
+  // EBrowserTools Enum Tests
+  // ============================================
+  describe('EBrowserTools enum', () => {
+    it('should have all expected tool names', () => {
+      expect(EBrowserTools.CLICK).toBe('browser_click');
+      expect(EBrowserTools.TYPE).toBe('browser_type');
+      expect(EBrowserTools.NAVIGATE).toBe('browser_navigate');
+      expect(EBrowserTools.SCROLL).toBe('browser_scroll');
+      expect(EBrowserTools.EXTRACT).toBe('browser_extract');
+      expect(EBrowserTools.HOVER).toBe('browser_hover');
+      expect(EBrowserTools.WAIT).toBe('browser_wait');
+      expect(EBrowserTools.BACK).toBe('browser_back');
+      expect(EBrowserTools.SCREENSHOT).toBe('browser_screenshot');
+    });
+
+    it('should have exactly 9 tool names', () => {
+      expect(Object.keys(EBrowserTools)).toHaveLength(9);
+    });
+  });
+
+  // ============================================
+  // BROWSER_TOOL_NAMES Tests
+  // ============================================
+  describe('BROWSER_TOOL_NAMES', () => {
+    it('should contain all tool names from enum', () => {
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.CLICK);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.TYPE);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.NAVIGATE);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.SCROLL);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.EXTRACT);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.HOVER);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.WAIT);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.BACK);
+      expect(BROWSER_TOOL_NAMES).toContain(EBrowserTools.SCREENSHOT);
+    });
+
+    it('should have exactly 9 entries', () => {
+      expect(BROWSER_TOOL_NAMES).toHaveLength(9);
+    });
+  });
+
+  // ============================================
+  // isBrowserToolCall Tests
+  // ============================================
+  describe('isBrowserToolCall', () => {
+    it('should return true for valid browser tool names', () => {
+      expect(isBrowserToolCall('browser_click')).toBe(true);
+      expect(isBrowserToolCall('browser_type')).toBe(true);
+      expect(isBrowserToolCall('browser_navigate')).toBe(true);
+      expect(isBrowserToolCall('browser_scroll')).toBe(true);
+      expect(isBrowserToolCall('browser_extract')).toBe(true);
+      expect(isBrowserToolCall('browser_hover')).toBe(true);
+      expect(isBrowserToolCall('browser_wait')).toBe(true);
+      expect(isBrowserToolCall('browser_back')).toBe(true);
+      expect(isBrowserToolCall('browser_screenshot')).toBe(true);
+    });
+
+    it('should return false for non-browser tool names', () => {
+      expect(isBrowserToolCall('calculator')).toBe(false);
+      expect(isBrowserToolCall('web_search')).toBe(false);
+      expect(isBrowserToolCall('code_execution')).toBe(false);
+      expect(isBrowserToolCall('random_tool')).toBe(false);
+      expect(isBrowserToolCall('')).toBe(false);
+    });
+
+    it('should return false for similar but incorrect names', () => {
+      expect(isBrowserToolCall('browser_Click')).toBe(false); // case sensitive
+      expect(isBrowserToolCall('click')).toBe(false);
+      expect(isBrowserToolCall('browser-click')).toBe(false); // wrong separator
+      expect(isBrowserToolCall('browserclick')).toBe(false);
+    });
+  });
+
+  // ============================================
+  // hasBrowserCapability Tests
+  // ============================================
+  describe('hasBrowserCapability', () => {
+    it('should return true when x-ranger-browser-extension header is "true"', () => {
+      expect(hasBrowserCapability({ 'x-ranger-browser-extension': 'true' })).toBe(true);
+    });
+
+    it('should return true when x-ranger-browser-capable header is "true"', () => {
+      expect(hasBrowserCapability({ 'x-ranger-browser-capable': 'true' })).toBe(true);
+    });
+
+    it('should return true when header is array containing "true"', () => {
+      expect(hasBrowserCapability({ 'x-ranger-browser-extension': ['true', 'other'] })).toBe(true);
+      expect(hasBrowserCapability({ 'x-ranger-browser-capable': ['true'] })).toBe(true);
+    });
+
+    it('should return false when headers are missing', () => {
+      expect(hasBrowserCapability({})).toBe(false);
+    });
+
+    it('should return false when header value is "false"', () => {
+      expect(hasBrowserCapability({ 'x-ranger-browser-extension': 'false' })).toBe(false);
+    });
+
+    it('should return false when header value is undefined', () => {
+      expect(hasBrowserCapability({ 'x-ranger-browser-extension': undefined })).toBe(false);
+    });
+
+    it('should return false when array does not contain "true"', () => {
+      expect(hasBrowserCapability({ 'x-ranger-browser-extension': ['false', 'other'] })).toBe(false);
+    });
+
+    it('should handle mixed case and other headers', () => {
+      // Only exact match should work
+      expect(hasBrowserCapability({ 
+        'x-ranger-browser-extension': 'false',
+        'x-ranger-browser-capable': 'true' 
+      })).toBe(true);
+    });
+  });
+
+  // ============================================
+  // Individual Tool Creation Tests
+  // ============================================
+  describe('createBrowserClickTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserClickTool();
+      expect(tool.name).toBe(EBrowserTools.CLICK);
+    });
+
+    it('should have a description', () => {
+      const tool = createBrowserClickTool();
+      expect(tool.description).toBeTruthy();
+      expect(tool.description.length).toBeGreaterThan(0);
+    });
+
+    it('should return browser_action with index', async () => {
+      const tool = createBrowserClickTool();
+      const result = await tool.invoke({ index: 5, reason: 'clicking button' });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('click');
+      expect(parsed.action.index).toBe(5);
+      expect(parsed.action.reason).toBe('clicking button');
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+
+    it('should return browser_action with coordinates', async () => {
+      const tool = createBrowserClickTool();
+      const result = await tool.invoke({ 
+        coordinates: { x: 100, y: 200 },
+        visualDescription: 'blue button' 
+      });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('click');
+      expect(parsed.action.coordinates).toEqual({ x: 100, y: 200 });
+      expect(parsed.action.visualDescription).toBe('blue button');
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+
+    it('should return error when neither index nor coordinates provided', async () => {
+      const tool = createBrowserClickTool();
+      const result = await tool.invoke({});
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('error');
+      expect(parsed.error).toContain('Either index or coordinates must be provided');
+    });
+  });
+
+  describe('createBrowserTypeTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserTypeTool();
+      expect(tool.name).toBe(EBrowserTools.TYPE);
+    });
+
+    it('should return browser_action for typing', async () => {
+      const tool = createBrowserTypeTool();
+      const result = await tool.invoke({ 
+        index: 2, 
+        text: 'Hello World',
+        clear: true,
+        pressEnter: true 
+      });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('type');
+      expect(parsed.action.index).toBe(2);
+      expect(parsed.action.text).toBe('Hello World');
+      expect(parsed.action.clear).toBe(true);
+      expect(parsed.action.pressEnter).toBe(true);
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+
+    it('should default clear and pressEnter to false', async () => {
+      const tool = createBrowserTypeTool();
+      const result = await tool.invoke({ index: 1, text: 'test' });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.action.clear).toBe(false);
+      expect(parsed.action.pressEnter).toBe(false);
+    });
+  });
+
+  describe('createBrowserNavigateTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserNavigateTool();
+      expect(tool.name).toBe(EBrowserTools.NAVIGATE);
+    });
+
+    it('should return browser_action for navigation', async () => {
+      const tool = createBrowserNavigateTool();
+      const result = await tool.invoke({ 
+        url: 'https://example.com',
+        reason: 'going to example site' 
+      });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('navigate');
+      expect(parsed.action.url).toBe('https://example.com');
+      expect(parsed.action.reason).toBe('going to example site');
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+  });
+
+  describe('createBrowserScrollTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserScrollTool();
+      expect(tool.name).toBe(EBrowserTools.SCROLL);
+    });
+
+    it('should return browser_action for scrolling', async () => {
+      const tool = createBrowserScrollTool();
+      const result = await tool.invoke({ direction: 'down', amount: 800 });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('scroll');
+      expect(parsed.action.scroll.direction).toBe('down');
+      expect(parsed.action.scroll.amount).toBe(800);
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+
+    it('should default amount to 500', async () => {
+      const tool = createBrowserScrollTool();
+      const result = await tool.invoke({ direction: 'up' });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.action.scroll.amount).toBe(500);
+    });
+
+    it('should support all directions', async () => {
+      const tool = createBrowserScrollTool();
+      
+      for (const direction of ['up', 'down', 'left', 'right'] as const) {
+        const result = await tool.invoke({ direction });
+        const parsed = JSON.parse(result);
+        expect(parsed.action.scroll.direction).toBe(direction);
+      }
+    });
+  });
+
+  describe('createBrowserExtractTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserExtractTool();
+      expect(tool.name).toBe(EBrowserTools.EXTRACT);
+    });
+
+    it('should return browser_action for extraction with query', async () => {
+      const tool = createBrowserExtractTool();
+      const result = await tool.invoke({ query: 'price information' });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('extract');
+      expect(parsed.action.query).toBe('price information');
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+
+    it('should return browser_action for extraction with selector', async () => {
+      const tool = createBrowserExtractTool();
+      const result = await tool.invoke({ selector: '#main-content' });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.action.selector).toBe('#main-content');
+    });
+
+    it('should work with empty input', async () => {
+      const tool = createBrowserExtractTool();
+      const result = await tool.invoke({});
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('extract');
+    });
+  });
+
+  describe('createBrowserHoverTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserHoverTool();
+      expect(tool.name).toBe(EBrowserTools.HOVER);
+    });
+
+    it('should return browser_action for hovering', async () => {
+      const tool = createBrowserHoverTool();
+      const result = await tool.invoke({ index: 3 });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('hover');
+      expect(parsed.action.index).toBe(3);
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+  });
+
+  describe('createBrowserWaitTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserWaitTool();
+      expect(tool.name).toBe(EBrowserTools.WAIT);
+    });
+
+    it('should return browser_action for waiting', async () => {
+      const tool = createBrowserWaitTool();
+      const result = await tool.invoke({ 
+        duration: 2000, 
+        reason: 'waiting for page load' 
+      });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('wait');
+      expect(parsed.action.duration).toBe(2000);
+      expect(parsed.action.reason).toBe('waiting for page load');
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+
+    it('should default duration to 1000', async () => {
+      const tool = createBrowserWaitTool();
+      const result = await tool.invoke({});
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.action.duration).toBe(1000);
+    });
+  });
+
+  describe('createBrowserGoBackTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserGoBackTool();
+      expect(tool.name).toBe(EBrowserTools.BACK);
+    });
+
+    it('should return browser_action for going back', async () => {
+      const tool = createBrowserGoBackTool();
+      const result = await tool.invoke({ reason: 'returning to previous page' });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('back');
+      expect(parsed.action.reason).toBe('returning to previous page');
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+  });
+
+  describe('createBrowserScreenshotTool', () => {
+    it('should create a tool with correct name', () => {
+      const tool = createBrowserScreenshotTool();
+      expect(tool.name).toBe(EBrowserTools.SCREENSHOT);
+    });
+
+    it('should return browser_action for screenshot', async () => {
+      const tool = createBrowserScreenshotTool();
+      const result = await tool.invoke({ fullPage: true });
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('browser_action');
+      expect(parsed.action.type).toBe('screenshot');
+      expect(parsed.action.fullPage).toBe(true);
+      expect(parsed.requiresBrowserExecution).toBe(true);
+    });
+
+    it('should default fullPage to false', async () => {
+      const tool = createBrowserScreenshotTool();
+      const result = await tool.invoke({});
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.action.fullPage).toBe(false);
+    });
+  });
+
+  // ============================================
+  // createBrowserTools Tests
+  // ============================================
+  describe('createBrowserTools', () => {
+    it('should create all 9 tools by default', () => {
+      const tools = createBrowserTools();
+      expect(tools).toHaveLength(9);
+    });
+
+    it('should create tools with correct names', () => {
+      const tools = createBrowserTools();
+      const toolNames = tools.map(t => t.name);
+      
+      expect(toolNames).toContain(EBrowserTools.CLICK);
+      expect(toolNames).toContain(EBrowserTools.TYPE);
+      expect(toolNames).toContain(EBrowserTools.NAVIGATE);
+      expect(toolNames).toContain(EBrowserTools.SCROLL);
+      expect(toolNames).toContain(EBrowserTools.EXTRACT);
+      expect(toolNames).toContain(EBrowserTools.HOVER);
+      expect(toolNames).toContain(EBrowserTools.WAIT);
+      expect(toolNames).toContain(EBrowserTools.BACK);
+      expect(toolNames).toContain(EBrowserTools.SCREENSHOT);
+    });
+
+    it('should allow disabling specific tools', () => {
+      const config: BrowserToolsConfig = {
+        enableClick: false,
+        enableType: false,
+        enableNavigate: true,
+      };
+      const tools = createBrowserTools(config);
+      const toolNames = tools.map(t => t.name);
+      
+      expect(toolNames).not.toContain(EBrowserTools.CLICK);
+      expect(toolNames).not.toContain(EBrowserTools.TYPE);
+      expect(toolNames).toContain(EBrowserTools.NAVIGATE);
+    });
+
+    it('should create no tools when all disabled', () => {
+      const config: BrowserToolsConfig = {
+        enableClick: false,
+        enableType: false,
+        enableNavigate: false,
+        enableScroll: false,
+        enableExtract: false,
+        enableHover: false,
+        enableWait: false,
+        enableBack: false,
+        enableScreenshot: false,
+      };
+      const tools = createBrowserTools(config);
+      expect(tools).toHaveLength(0);
+    });
+
+    it('should create only specified tools', () => {
+      const config: BrowserToolsConfig = {
+        enableClick: true,
+        enableType: true,
+        enableNavigate: false,
+        enableScroll: false,
+        enableExtract: false,
+        enableHover: false,
+        enableWait: false,
+        enableBack: false,
+        enableScreenshot: false,
+      };
+      const tools = createBrowserTools(config);
+      expect(tools).toHaveLength(2);
+      
+      const toolNames = tools.map(t => t.name);
+      expect(toolNames).toContain(EBrowserTools.CLICK);
+      expect(toolNames).toContain(EBrowserTools.TYPE);
+    });
+  });
+
+  // ============================================
+  // Integration-like Tests
+  // ============================================
+  describe('tool response format consistency', () => {
+    it('all tools should return JSON with type and requiresBrowserExecution', async () => {
+      const tools = createBrowserTools();
+      
+      // Test each tool with minimal valid input
+      const testInputs = [
+        { tool: EBrowserTools.CLICK, input: { index: 0 } },
+        { tool: EBrowserTools.TYPE, input: { index: 0, text: 'test' } },
+        { tool: EBrowserTools.NAVIGATE, input: { url: 'https://test.com' } },
+        { tool: EBrowserTools.SCROLL, input: { direction: 'down' } },
+        { tool: EBrowserTools.EXTRACT, input: {} },
+        { tool: EBrowserTools.HOVER, input: { index: 0 } },
+        { tool: EBrowserTools.WAIT, input: {} },
+        { tool: EBrowserTools.BACK, input: {} },
+        { tool: EBrowserTools.SCREENSHOT, input: {} },
+      ];
+      
+      for (const { tool: toolName, input } of testInputs) {
+        const tool = tools.find(t => t.name === toolName);
+        expect(tool).toBeDefined();
+        
+        const result = await tool!.invoke(input);
+        const parsed = JSON.parse(result);
+        
+        expect(parsed.type).toBe('browser_action');
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBeDefined();
+        expect(parsed.action.type).toBeDefined();
+      }
+    });
+  });
+
+  describe('error handling', () => {
+    it('click tool should handle missing required params', async () => {
+      const tool = createBrowserClickTool();
+      const result = await tool.invoke({});
+      const parsed = JSON.parse(result);
+      
+      expect(parsed.type).toBe('error');
+    });
+  });
+});