@desplega.ai/qa-use 2.1.5 → 2.2.2

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'
+      );
+    });
+  });
+});

package/lib/api/browser.ts

@@ -0,0 +1,279 @@
+/**
+ * BrowserApiClient - Client for the desplega.ai Browser API (/browsers/v1/)
+ */
+
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import { getEnv } from '../env/index.js';
+import type {
+  BrowserSession,
+  BrowserAction,
+  ActionResult,
+  SnapshotResult,
+  UrlResult,
+  BlocksResult,
+  CreateBrowserSessionOptions,
+  BrowserSessionStatus,
+} from './browser-types.js';
+import type { ExtendedStep } from '../../src/types/test-definition.js';
+
+export class BrowserApiClient {
+  private readonly client: AxiosInstance;
+  private apiKey: string | null = null;
+
+  constructor(baseUrl?: string) {
+    // Use environment variable if available, otherwise use provided baseUrl, finally fall back to production
+    const apiUrl = getEnv('QA_USE_API_URL') || baseUrl || 'https://api.desplega.ai';
+
+    this.client = axios.create({
+      baseURL: `${apiUrl}/browsers/v1`,
+      timeout: 60000, // Longer timeout for browser operations
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    // Auto-load API key from environment or config file if available
+    const envApiKey = getEnv('QA_USE_API_KEY');
+    if (envApiKey) {
+      this.setApiKey(envApiKey);
+    }
+  }
+
+  setApiKey(apiKey: string): void {
+    this.apiKey = apiKey;
+    this.client.defaults.headers['Authorization'] = `Bearer ${apiKey}`;
+  }
+
+  getApiKey(): string | null {
+    return this.apiKey;
+  }
+
+  getBaseUrl(): string {
+    return this.client.defaults.baseURL || 'https://api.desplega.ai/browsers/v1';
+  }
+
+  // ==========================================
+  // Session Management
+  // ==========================================
+
+  /**
+   * Create a new browser session
+   */
+  async createSession(options: CreateBrowserSessionOptions = {}): Promise<BrowserSession> {
+    try {
+      const response = await this.client.post('/sessions', {
+        headless: options.headless ?? true,
+        viewport: options.viewport ?? 'desktop',
+        timeout: options.timeout ?? 300,
+        ...(options.ws_url && { ws_url: options.ws_url }),
+      });
+
+      return response.data as BrowserSession;
+    } catch (error) {
+      throw this.handleError(error, 'create session');
+    }
+  }
+
+  /**
+   * List all sessions for the organization
+   */
+  async listSessions(): Promise<BrowserSession[]> {
+    try {
+      const response = await this.client.get('/sessions');
+      // API may return { sessions: [...] } or just [...]
+      return Array.isArray(response.data) ? response.data : response.data.sessions || [];
+    } catch (error) {
+      throw this.handleError(error, 'list sessions');
+    }
+  }
+
+  /**
+   * Get a specific session by ID
+   */
+  async getSession(sessionId: string): Promise<BrowserSession> {
+    try {
+      const response = await this.client.get(`/sessions/${sessionId}`);
+      return response.data as BrowserSession;
+    } catch (error) {
+      throw this.handleError(error, 'get session');
+    }
+  }
+
+  /**
+   * Delete/close a session
+   */
+  async deleteSession(sessionId: string): Promise<void> {
+    try {
+      await this.client.delete(`/sessions/${sessionId}`);
+    } catch (error) {
+      throw this.handleError(error, 'delete session');
+    }
+  }
+
+  /**
+   * Wait for a session to reach a specific status
+   * @param sessionId - The session ID to wait for
+   * @param targetStatus - The status to wait for (default: 'active')
+   * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000)
+   * @param pollIntervalMs - Polling interval in milliseconds (default: 1000)
+   */
+  async waitForStatus(
+    sessionId: string,
+    targetStatus: BrowserSessionStatus = 'active',
+    timeoutMs: number = 30000,
+    pollIntervalMs: number = 1000
+  ): Promise<BrowserSession> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      const session = await this.getSession(sessionId);
+
+      if (session.status === targetStatus) {
+        return session;
+      }
+
+      // If session is closed or failed, throw error
+      if (session.status === 'closed') {
+        throw new Error(`Session ${sessionId} is closed`);
+      }
+
+      // Wait before polling again
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+
+    throw new Error(`Timeout waiting for session ${sessionId} to reach status "${targetStatus}"`);
+  }
+
+  // ==========================================
+  // Actions
+  // ==========================================
+
+  /**
+   * Execute a browser action
+   */
+  async executeAction(sessionId: string, action: BrowserAction): Promise<ActionResult> {
+    try {
+      const response = await this.client.post(`/sessions/${sessionId}/action`, action);
+      return response.data as ActionResult;
+    } catch (error) {
+      throw this.handleError(error, `execute action "${action.type}"`);
+    }
+  }
+
+  // ==========================================
+  // Inspection
+  // ==========================================
+
+  /**
+   * Get the ARIA accessibility tree snapshot
+   */
+  async getSnapshot(sessionId: string): Promise<SnapshotResult> {
+    try {
+      const response = await this.client.get(`/sessions/${sessionId}/snapshot`);
+      return response.data as SnapshotResult;
+    } catch (error) {
+      throw this.handleError(error, 'get snapshot');
+    }
+  }
+
+  /**
+   * Get a screenshot of the current page
+   * @returns Buffer containing PNG image data
+   */
+  async getScreenshot(sessionId: string): Promise<Buffer> {
+    try {
+      const response = await this.client.get(`/sessions/${sessionId}/screenshot`, {
+        responseType: 'arraybuffer',
+      });
+      return Buffer.from(response.data);
+    } catch (error) {
+      throw this.handleError(error, 'get screenshot');
+    }
+  }
+
+  /**
+   * Get the current page URL
+   */
+  async getUrl(sessionId: string): Promise<string> {
+    try {
+      const response = await this.client.get(`/sessions/${sessionId}/url`);
+      const result = response.data as UrlResult;
+      return result.url;
+    } catch (error) {
+      throw this.handleError(error, 'get URL');
+    }
+  }
+
+  /**
+   * Get recorded blocks (test steps) from the session
+   * @returns Array of ExtendedStep objects
+   */
+  async getBlocks(sessionId: string): Promise<ExtendedStep[]> {
+    try {
+      const response = await this.client.get(`/sessions/${sessionId}/blocks`);
+      const result = response.data as BlocksResult;
+      return (result.blocks || []) as ExtendedStep[];
+    } catch (error) {
+      throw this.handleError(error, 'get blocks');
+    }
+  }
+
+  // ==========================================
+  // WebSocket Streaming
+  // ==========================================
+
+  /**
+   * Get the WebSocket URL for streaming events
+   */
+  getStreamUrl(sessionId: string): string {
+    // Convert HTTP URL to WebSocket URL
+    const baseUrl = this.getBaseUrl();
+    const wsUrl = baseUrl.replace(/^http/, 'ws');
+    return `${wsUrl}/sessions/${sessionId}/stream`;
+  }
+
+  // ==========================================
+  // Error Handling
+  // ==========================================
+
+  private handleError(error: unknown, operation: string): Error {
+    if (axios.isAxiosError(error)) {
+      const statusCode = error.response?.status;
+      const errorData = error.response?.data as { message?: string; detail?: string } | undefined;
+
+      if (statusCode === 404) {
+        return new Error(`Session not found`);
+      }
+
+      if (statusCode === 401) {
+        return new Error(`Unauthorized. Please check your API key.`);
+      }
+
+      if (statusCode === 403) {
+        return new Error(`Forbidden. You don't have permission for this operation.`);
+      }
+
+      const message =
+        errorData?.message || errorData?.detail || `HTTP ${statusCode}: Failed to ${operation}`;
+      return new Error(message);
+    }
+
+    if (error instanceof Error) {
+      return error;
+    }
+
+    return new Error(`Unknown error during ${operation}`);
+  }
+}
+
+// Re-export types for convenience
+export type {
+  BrowserSession,
+  BrowserAction,
+  ActionResult,
+  SnapshotResult,
+  UrlResult,
+  CreateBrowserSessionOptions,
+  BrowserSessionStatus,
+} from './browser-types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/qa-use",
-  "version": "2.1.5",
+  "version": "2.2.2",
   "packageManager": "bun@^1.3.4",
   "description": "QA automation tool for browser testing with MCP server support",
   "type": "module",
@@ -95,6 +95,7 @@
     "express": "^4.21.2",
     "glob": "^13.0.0",
     "playwright": "1.55.0",
+    "ws": "^8.19.0",
     "yaml": "^2.8.2"
   }
 }