@desplega.ai/qa-use 2.1.7 → 2.2.2

package/lib/api/browser-types.ts

@@ -0,0 +1,278 @@
+/**
+ * Type definitions for the Browser API (/browsers/v1/)
+ */
+
+// ==========================================
+// Session Types
+// ==========================================
+
+export type BrowserSessionStatus = 'starting' | 'active' | 'closing' | 'closed';
+
+export type ViewportType = 'desktop' | 'mobile' | 'tablet';
+
+export interface CreateBrowserSessionOptions {
+  headless?: boolean;
+  viewport?: ViewportType;
+  timeout?: number; // Session timeout in seconds (60-3600)
+  ws_url?: string; // WebSocket URL for remote/tunneled browser
+}
+
+export interface BrowserSession {
+  id: string;
+  status: BrowserSessionStatus;
+  created_at: string;
+  updated_at?: string;
+  current_url?: string;
+  viewport?: ViewportType;
+  headless?: boolean;
+  timeout?: number;
+}
+
+// ==========================================
+// Action Types
+// ==========================================
+
+export type BrowserActionType =
+  | 'goto'
+  | 'back'
+  | 'forward'
+  | 'reload'
+  | 'click'
+  | 'fill'
+  | 'type'
+  | 'press'
+  | 'hover'
+  | 'scroll'
+  | 'scroll_into_view'
+  | 'select'
+  | 'check'
+  | 'uncheck'
+  | 'wait'
+  | 'wait_for_selector'
+  | 'wait_for_load'
+  | 'snapshot'
+  | 'screenshot';
+
+export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+
+export interface GotoAction {
+  type: 'goto';
+  url: string;
+}
+
+export interface BackAction {
+  type: 'back';
+}
+
+export interface ForwardAction {
+  type: 'forward';
+}
+
+export interface ReloadAction {
+  type: 'reload';
+}
+
+export interface ClickAction {
+  type: 'click';
+  ref?: string;
+  text?: string; // AI-based semantic element selection (alternative to ref)
+}
+
+export interface FillAction {
+  type: 'fill';
+  ref?: string;
+  text?: string; // AI-based semantic element selection (alternative to ref)
+  value: string;
+}
+
+export interface TypeAction {
+  type: 'type';
+  ref: string;
+  text: string;
+}
+
+export interface PressAction {
+  type: 'press';
+  key: string;
+}
+
+export interface HoverAction {
+  type: 'hover';
+  ref?: string;
+  text?: string; // AI-based semantic element selection (alternative to ref)
+}
+
+export interface ScrollAction {
+  type: 'scroll';
+  direction: ScrollDirection;
+  amount?: number; // pixels, default 500
+}
+
+export interface SelectAction {
+  type: 'select';
+  ref?: string;
+  text?: string; // AI-based semantic element selection (alternative to ref)
+  value: string;
+}
+
+export interface CheckAction {
+  type: 'check';
+  ref?: string;
+  text?: string; // AI-based semantic element selection (alternative to ref)
+}
+
+export interface UncheckAction {
+  type: 'uncheck';
+  ref?: string;
+  text?: string; // AI-based semantic element selection (alternative to ref)
+}
+
+export interface ScrollIntoViewAction {
+  type: 'scroll_into_view';
+  ref?: string;
+  text?: string; // AI-based semantic element selection (alternative to ref)
+}
+
+export interface WaitAction {
+  type: 'wait';
+  duration_ms: number;
+}
+
+export interface WaitForSelectorAction {
+  type: 'wait_for_selector';
+  selector: string;
+  state?: 'visible' | 'hidden' | 'attached' | 'detached';
+}
+
+export interface WaitForLoadAction {
+  type: 'wait_for_load';
+  state?: 'load' | 'domcontentloaded' | 'networkidle';
+}
+
+export interface SnapshotAction {
+  type: 'snapshot';
+}
+
+export interface ScreenshotAction {
+  type: 'screenshot';
+}
+
+export type BrowserAction =
+  | GotoAction
+  | BackAction
+  | ForwardAction
+  | ReloadAction
+  | ClickAction
+  | FillAction
+  | TypeAction
+  | PressAction
+  | HoverAction
+  | ScrollAction
+  | ScrollIntoViewAction
+  | SelectAction
+  | CheckAction
+  | UncheckAction
+  | WaitAction
+  | WaitForSelectorAction
+  | WaitForLoadAction
+  | SnapshotAction
+  | ScreenshotAction;
+
+// ==========================================
+// API Response Types
+// ==========================================
+
+export interface ActionResult {
+  success: boolean;
+  error?: string;
+  data?: unknown;
+}
+
+export interface SnapshotResult {
+  snapshot: string;
+  url?: string;
+}
+
+export interface UrlResult {
+  url: string;
+}
+
+export interface BlocksResult {
+  blocks: unknown[]; // ExtendedStep[] - typed in BrowserApiClient
+}
+
+// ==========================================
+// WebSocket Event Types
+// ==========================================
+
+export type WebSocketEventType =
+  | 'action_started'
+  | 'action_completed'
+  | 'status_changed'
+  | 'error'
+  | 'closed';
+
+export interface WebSocketEvent {
+  type: WebSocketEventType;
+  data?: unknown;
+  timestamp?: string;
+}
+
+export interface ActionStartedEvent extends WebSocketEvent {
+  type: 'action_started';
+  data: {
+    action_type: BrowserActionType;
+    action_id?: string;
+  };
+}
+
+export interface ActionCompletedEvent extends WebSocketEvent {
+  type: 'action_completed';
+  data: {
+    action_id?: string;
+    success: boolean;
+    error?: string;
+    result?: unknown;
+  };
+}
+
+export interface StatusChangedEvent extends WebSocketEvent {
+  type: 'status_changed';
+  data: {
+    status: BrowserSessionStatus;
+  };
+}
+
+export interface ErrorEvent extends WebSocketEvent {
+  type: 'error';
+  data: {
+    message: string;
+    code?: string;
+  };
+}
+
+export interface ClosedEvent extends WebSocketEvent {
+  type: 'closed';
+  data?: {
+    reason?: string;
+  };
+}
+
+// ==========================================
+// Client Messages (WebSocket)
+// ==========================================
+
+export interface PingMessage {
+  type: 'ping';
+}
+
+export interface ActionMessage {
+  type: 'action';
+  data: BrowserAction;
+}
+
+export interface GetStatusMessage {
+  type: 'get_status';
+}
+
+export type ClientMessage = PingMessage | ActionMessage | GetStatusMessage;

package/lib/api/browser.test.ts

@@ -0,0 +1,378 @@
+/**
+ * BrowserApiClient Unit Tests
+ */
+
+import { describe, it, expect, beforeEach, mock, spyOn } from 'bun:test';
+import axios from 'axios';
+import { BrowserApiClient } from './browser.js';
+
+// Mock axios
+const mockAxiosInstance = {
+  get: mock(() => Promise.resolve({ data: {} })),
+  post: mock(() => Promise.resolve({ data: {} })),
+  delete: mock(() => Promise.resolve({ data: {} })),
+  defaults: {
+    baseURL: 'https://api.desplega.ai/browsers/v1',
+    headers: {},
+  },
+};
+
+mock.module('axios', () => ({
+  default: {
+    create: () => mockAxiosInstance,
+    isAxiosError: (err: unknown) =>
+      typeof err === 'object' && err !== null && 'response' in err && 'isAxiosError' in err,
+  },
+}));
+
+describe('BrowserApiClient', () => {
+  let client: BrowserApiClient;
+
+  beforeEach(() => {
+    // Reset mocks
+    mockAxiosInstance.get.mockReset();
+    mockAxiosInstance.post.mockReset();
+    mockAxiosInstance.delete.mockReset();
+
+    // Clear environment variables
+    delete process.env.QA_USE_API_KEY;
+    delete process.env.QA_USE_API_URL;
+
+    client = new BrowserApiClient();
+  });
+
+  describe('constructor', () => {
+    it('should use default API URL', () => {
+      const c = new BrowserApiClient();
+      expect(c.getBaseUrl()).toContain('api.desplega.ai');
+    });
+
+    it('should use custom API URL', () => {
+      const c = new BrowserApiClient('https://custom.api.com');
+      // The URL should be set via axios.create
+      expect(mockAxiosInstance.defaults.baseURL).toBeDefined();
+    });
+  });
+
+  describe('setApiKey', () => {
+    it('should set API key', () => {
+      client.setApiKey('test-key-123');
+      expect(client.getApiKey()).toBe('test-key-123');
+    });
+  });
+
+  describe('createSession', () => {
+    it('should create session with default options', async () => {
+      const mockSession = {
+        id: 'session-123',
+        status: 'starting',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockSession });
+
+      const session = await client.createSession();
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/sessions', {
+        headless: true,
+        viewport: 'desktop',
+        timeout: 300,
+      });
+      expect(session.id).toBe('session-123');
+      expect(session.status).toBe('starting');
+    });
+
+    it('should create session with custom options', async () => {
+      const mockSession = {
+        id: 'session-456',
+        status: 'starting',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockSession });
+
+      const session = await client.createSession({
+        headless: false,
+        viewport: 'mobile',
+        timeout: 600,
+      });
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/sessions', {
+        headless: false,
+        viewport: 'mobile',
+        timeout: 600,
+      });
+      expect(session.id).toBe('session-456');
+    });
+
+    it('should create session with ws_url for remote browser', async () => {
+      const mockSession = {
+        id: 'session-789',
+        status: 'starting',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockSession });
+
+      const session = await client.createSession({
+        headless: true,
+        viewport: 'desktop',
+        timeout: 300,
+        ws_url: 'wss://tunnel.example.com/devtools/browser/abc123',
+      });
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/sessions', {
+        headless: true,
+        viewport: 'desktop',
+        timeout: 300,
+        ws_url: 'wss://tunnel.example.com/devtools/browser/abc123',
+      });
+      expect(session.id).toBe('session-789');
+    });
+
+    it('should not include ws_url when not provided', async () => {
+      const mockSession = {
+        id: 'session-abc',
+        status: 'starting',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockSession });
+
+      await client.createSession({
+        headless: true,
+        viewport: 'desktop',
+      });
+
+      const callArgs = mockAxiosInstance.post.mock.calls[0];
+      expect(callArgs[1]).not.toHaveProperty('ws_url');
+    });
+  });
+
+  describe('listSessions', () => {
+    it('should list sessions from array response', async () => {
+      const mockSessions = [
+        { id: 'session-1', status: 'active' },
+        { id: 'session-2', status: 'starting' },
+      ];
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockSessions });
+
+      const sessions = await client.listSessions();
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/sessions');
+      expect(sessions).toHaveLength(2);
+      expect(sessions[0].id).toBe('session-1');
+    });
+
+    it('should list sessions from object response', async () => {
+      const mockResponse = {
+        sessions: [
+          { id: 'session-1', status: 'active' },
+          { id: 'session-2', status: 'starting' },
+        ],
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockResponse });
+
+      const sessions = await client.listSessions();
+
+      expect(sessions).toHaveLength(2);
+    });
+  });
+
+  describe('getSession', () => {
+    it('should get session by ID', async () => {
+      const mockSession = {
+        id: 'session-123',
+        status: 'active',
+        url: 'https://example.com',
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockSession });
+
+      const session = await client.getSession('session-123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/sessions/session-123');
+      expect(session.id).toBe('session-123');
+      expect(session.status).toBe('active');
+    });
+  });
+
+  describe('deleteSession', () => {
+    it('should delete session by ID', async () => {
+      mockAxiosInstance.delete.mockResolvedValueOnce({ data: {} });
+
+      await client.deleteSession('session-123');
+
+      expect(mockAxiosInstance.delete).toHaveBeenCalledWith('/sessions/session-123');
+    });
+  });
+
+  describe('executeAction', () => {
+    it('should execute goto action', async () => {
+      const mockResult = { success: true };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockResult });
+
+      const result = await client.executeAction('session-123', {
+        type: 'goto',
+        url: 'https://example.com',
+      });
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/sessions/session-123/action', {
+        type: 'goto',
+        url: 'https://example.com',
+      });
+      expect(result.success).toBe(true);
+    });
+
+    it('should execute click action', async () => {
+      const mockResult = { success: true };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockResult });
+
+      const result = await client.executeAction('session-123', {
+        type: 'click',
+        ref: 'e3',
+      });
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/sessions/session-123/action', {
+        type: 'click',
+        ref: 'e3',
+      });
+      expect(result.success).toBe(true);
+    });
+
+    it('should execute fill action', async () => {
+      const mockResult = { success: true };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockResult });
+
+      const result = await client.executeAction('session-123', {
+        type: 'fill',
+        ref: 'e4',
+        value: 'test@example.com',
+      });
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/sessions/session-123/action', {
+        type: 'fill',
+        ref: 'e4',
+        value: 'test@example.com',
+      });
+      expect(result.success).toBe(true);
+    });
+
+    it('should execute scroll action', async () => {
+      const mockResult = { success: true };
+      mockAxiosInstance.post.mockResolvedValueOnce({ data: mockResult });
+
+      const result = await client.executeAction('session-123', {
+        type: 'scroll',
+        direction: 'down',
+        amount: 500,
+      });
+
+      expect(mockAxiosInstance.post).toHaveBeenCalledWith('/sessions/session-123/action', {
+        type: 'scroll',
+        direction: 'down',
+        amount: 500,
+      });
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('getSnapshot', () => {
+    it('should get ARIA snapshot', async () => {
+      const mockSnapshot = {
+        snapshot: '- heading "Example" [ref=e1]',
+        url: 'https://example.com',
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockSnapshot });
+
+      const snapshot = await client.getSnapshot('session-123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/sessions/session-123/snapshot');
+      expect(snapshot.snapshot).toContain('Example');
+      expect(snapshot.url).toBe('https://example.com');
+    });
+  });
+
+  describe('getScreenshot', () => {
+    it('should get screenshot as buffer', async () => {
+      const mockData = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG header
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockData });
+
+      const buffer = await client.getScreenshot('session-123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/sessions/session-123/screenshot', {
+        responseType: 'arraybuffer',
+      });
+      expect(Buffer.isBuffer(buffer)).toBe(true);
+    });
+  });
+
+  describe('getUrl', () => {
+    it('should get current URL', async () => {
+      const mockResult = { url: 'https://example.com/page' };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockResult });
+
+      const url = await client.getUrl('session-123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/sessions/session-123/url');
+      expect(url).toBe('https://example.com/page');
+    });
+  });
+
+  describe('getStreamUrl', () => {
+    it('should return WebSocket URL', () => {
+      const url = client.getStreamUrl('session-123');
+
+      expect(url).toContain('ws');
+      expect(url).toContain('session-123');
+      expect(url).toContain('/stream');
+    });
+  });
+
+  describe('waitForStatus', () => {
+    it('should return immediately if session is already active', async () => {
+      const mockSession = {
+        id: 'session-123',
+        status: 'active',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockSession });
+
+      const session = await client.waitForStatus('session-123', 'active', 5000, 100);
+
+      expect(session.status).toBe('active');
+      expect(mockAxiosInstance.get).toHaveBeenCalledTimes(1);
+    });
+
+    it('should poll until session becomes active', async () => {
+      const startingSession = {
+        id: 'session-123',
+        status: 'starting',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+      const activeSession = {
+        id: 'session-123',
+        status: 'active',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+
+      mockAxiosInstance.get
+        .mockResolvedValueOnce({ data: startingSession })
+        .mockResolvedValueOnce({ data: startingSession })
+        .mockResolvedValueOnce({ data: activeSession });
+
+      const session = await client.waitForStatus('session-123', 'active', 5000, 50);
+
+      expect(session.status).toBe('active');
+      expect(mockAxiosInstance.get).toHaveBeenCalledTimes(3);
+    });
+
+    it('should throw error if session is closed', async () => {
+      const closedSession = {
+        id: 'session-123',
+        status: 'closed',
+        created_at: '2026-01-23T10:00:00Z',
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: closedSession });
+
+      await expect(client.waitForStatus('session-123', 'active', 5000, 100)).rejects.toThrow(
+        'closed'
+      );
+    });
+  });
+});