testdriverai 7.0.0 → 7.1.1

package/agent/lib/redraw.js

@@ -3,13 +3,28 @@ const fs = require("fs");
 const { events } = require("../events");
 const theme = require("./theme");
 
+// Default redraw options
+const DEFAULT_REDRAW_OPTIONS = {
+  enabled: true,           // Master switch to enable/disable redraw detection
+  screenRedraw: true,      // Enable screen redraw detection
+  networkMonitor: true,    // Enable network activity monitoring
+  diffThreshold: 0.01,     // Percentage threshold for screen diff (0.01 = 0.01%)
+};
+
 // Factory function that creates redraw functionality with the provided system instance
 const createRedraw = (
   emitter,
   system,
   sandbox,
-  redrawThresholdPercent = 0.1,
+  defaultOptions = {},
 ) => {
+  // Merge default options with provided defaults
+  const baseOptions = { ...DEFAULT_REDRAW_OPTIONS, ...defaultOptions };
+  // Support legacy redrawThresholdPercent number argument
+  if (typeof defaultOptions === 'number') {
+    baseOptions.diffThreshold = defaultOptions;
+  }
+  
   const networkUpdateInterval = 15000;
 
   let lastTxBytes = null;
@@ -116,16 +131,13 @@ const createRedraw = (
         { threshold: 0.1 },
       );
 
-      if (differentPixels === 0) {
-        return false;
-      } else {
-        // Calculate percentage difference based on pixel differences
-        const diffPercentage = (differentPixels / totalPixels) * 100;
-        return diffPercentage.toFixed(1);
-      }
+      // Calculate percentage difference based on pixel differences
+      // Always return a number (0 if no difference)
+      const diffPercentage = (differentPixels / totalPixels) * 100;
+      return parseFloat(diffPercentage.toFixed(2));
     } catch (error) {
       console.error("Error comparing images:", error);
-      return false;
+      return 0; // Return 0 on error instead of false
     }
   }
 
@@ -146,46 +158,104 @@ const createRedraw = (
     }
   }
 
-  async function start() {
+  // Current options for the active redraw cycle
+  let currentOptions = { ...baseOptions };
+
+  async function start(options = {}) {
+    // Merge base options with per-call options
+    currentOptions = { ...baseOptions, ...options };
+    
+    console.log('[redraw] start() called with options:', JSON.stringify(currentOptions));
+    
+    // If redraw is completely disabled, return early
+    if (!currentOptions.enabled) {
+      console.log('[redraw] start() - redraw disabled, returning null');
+      return null;
+    }
+    
+    // If both screenRedraw and networkMonitor are disabled, disable redraw
+    if (!currentOptions.screenRedraw && !currentOptions.networkMonitor) {
+      currentOptions.enabled = false;
+      console.log('[redraw] start() - both screenRedraw and networkMonitor disabled, returning null');
+      return null;
+    }
+    
     resetState();
-    startNetworkMonitoring();
-    startImage = await system.captureScreenPNG(0.25, true);
+    
+    // Only start network monitoring if enabled
+    if (currentOptions.networkMonitor) {
+      startNetworkMonitoring();
+    }
+    
+    // Only capture start image if screen redraw is enabled
+    if (currentOptions.screenRedraw) {
+      startImage = await system.captureScreenPNG(0.25, true);
+      console.log('[redraw] start() - captured startImage:', startImage);
+    }
+    
     return startImage;
   }
 
-  async function checkCondition(resolve, startTime, timeoutMs) {
-    let nowImage = await system.captureScreenPNG(0.25, true);
+  async function checkCondition(resolve, startTime, timeoutMs, options) {
+    const { enabled, screenRedraw, networkMonitor, diffThreshold } = options;
+    
+    // If redraw is disabled, resolve immediately
+    if (!enabled) {
+      resolve("true");
+      return;
+    }
+    
+    let nowImage = screenRedraw ? await system.captureScreenPNG(0.25, true) : null;
     let timeElapsed = Date.now() - startTime;
     let diffPercent = 0;
     let isTimeout = timeElapsed > timeoutMs;
 
-    if (!screenHasRedrawn) {
+    // Check screen redraw if enabled and we have a start image to compare against
+    if (screenRedraw && !screenHasRedrawn && startImage && nowImage) {
+      console.log('[redraw] checkCondition() - comparing images:', { startImage, nowImage });
       diffPercent = await imageDiffPercent(startImage, nowImage);
-      screenHasRedrawn = diffPercent > redrawThresholdPercent;
+      console.log('[redraw] checkCondition() - diffPercent:', diffPercent, 'threshold:', diffThreshold);
+      screenHasRedrawn = diffPercent > diffThreshold;
+      console.log('[redraw] checkCondition() - screenHasRedrawn:', screenHasRedrawn);
+    } else if (screenRedraw && !startImage) {
+      // If no start image was captured, capture one now and wait for next check
+      console.log('[redraw] checkCondition() - no startImage, capturing now');
+      startImage = await system.captureScreenPNG(0.25, true);
     }
-
-    // // log redraw as output
-    let redrawText = screenHasRedrawn
-      ? theme.green(`y`)
-      : theme.dim(`${diffPercent}/${redrawThresholdPercent}%`);
-    let networkText = networkSettled
-      ? theme.green(`y`)
-      : theme.dim(
-          `${Math.trunc((diffRxBytes + diffTxBytes) / networkUpdateInterval)}b/s`,
-        );
+    
+    // If screen redraw is disabled, consider it as "redrawn"
+    const effectiveScreenRedrawn = screenRedraw ? screenHasRedrawn : true;
+    // If network monitor is disabled, consider it as "settled"
+    const effectiveNetworkSettled = networkMonitor ? networkSettled : true;
+
+    // Log redraw status
+    let redrawText = !screenRedraw
+      ? theme.dim(`disabled`)
+      : effectiveScreenRedrawn
+        ? theme.green(`y`)
+        : theme.dim(`${diffPercent}/${diffThreshold}%`);
+    let networkText = !networkMonitor
+      ? theme.dim(`disabled`)
+      : effectiveNetworkSettled
+        ? theme.green(`y`)
+        : theme.dim(
+            `${Math.trunc((diffRxBytes + diffTxBytes) / networkUpdateInterval)}b/s`,
+          );
     let timeoutText = isTimeout
       ? theme.green(`y`)
       : theme.dim(`${Math.floor(timeElapsed / 1000)}/${timeoutMs / 1000}s`);
 
     emitter.emit(events.redraw.status, {
       redraw: {
-        hasRedrawn: screenHasRedrawn,
+        enabled: screenRedraw,
+        hasRedrawn: effectiveScreenRedrawn,
         diffPercent,
-        threshold: redrawThresholdPercent,
+        threshold: diffThreshold,
         text: redrawText,
       },
       network: {
-        settled: networkSettled,
+        enabled: networkMonitor,
+        settled: effectiveNetworkSettled,
         rxBytes: diffRxBytes,
         txBytes: diffTxBytes,
         text: networkText,
@@ -198,27 +268,42 @@ const createRedraw = (
       },
     });
 
-    if ((screenHasRedrawn && networkSettled) || isTimeout) {
+    if ((effectiveScreenRedrawn && effectiveNetworkSettled) || isTimeout) {
       emitter.emit(events.redraw.complete, {
-        screenHasRedrawn,
-        networkSettled,
+        screenHasRedrawn: effectiveScreenRedrawn,
+        networkSettled: effectiveNetworkSettled,
         isTimeout,
         timeElapsed,
       });
       resolve("true");
     } else {
       setTimeout(() => {
-        checkCondition(resolve, startTime, timeoutMs);
+        checkCondition(resolve, startTime, timeoutMs, options);
       }, 500);
     }
   }
 
-  function wait(timeoutMs) {
+  function wait(timeoutMs, options = {}) {
+    // Merge current options with any per-call overrides
+    const waitOptions = { ...currentOptions, ...options };
+    
+    // If redraw is disabled, resolve immediately
+    if (!waitOptions.enabled) {
+      return Promise.resolve("true");
+    }
+    
+    // If both are disabled, resolve immediately
+    if (!waitOptions.screenRedraw && !waitOptions.networkMonitor) {
+      return Promise.resolve("true");
+    }
+    
     return new Promise((resolve) => {
       const startTime = Date.now();
-      // Start network monitoring if not already started
-      startNetworkMonitoring();
-      checkCondition(resolve, startTime, timeoutMs);
+      // Start network monitoring if not already started and enabled
+      if (waitOptions.networkMonitor) {
+        startNetworkMonitoring();
+      }
+      checkCondition(resolve, startTime, timeoutMs, waitOptions);
     });
   }
 
@@ -226,7 +311,7 @@ const createRedraw = (
     stopNetworkMonitoring(networkInterval);
   }
 
-  return { start, wait, cleanup };
+  return { start, wait, cleanup, DEFAULT_OPTIONS: DEFAULT_REDRAW_OPTIONS };
 };
 
-module.exports = { createRedraw };
+module.exports = { createRedraw, DEFAULT_REDRAW_OPTIONS };

package/agent/lib/sandbox.js

@@ -2,7 +2,7 @@ const WebSocket = require("ws");
 const marky = require("marky");
 const { events } = require("../events");
 
-const createSandbox = (emitter, analytics) => {
+const createSandbox = (emitter, analytics, sessionInstance) => {
   class Sandbox {
     constructor() {
       this.socket = null;
@@ -15,6 +15,7 @@ const createSandbox = (emitter, analytics) => {
       this.messageId = 0;
       this.uniqueId = Math.random().toString(36).substring(7);
       this.os = null; // Store OS value to send with every message
+      this.sessionInstance = sessionInstance; // Store session instance to include in messages
     }
 
     send(message) {
@@ -35,6 +36,14 @@ const createSandbox = (emitter, analytics) => {
           message.os = this.os;
         }
 
+        // Add session to every message if available (for interaction tracking)
+        if (this.sessionInstance && !message.session) {
+          const sessionId = this.sessionInstance.get();
+          if (sessionId) {
+            message.session = sessionId;
+          }
+        }
+
         // Start timing for this message
         const timingKey = `sandbox-${message.type}`;
         marky.mark(timingKey);
@@ -114,8 +123,8 @@ const createSandbox = (emitter, analytics) => {
         this.socket.on("open", async () => {
           this.apiSocketConnected = true;
 
-          setInterval(() => {
-            if (this.socket.readyState === WebSocket.OPEN) {
+          this.heartbeat = setInterval(() => {
+            if (this.socket && this.socket.readyState === WebSocket.OPEN) {
               this.socket.ping();
             }
           }, 5000);
@@ -166,6 +175,34 @@ const createSandbox = (emitter, analytics) => {
         });
       });
     }
+
+    /**
+     * Close the WebSocket connection and clean up resources
+     */
+    close() {
+      if (this.heartbeat) {
+        clearInterval(this.heartbeat);
+        this.heartbeat = null;
+      }
+      
+      if (this.socket) {
+        try {
+          this.socket.close();
+        } catch (err) {
+          // Ignore close errors
+        }
+        this.socket = null;
+      }
+      
+      this.apiSocketConnected = false;
+      this.instanceSocketConnected = false;
+      this.authenticated = false;
+      this.instance = null;
+      
+      // Silently clear pending promises without rejecting
+      // (rejecting causes unhandled promise rejections during cleanup)
+      this.ps = {};
+    }
   }
 
   return new Sandbox();

package/agent/lib/sdk.js

@@ -194,6 +194,27 @@ const createSDK = (emitter, config, sessionInstance) => {
 
       return value;
     } catch (error) {
+      // Check if this is an API validation error with detailed problems
+      if (error.response?.data?.problems) {
+        const problems = error.response.data.problems;
+        const errorMessage = error.response.data.message || 'API validation error';
+        const detailedError = new Error(
+          `${errorMessage}\n\nDetails:\n${problems.map(p => `  - ${p}`).join('\n')}`
+        );
+        detailedError.originalError = error;
+        detailedError.problems = problems;
+        
+        // Emit the formatted error
+        emitter.emit(events.error.sdk, {
+          message: detailedError.message,
+          code: error.response?.data?.code || error.code,
+          problems: problems,
+          fullError: error,
+        });
+        
+        throw detailedError;
+      }
+      
       outputError(error);
       throw error; // Re-throw the error so calling code can handle it properly
     }

package/agent/lib/valid-version.js

@@ -1,9 +1,9 @@
 const semver = require("semver");
-const package = require("../../package.json");
+const packageJson = require("../../package.json");
 
 // Function to check if the new version's minor version is >= current version's minor version
 module.exports = (inputVersion) => {
-  const currentParsed = semver.parse(package.version);
+  const currentParsed = semver.parse(packageJson.version);
   const inputParsed = semver.parse(inputVersion.replace("v", ""));
 
   if (!currentParsed || !inputParsed) {

package/debugger/index.html

@@ -8,7 +8,7 @@
       rel="stylesheet"
     />
     <link rel="icon" type="image/png" href="icon.png" />
-    <title>TestDriver</title>
+    <title>TestDriver - Debugger</title>
     <style>
       body {
         background-color: #111;

package/docs/docs.json

@@ -17,67 +17,7 @@
         "tab": "Computer-Use SDK",
         "versions": [
           {
-            "version": "7.0.0 (SDK)",
-            "groups": [
-              {
-                "group": "Getting Started",
-                "pages": [
-                  "/v7/getting-started/quickstart"
-                ]
-              },
-              {
-                "group": "API Reference",
-                "pages": [
-                  {
-                    "group": "Setup",
-                    "icon": "gear",
-                    "pages": [
-                      "/v7/api/client",
-                      "/v7/api/sandbox"
-                    ]
-                  },
-                  {
-                    "group": "Actions",
-                    "icon": "wand-magic-sparkles",
-                    "pages": [
-                      "/v7/api/ai"
-                    ]
-                  },
-                  {
-                    "group": "Methods",
-                    "icon": "code",
-                    "pages": [
-                      "/v7/api/find",
-                      "/v7/api/click",
-                      "/v7/api/type",
-                      "/v7/api/pressKeys",
-                      "/v7/api/scroll",
-                      "/v7/api/hover",
-                      "/v7/api/exec",
-                      "/v7/api/focusApplication",
-                      "/v7/api/assert"
-                    ]
-                  },
-                  {
-                    "group": "Reference",
-                    "icon": "book",
-                    "pages": [
-                      "/v7/api/elements",
-                      "/v7/api/assertions"
-                    ]
-                  }
-                ]
-              },
-              {
-                "group": "Guides",
-                "pages": [
-                  "/v7/guides/migration"
-                ]
-              }
-            ]
-          },
-          {
-            "version": "6.X.X (YAML)",
+            "version": "v6 (YAML)",
             "groups": [
               {
                 "group": "Overview",
@@ -249,18 +189,93 @@
                 ]
               }
             ]
+          },
+          {
+            "version": "v7 (JS Beta)",
+            "groups": [
+              {
+                "group": "Overview",
+                "icon": "circle-info",
+                "pages": [
+                  "/v7/overview/what-is-testdriver",
+                  {
+                    "group": "Features",
+                    "icon": "star",
+                    "pages": [
+                      "/v7/features/easy-to-write",
+                      "/v7/features/fast",
+                      "/v7/features/stable",
+                      "/v7/features/scalable",
+                      "/v7/features/ai-native",
+                      "/v7/features/powerful",
+                      "/v7/features/observable",
+                      "/v7/features/enterprise"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Getting Started",
+                "icon": "rocket",
+                "pages": [
+                  "/v7/getting-started/installation",
+                  "/v7/getting-started/writing-tests",
+                  "/v7/getting-started/generating-tests",
+                  "/v7/getting-started/running-and-debugging",
+                  "/v7/getting-started/setting-up-in-ci"
+                ]
+              },
+              {
+                "group": "Examples",
+                "icon": "code",
+                "pages": [
+                  "/v7/presets/chrome",
+                  "/v7/presets/chrome-extension",
+                  "/v7/presets/vscode",
+                  "/v7/presets/electron",
+                  "/v7/presets/webapp"
+                ]
+              },
+              {
+                "group": "API Reference",
+                "icon": "book",
+                "pages": [
+                  "/v7/api/client",
+                  "/v7/api/sandbox",
+                  {
+                    "group": "Interactions",
+                    "icon": "bolt",
+                    "pages": [
+                      "/v7/api/find",
+                      "/v7/api/elements",
+                      "/v7/api/click",
+                      "/v7/api/doubleClick",
+                      "/v7/api/rightClick",
+                      "/v7/api/hover",
+                      "/v7/api/mouseDown",
+                      "/v7/api/mouseUp",
+                      "/v7/api/type",
+                      "/v7/api/pressKeys",
+                      "/v7/api/scroll",
+                      "/v7/api/focusApplication"
+                    ]
+                  },
+                  {
+                    "group": "AI & Assertions",
+                    "icon": "wand-magic-sparkles",
+                    "pages": [
+                      "/v7/api/act",
+                      "/v7/api/assert",
+                      "/v7/api/assertions"
+                    ]
+                  },
+                  "/v7/api/exec",
+                  "/v7/api/dashcam"
+                ]
+              }
+            ]
           }
         ]
-      },
-      {
-        "tab": "Playwright SDK",
-        "pages": ["v7/playwright"]
-      },
-      {
-        "tab": "Playwright Studio"
-      },
-      {
-        "tab": "Dashcam CLI"
       }
     ]
   },

package/docs/guide/best-practices-polling.mdx

@@ -0,0 +1,154 @@
+# Best Practices: Element Polling
+
+**⚠️ CRITICAL: Never use `wait()` for waiting for elements to appear.**
+
+## Why Avoid `wait()`?
+
+Arbitrary waits with `wait()` have several problems:
+
+1. **Brittle**: Fixed timeouts may be too short (causing flaky tests) or too long (wasting time)
+2. **Slow**: You always wait the full duration, even if the element appears sooner
+3. **Unreliable**: Network conditions, system load, and other factors affect timing
+4. **Hard to debug**: When tests fail, you don't know if it was a timing issue or actual failure
+
+## The Right Way: Element Polling with `find()`
+
+TestDriver's `find()` method is designed for element detection. Use it in a polling loop to wait for elements:
+
+### Basic Polling Pattern
+
+```javascript
+// ❌ WRONG: Using wait()
+await testdriver.wait(2000);
+const button = await testdriver.find("Submit button");
+
+// ✅ CORRECT: Polling with find()
+let button;
+for (let i = 0; i < 10; i++) {
+  try {
+    button = await testdriver.find("Submit button");
+    if (button.found()) break;
+  } catch (e) {
+    if (i === 9) throw e; // Re-throw on last attempt
+  }
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+```
+
+### Helper Function for Polling
+
+Create a reusable helper function:
+
+```javascript
+async function waitForElement(testdriver, description, maxAttempts = 10, delayMs = 1000) {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      const element = await testdriver.find(description);
+      if (element.found()) {
+        return element;
+      }
+    } catch (e) {
+      if (i === maxAttempts - 1) throw e;
+    }
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+  }
+  throw new Error(`Element not found after ${maxAttempts} attempts: ${description}`);
+}
+
+// Usage
+const emailField = await waitForElement(testdriver, "Email input field");
+await emailField.click();
+```
+
+## When to Use Polling
+
+Use element polling in these scenarios:
+
+- **After navigation**: Waiting for a new page to load
+- **After user action**: Waiting for UI updates (form submission, modal opening, etc.)
+- **Dynamic content**: Waiting for AJAX-loaded elements
+- **State transitions**: Waiting for loading spinners to disappear or success messages to appear
+
+## Example: Complete Login Flow
+
+```javascript
+import { chrome } from "testdriverai/presets";
+
+// Helper function
+async function waitForElement(testdriver, description, maxAttempts = 10, delayMs = 1000) {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      const element = await testdriver.find(description);
+      if (element.found()) return element;
+    } catch (e) {
+      if (i === maxAttempts - 1) throw e;
+    }
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+  }
+  throw new Error(`Element not found after ${maxAttempts} attempts: ${description}`);
+}
+
+it("should log in successfully", async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com/login',
+  });
+
+  // Wait for login page to load
+  const emailField = await waitForElement(testdriver, "Email input field");
+  await emailField.click();
+  await testdriver.type("user@example.com");
+
+  const passwordField = await testdriver.find("Password input field");
+  await passwordField.click();
+  await testdriver.type("password123");
+
+  const loginButton = await testdriver.find("Login button");
+  await loginButton.click();
+
+  // Wait for dashboard to load after login
+  await waitForElement(testdriver, "Dashboard welcome message");
+  
+  // Verify login successful
+  const isLoggedIn = await testdriver.assert("user is logged in to dashboard");
+  expect(isLoggedIn).toBeTruthy();
+});
+```
+
+## Advanced: Conditional Polling
+
+For elements that may or may not appear (like dialogs or notifications):
+
+```javascript
+// Try to find and dismiss optional dialog
+try {
+  const dialog = await waitForElement(testdriver, "Cookie consent dialog", 3, 500);
+  const acceptButton = await testdriver.find("Accept button");
+  await acceptButton.click();
+  console.log("Dismissed cookie dialog");
+} catch {
+  console.log("No cookie dialog found, continuing...");
+}
+```
+
+## Configuration
+
+Adjust polling parameters based on your needs:
+
+```javascript
+// Quick polling for fast UI updates (check every 300ms, up to 3 seconds)
+await waitForElement(testdriver, "Success message", 10, 300);
+
+// Patient polling for slow operations (check every 2s, up to 20 seconds)
+await waitForElement(testdriver, "Processing complete indicator", 10, 2000);
+```
+
+## Summary
+
+| Pattern | Use Case |
+|---------|----------|
+| **Polling with `find()`** | ✅ Waiting for UI elements to appear or disappear |
+| **`wait()`** | ❌ NEVER use for element waiting |
+| **Helper function** | ✅ Recommended for cleaner, reusable code |
+| **Conditional polling** | ✅ For optional elements (dialogs, notifications) |
+
+Remember: **If you're waiting for something to appear on screen, use `find()` in a polling loop, not `wait()`.**