@desplega.ai/qa-use 2.2.4 → 2.3.0

package/dist/src/cli/lib/loader.js

@@ -53,6 +53,28 @@ export function resolveTestPath(testNameOrPath, directory) {
     }
     throw new Error(`Test file not found: ${testNameOrPath}`);
 }
+/**
+ * Find a local test file by its ID
+ *
+ * @param testId - The UUID to search for
+ * @param directory - Test directory root
+ * @returns File path if found, null otherwise
+ */
+export async function findLocalTestById(testId, directory) {
+    const files = await discoverTests(directory);
+    for (const file of files) {
+        try {
+            const def = await loadTestDefinition(file);
+            if (def.id === testId) {
+                return file;
+            }
+        }
+        catch {
+            // Skip files that fail to load
+        }
+    }
+    return null;
+}
 /**
  * Load a test and all its dependencies recursively
  *
@@ -63,22 +85,31 @@ export function resolveTestPath(testNameOrPath, directory) {
 export async function loadTestWithDeps(testName, directory) {
     const definitions = [];
     const loaded = new Set();
-    async function loadRecursive(name) {
+    async function loadRecursive(nameOrPath, isFullPath = false) {
         // Avoid circular dependencies
-        if (loaded.has(name))
+        if (loaded.has(nameOrPath))
             return;
-        loaded.add(name);
-        const filePath = resolveTestPath(name, directory);
+        loaded.add(nameOrPath);
+        // If isFullPath is true (from findLocalTestById), use directly; otherwise resolve
+        const filePath = isFullPath ? nameOrPath : resolveTestPath(nameOrPath, directory);
         const def = await loadTestDefinition(filePath);
-        // Load dependency first (if it exists and is a local file)
+        // Load dependency first (if it exists)
         if (def.depends_on) {
             // Check if depends_on is a UUID (cloud test) or a file name
             const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(def.depends_on);
-            if (!isUuid) {
+            if (isUuid) {
+                // Try to find local file with this ID first
+                const localFile = await findLocalTestById(def.depends_on, directory);
+                if (localFile) {
+                    // Load from local file (localFile is already a full path from discoverTests)
+                    await loadRecursive(localFile, true);
+                }
+                // If not found locally, API will resolve at runtime
+            }
+            else {
                 // It's a local file reference
                 await loadRecursive(def.depends_on);
             }
-            // If it's a UUID, the API will resolve it
         }
         definitions.push(def);
     }

package/dist/src/cli/lib/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../../src/cli/lib/loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../../src/cli/lib/loader.ts"],"names":[],"mappings":"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"}

package/lib/api/browser-types.ts

@@ -6,7 +6,7 @@
 // Session Types
 // ==========================================
 
-export type BrowserSessionStatus = 'starting' | 'active' | 'closing' | 'closed';
+export type BrowserSessionStatus = 'starting' | 'active' | 'closing' | 'closed' | 'failed';
 
 export type ViewportType = 'desktop' | 'mobile' | 'tablet';
 
@@ -16,6 +16,8 @@ export interface CreateBrowserSessionOptions {
   timeout?: number; // Session timeout in seconds (60-3600)
   ws_url?: string; // WebSocket URL for remote/tunneled browser
   record_blocks?: boolean; // Enable block recording for test generation
+  after_test_id?: string; // Run a test before session becomes interactive
+  vars?: Record<string, string>; // Variable overrides for after_test_id test
 }
 
 export interface BrowserSession {
@@ -167,6 +169,17 @@ export interface WaitForLoadAction {
 
 export interface SnapshotAction {
   type: 'snapshot';
+  interactive?: boolean;
+  compact?: boolean;
+  max_depth?: number;
+  scope?: string;
+}
+
+export interface SnapshotOptions {
+  interactive?: boolean; // Only include interactive elements
+  compact?: boolean; // Remove empty structural elements
+  max_depth?: number; // Limit tree depth (1-20)
+  scope?: string; // CSS selector to scope snapshot
 }
 
 export interface ScreenshotAction {
@@ -209,9 +222,16 @@ export interface ActionResult {
   url_after?: string; // URL after action executed
 }
 
+export interface SnapshotFilterStats {
+  original_lines: number;
+  filtered_lines: number;
+  reduction_percent: number;
+}
+
 export interface SnapshotResult {
   snapshot: string;
   url?: string;
+  filter_stats?: SnapshotFilterStats;
 }
 
 export interface UrlResult {

package/lib/api/browser.test.ts

@@ -286,6 +286,56 @@ describe('BrowserApiClient', () => {
       expect(snapshot.snapshot).toContain('Example');
       expect(snapshot.url).toBe('https://example.com');
     });
+
+    it('should get ARIA snapshot with filtering options', async () => {
+      const mockSnapshot = {
+        snapshot: '- button "Submit" [ref=e1]',
+        url: 'https://example.com',
+        filter_stats: {
+          original_lines: 450,
+          filtered_lines: 42,
+          reduction_percent: 91,
+        },
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockSnapshot });
+
+      const snapshot = await client.getSnapshot('session-123', {
+        interactive: true,
+        compact: true,
+        max_depth: 3,
+      });
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith(
+        '/sessions/session-123/snapshot?interactive=true&compact=true&max_depth=3'
+      );
+      expect(snapshot.filter_stats?.reduction_percent).toBe(91);
+    });
+
+    it('should get ARIA snapshot with scope option', async () => {
+      const mockSnapshot = {
+        snapshot: '- heading "Main Content" [ref=e1]',
+        url: 'https://example.com',
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockSnapshot });
+
+      await client.getSnapshot('session-123', { scope: '#main' });
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith(
+        '/sessions/session-123/snapshot?scope=%23main'
+      );
+    });
+
+    it('should get ARIA snapshot without options (backward compatible)', async () => {
+      const mockSnapshot = {
+        snapshot: '- heading "Example" [ref=e1]',
+        url: 'https://example.com',
+      };
+      mockAxiosInstance.get.mockResolvedValueOnce({ data: mockSnapshot });
+
+      await client.getSnapshot('session-123');
+
+      expect(mockAxiosInstance.get).toHaveBeenCalledWith('/sessions/session-123/snapshot');
+    });
   });
 
   describe('getScreenshot', () => {

package/lib/api/browser.ts

@@ -10,6 +10,7 @@ import type {
   BrowserAction,
   ActionResult,
   SnapshotResult,
+  SnapshotOptions,
   UrlResult,
   BlocksResult,
   CreateBrowserSessionOptions,
@@ -74,6 +75,8 @@ export class BrowserApiClient {
         timeout: options.timeout ?? 300,
         ...(options.ws_url && { ws_url: options.ws_url }),
         ...(options.record_blocks !== undefined && { record_blocks: options.record_blocks }),
+        ...(options.after_test_id && { after_test_id: options.after_test_id }),
+        ...(options.vars && Object.keys(options.vars).length > 0 && { vars: options.vars }),
       });
 
       return response.data as BrowserSession;
@@ -140,11 +143,16 @@ export class BrowserApiClient {
         return session;
       }
 
-      // If session is closed or failed, throw error
+      // If session is closed, throw error
       if (session.status === 'closed') {
         throw new Error(`Session ${sessionId} is closed`);
       }
 
+      // If session failed (e.g., after_test_id test failed), return session for error handling
+      if (session.status === 'failed') {
+        return session;
+      }
+
       // Wait before polling again
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     }
@@ -174,10 +182,21 @@ export class BrowserApiClient {
 
   /**
    * Get the ARIA accessibility tree snapshot
+   * @param sessionId - The session ID
+   * @param options - Filtering options (interactive, compact, max_depth, scope)
    */
-  async getSnapshot(sessionId: string): Promise<SnapshotResult> {
+  async getSnapshot(sessionId: string, options: SnapshotOptions = {}): Promise<SnapshotResult> {
     try {
-      const response = await this.client.get(`/sessions/${sessionId}/snapshot`);
+      const params = new URLSearchParams();
+      if (options.interactive) params.append('interactive', 'true');
+      if (options.compact) params.append('compact', 'true');
+      if (options.max_depth !== undefined) params.append('max_depth', options.max_depth.toString());
+      if (options.scope) params.append('scope', options.scope);
+
+      const queryString = params.toString();
+      const url = `/sessions/${sessionId}/snapshot${queryString ? `?${queryString}` : ''}`;
+
+      const response = await this.client.get(url);
       return response.data as SnapshotResult;
     } catch (error) {
       throw this.handleError(error, 'get snapshot');
@@ -354,6 +373,8 @@ export type {
   BrowserAction,
   ActionResult,
   SnapshotResult,
+  SnapshotOptions,
+  SnapshotFilterStats,
   UrlResult,
   CreateBrowserSessionOptions,
   BrowserSessionStatus,

package/lib/api/index.ts

@@ -236,6 +236,7 @@ export interface RunCliTestOptions {
   store_recording?: boolean;
   store_har?: boolean;
   ws_url?: string;
+  vars?: Record<string, string>; // Variable overrides for cloud test (test_id)
 }
 
 export type SSECallback = (event: SSEEvent) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/qa-use",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "packageManager": "bun@^1.3.4",
   "description": "QA automation tool for browser testing with MCP server support",
   "type": "module",