testdriverai 7.3.44 → 7.4.1

package/agent/lib/debugger-server.js

@@ -84,6 +84,13 @@ function createDebuggerServer(config = {}) {
         return;
       }
       const actualPort = address.port;
+      
+      // Don't let the debugger server prevent Node process from exiting
+      // This ensures tests can exit even if debugger cleanup fails
+      if (server.unref) {
+        server.unref();
+      }
+      
       resolve({ port: actualPort, server, wss });
     });
 
@@ -110,6 +117,9 @@ function broadcastEvent(event, data) {
 
 async function startDebugger(config = {}, emitter) {
   try {
+    // Register exit handler to ensure cleanup on process exit
+    registerExitHandler();
+    
     const { port } = await createDebuggerServer(config);
     const url = `http://localhost:${port}`;
 
@@ -190,6 +200,29 @@ function stopDebugger() {
   forceStopDebugger();
 }
 
+// Ensure debugger server is cleaned up on process exit
+// This prevents zombie processes when tests crash or cleanup fails
+let exitHandlerRegistered = false;
+function registerExitHandler() {
+  if (exitHandlerRegistered) return;
+  exitHandlerRegistered = true;
+  
+  process.on("exit", () => {
+    if (server || wss) {
+      // Synchronous cleanup - can't await in exit handler
+      if (wss) {
+        try { wss.close(); } catch (e) { /* ignore */ }
+        wss = null;
+      }
+      if (server) {
+        try { server.close(); } catch (e) { /* ignore */ }
+        server = null;
+      }
+      clients.clear();
+    }
+  });
+}
+
 module.exports = {
   startDebugger,
   stopDebugger,

package/agent/lib/sandbox.js

@@ -128,6 +128,10 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
             );
           }
         }, timeout);
+        // Don't let pending timeouts prevent Node process from exiting
+        if (timeoutId.unref) {
+          timeoutId.unref();
+        }
 
         // Track timeout so close() can clear it
         this.pendingTimeouts.set(requestId, timeoutId);
@@ -150,7 +154,7 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
 
         // Fire-and-forget message types: attach .catch() to prevent
         // unhandled promise rejections if nobody awaits the result
-        const fireAndForgetTypes = ["output", "trackInteraction"];
+        const fireAndForgetTypes = ["output"];
         if (fireAndForgetTypes.includes(message.type)) {
           p.catch(() => {});
         }
@@ -360,6 +364,10 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           this.reconnecting = false;
         }
       }, delay);
+      // Don't let reconnect timer prevent Node process from exiting
+      if (this.reconnectTimer.unref) {
+        this.reconnectTimer.unref();
+      }
     }
 
     /**

package/agent/lib/sdk.js

@@ -346,6 +346,73 @@ const createSDK = (emitter, config, sessionInstance) => {
       }
     }
 
+    // ── S3 upload: replace large inline base64 images with S3 keys ──────
+    // If data.image is a large base64 string (>50KB), upload the raw PNG
+    // to S3 via a presigned URL and send only the imageKey instead.
+    // This reduces JSON body size from ~1.3MB to ~60 bytes.
+    const MIN_IMAGE_SIZE = 50_000; // 50KB base64 chars
+    if (
+      data &&
+      typeof data.image === "string" &&
+      data.image.length > MIN_IMAGE_SIZE
+    ) {
+      try {
+        const apiRoot = config["TD_API_ROOT"];
+        const uploadUrlEndpoint = [apiRoot, "api", version, "testdriver", "upload-url"].join("/");
+
+        // Step 1: Get presigned upload URL from API
+        const uploadRes = await axios(uploadUrlEndpoint, {
+          method: "post",
+          headers: {
+            "Content-Type": "application/json",
+            ...(token && { Authorization: `Bearer ${token}` }),
+          },
+          timeout: 15000,
+          data: {
+            session: sessionInstance.get(),
+            contentType: "image/png",
+          },
+        });
+
+        const { uploadUrl, imageKey } = uploadRes.data;
+
+        if (uploadUrl && imageKey) {
+          // Step 2: Upload raw PNG bytes to S3 via presigned PUT URL
+          const base64Data = data.image.replace(/^data:image\/\w+;base64,/, "");
+          const pngBuffer = Buffer.from(base64Data, "base64");
+
+          await axios(uploadUrl, {
+            method: "put",
+            headers: {
+              "Content-Type": "image/png",
+              "Content-Length": pngBuffer.length,
+            },
+            data: pngBuffer,
+            timeout: 30000,
+            maxBodyLength: Infinity,
+            maxContentLength: Infinity,
+          });
+
+          // Step 3: Replace image with imageKey in the request data
+          const savedKB = (data.image.length / 1024).toFixed(0);
+          delete data.image;
+          data.imageKey = imageKey;
+          emitter.emit(events.log?.debug || events.sdk.request, {
+            path,
+            message: `[sdk] uploaded screenshot to S3 (saved ${savedKB}KB inline), imageKey=${imageKey}`,
+          });
+        }
+      } catch (uploadErr) {
+        // Non-fatal: fall back to sending base64 inline
+        // This ensures old API servers without the upload-url endpoint still work
+        emitter.emit(events.log?.debug || events.sdk.request, {
+          path,
+          message: `[sdk] S3 upload failed, falling back to inline base64: ${uploadErr.message}`,
+        });
+      }
+    }
+    // ── End S3 upload ───────────────────────────────────────────────────
+
     emitter.emit(events.sdk.request, {
       path,
     });

package/ai/skills/testdriver:client/SKILL.md

@@ -24,7 +24,7 @@ const testdriver = new TestDriver(apiKey, options)
   Configuration options for the client
   
   <Expandable title="properties">
-    <ParamField path="os" type="string" default="windows">
+    <ParamField path="os" type="string" default="linux">
       Operating system for the sandbox: `'windows'` or `'linux'`
     </ParamField>
     
@@ -32,7 +32,7 @@ const testdriver = new TestDriver(apiKey, options)
       Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`)
     </ParamField>
     
-    <ParamField path="apiRoot" type="string" default="https://testdriver-api.onrender.com">
+    <ParamField path="apiRoot" type="string">
       API endpoint URL (typically only changed for self-hosted deployments)
     </ParamField>
     
@@ -48,6 +48,111 @@ const testdriver = new TestDriver(apiKey, options)
       Automatically capture screenshots before and after each command. Screenshots are saved to `.testdriver/screenshots/<test>/` with descriptive filenames that include the line number and action name. Format: `<seq>-<action>-<phase>-L<line>-<description>.png`
     </ParamField>
     
+    <ParamField path="newSandbox" type="boolean" default="true">
+      Force creation of a new sandbox instead of reusing an existing one
+    </ParamField>
+    
+    <ParamField path="reconnect" type="boolean" default="false">
+      Reconnect to the last used sandbox instead of creating a new one. When `true`, provision methods (`chrome`, `vscode`, `installer`, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists.
+    </ParamField>
+    
+    <ParamField path="keepAlive" type="number" default="60000">
+      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+    </ParamField>
+    
+    <ParamField path="preview" type="string" default="browser">
+      Preview mode for live test visualization:
+      - `"browser"` — Opens debugger in default browser (default)
+      - `"ide"` — Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension)
+      - `"none"` — Headless mode, no visual preview
+    </ParamField>
+    
+    <ParamField path="headless" type="boolean" default="false">
+      **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
+    </ParamField>
+    
+    <ParamField path="debugOnFailure" type="boolean" default="false">
+      Keep the sandbox alive when a test fails so you can reconnect and debug interactively. The sandbox ID is printed to the console.
+    </ParamField>
+    
+    <ParamField path="ip" type="string">
+      Direct IP address to connect to a running sandbox instance (for self-hosted deployments)
+    </ParamField>
+    
+    <ParamField path="sandboxAmi" type="string">
+      Custom AMI ID for the sandbox instance (AWS deployments, e.g., `'ami-1234'`)
+    </ParamField>
+    
+    <ParamField path="sandboxInstance" type="string">
+      EC2 instance type for the sandbox (AWS deployments, e.g., `'i3.metal'`)
+    </ParamField>
+    
+    <ParamField path="cache" type="boolean | object" default="true">
+      Enable or disable element caching, or provide advanced threshold configuration.
+      
+      <Expandable title="advanced config">
+        <ParamField path="enabled" type="boolean" default="true">
+          Enable or disable caching
+        </ParamField>
+        
+        <ParamField path="thresholds" type="object">
+          Fine-tune cache matching
+          
+          <Expandable title="properties">
+            <ParamField path="find" type="object">
+              Thresholds for `find()` operations
+              
+              <Expandable title="properties">
+                <ParamField path="screen" type="number" default="0.05">
+                  Pixel diff threshold for screen comparison (0-1). `0.05` = 5% diff allowed.
+                </ParamField>
+                
+                <ParamField path="element" type="number" default="0.8">
+                  OpenCV template match threshold for element matching (0-1). `0.8` = 80% correlation.
+                </ParamField>
+              </Expandable>
+            </ParamField>
+            
+            <ParamField path="assert" type="number" default="0.05">
+              Pixel diff threshold for `assert()` operations (0-1). `0.05` = 5% diff allowed.
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    
+    <ParamField path="cacheKey" type="string">
+      Cache key for element finding operations. If provided, enables caching tied to this key.
+    </ParamField>
+    
+    <ParamField path="dashcam" type="boolean" default="true">
+      Enable or disable Dashcam video recording
+    </ParamField>
+    
+    <ParamField path="redraw" type="boolean | object" default="true">
+      Enable or disable screen-change (redraw) detection, or provide advanced configuration.
+      
+      <Expandable title="advanced config">
+        <ParamField path="enabled" type="boolean" default="true">
+          Enable or disable redraw detection
+        </ParamField>
+        
+        <ParamField path="thresholds" type="object">
+          Threshold configuration
+          
+          <Expandable title="properties">
+            <ParamField path="screen" type="number | false" default="0.05">
+              Pixel diff threshold (0-1). Set to `false` to disable screen redraw detection.
+            </ParamField>
+            
+            <ParamField path="network" type="boolean" default="false">
+              Enable or disable network activity monitoring
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    
     <ParamField path="environment" type="object">
       Additional environment variables to pass to the sandbox
     </ParamField>

package/ai/skills/testdriver:customizing-devices/SKILL.md

@@ -10,7 +10,64 @@ Configure TestDriver behavior with options passed to the `TestDriver()` function
 
 ```javascript
 const testdriver = TestDriver(context, {
-  reconnect: false,
+  // === Sandbox & Connection ===
+  newSandbox: true,          // Force creation of a new sandbox (default: true)
+  reconnect: false,          // Reconnect to last sandbox (default: false)
+  keepAlive: 60000,          // Keep sandbox alive after disconnect in ms (default: 60000)
+  os: "linux",               // 'linux' | 'windows' (default: 'linux')
+  resolution: "1366x768",    // Sandbox resolution (e.g., '1920x1080')
+  ip: "203.0.113.42",        // Direct IP for self-hosted sandbox
+  sandboxAmi: "ami-1234",    // Custom AMI ID (AWS deployments)
+  sandboxInstance: "i3.metal", // EC2 instance type (AWS deployments)
+
+  // === Preview & Debugging ===
+  preview: "browser",        // "browser" | "ide" | "none" (default: "browser")
+  headless: false,           // @deprecated - use preview: "none" instead
+  debugOnFailure: false,     // Keep sandbox alive on test failure for debugging
+
+  // === Caching ===
+  cache: true,               // Enable element caching (default: true)
+  // Or use advanced caching config:
+  // cache: {
+  //   enabled: true,
+  //   thresholds: {
+  //     find: { screen: 0.05, element: 0.8 },
+  //     assert: 0.05
+  //   }
+  // },
+  cacheKey: "my-test",       // Cache key for element finding operations
+
+  // === Recording & Screenshots ===
+  dashcam: true,             // Enable/disable Dashcam video recording (default: true)
+  autoScreenshots: true,     // Capture screenshots before/after each command (default: true)
+
+  // === AI Configuration ===
+  ai: {                      // Global AI sampling configuration
+    temperature: 0,          // 0 = deterministic, higher = more creative
+    top: {
+      p: 0.9,               // Top-P nucleus sampling (0-1)
+      k: 40,                // Top-K sampling (1 = most likely, 0 = disabled)
+    },
+  },
+
+  // === Screen Change Detection ===
+  redraw: true,              // Enable redraw detection (default: true)
+  // Or use advanced redraw config:
+  // redraw: {
+  //   enabled: true,
+  //   thresholds: {
+  //     screen: 0.05,       // Pixel diff threshold (0-1), false to disable
+  //     network: false,     // Monitor network activity (default: false)
+  //   }
+  // },
+
+  // === Logging & Analytics ===
+  logging: true,             // Enable console logging output (default: true)
+  analytics: true,           // Enable analytics tracking (default: true)
+
+  // === Advanced ===
+  apiRoot: "https://...",    // API endpoint URL (for self-hosted deployments)
+  environment: {},           // Additional environment variables for the sandbox
 });
 ```
 
@@ -54,6 +111,16 @@ const testdriver = TestDriver(context, {
   The legacy `headless: true` option still works for backward compatibility and maps to `preview: "none"`.
 </Note>
 
+### Debug on Failure
+
+Keep the sandbox alive when a test fails so you can reconnect and debug interactively. The sandbox ID is printed to the console along with instructions for reconnecting via MCP.
+
+```javascript
+const testdriver = TestDriver(context, {
+  debugOnFailure: true,
+});
+```
+
 ### IP Target
 
 If self-hosting TestDriver, use `ip` to specify the device IP. See [Self-Hosting TestDriver](../self-hosting.md) for details.
@@ -105,11 +172,102 @@ steps:
   - run: TD_OS=${{ matrix.os }} vitest run
 ```
 
-## Keepalive
+### Dashcam Recording
+
+Dashcam video recording is enabled by default. Disable it to skip recording:
+
+```javascript
+const testdriver = TestDriver(context, {
+  dashcam: false,
+});
+```
+
+### Automatic Screenshots
+
+Screenshots are automatically captured before and after every command (click, type, find, assert, etc.) by default. Each screenshot filename includes the line number from your test file.
+
+Disable automatic screenshots:
+
+```javascript
+const testdriver = TestDriver(context, {
+  autoScreenshots: false,
+});
+```
+
+### Caching
+
+Element caching speeds up repeated `find()` and `assert()` calls. Enabled by default.
+
+```javascript
+// Disable caching
+const testdriver = TestDriver(context, {
+  cache: false,
+});
+
+// Advanced: custom thresholds
+const testdriver = TestDriver(context, {
+  cache: {
+    enabled: true,
+    thresholds: {
+      find: { screen: 0.05, element: 0.8 },
+      assert: 0.05,
+    },
+  },
+  cacheKey: "my-test",
+});
+```
 
-By default, sandboxes terminate immediately when the test finishes. Set this value to keep the sandbox alive for reconnection.
+### Redraw Detection
 
-The `keepAlive` param enables you to keep the sandbox running after the test completes for debugging or reconnection.  This will allow you to use the debugger to inspect the state of the device after the test has finished.
+Redraw detection waits for the screen to stabilize before taking actions. Enabled by default.
+
+```javascript
+// Disable redraw detection
+const testdriver = TestDriver(context, {
+  redraw: false,
+});
+
+// Advanced: custom thresholds with network monitoring
+const testdriver = TestDriver(context, {
+  redraw: {
+    enabled: true,
+    thresholds: {
+      screen: 0.05,
+      network: true,
+    },
+  },
+});
+```
+
+### AI Configuration
+
+Control how the AI model generates responses for `find()` verification and `assert()` calls:
+
+```javascript
+const testdriver = TestDriver(context, {
+  ai: {
+    temperature: 0,       // 0 = deterministic
+    top: { p: 0.9, k: 40 },
+  },
+});
+```
+
+### Environment Variables
+
+Pass additional environment variables to the sandbox:
+
+```javascript
+const testdriver = TestDriver(context, {
+  environment: {
+    MY_VAR: "value",
+    DEBUG: "true",
+  },
+});
+```
+
+## Keepalive
+
+By default, sandboxes stay alive for 60 seconds after disconnect. Customize this with `keepAlive`:
 
 ```javascript
 const testdriver = TestDriver(context, {
@@ -117,6 +275,14 @@ const testdriver = TestDriver(context, {
 });
 ```
 
+Set to `0` to terminate immediately:
+
+```javascript
+const testdriver = TestDriver(context, {
+  keepAlive: 0,  // Terminate sandbox immediately on disconnect
+});
+```
+
 ### Reconnecting to Existing Sandbox
 
 Speed up test development by reconnecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.

package/ai/skills/testdriver:find/SKILL.md

@@ -33,8 +33,8 @@ const element = await testdriver.find(description, options)
       Similarity threshold (0-1) for cache matching. Lower values require more similarity. Set to -1 to disable cache.
     </ParamField>
     
-    <ParamField path="timeout" type="number">
-      Maximum time in milliseconds to poll for the element. Retries every 5 seconds until found or timeout expires.
+    <ParamField path="timeout" type="number" default={10000}>
+      Maximum time in milliseconds to poll for the element. Retries every 5 seconds until found or timeout expires. Defaults to `10000` (10 seconds). Set to `0` to disable polling and make a single attempt.
     </ParamField>
     
     <ParamField path="confidence" type="number">
@@ -309,19 +309,28 @@ const el = await testdriver.find('the blue submit button', { type: 'any' });
 </Tip>
 ## Polling for Dynamic Elements
 
-For elements that may not be immediately visible, use the `timeout` option to automatically poll:
+By default, `find()` polls for up to 10 seconds (retrying every 5 seconds) until the element is found. You can customize this with the `timeout` option:
 
 ```javascript
-// Poll for element (retries every 5 seconds until found or timeout)
+// Uses default 10s timeout - polls every 5 seconds
+const element = await testdriver.find('login button');
+await element.click();
+
+// Custom timeout - wait up to 30 seconds
 const element = await testdriver.find('login button', { timeout: 30000 });
 await element.click();
+
+// Disable polling - single attempt only
+const element = await testdriver.find('login button', { timeout: 0 });
 ```
 
 The `timeout` option:
+- Defaults to `10000` (10 seconds)
 - Retries finding the element every 5 seconds
 - Stops when the element is found or the timeout expires
 - Logs progress during polling
 - Returns the element (check `element.found()` if not throwing on failure)
+- Set to `0` to disable polling and make a single attempt
 
 ## Zoom Mode for Crowded UIs
 

package/ai/skills/testdriver:waiting-for-elements/SKILL.md

@@ -6,10 +6,16 @@ description: Handle async operations and prevent flaky tests
 
 ## Waiting for Elements
 
-Use the `timeout` option with `find()` to wait for elements that appear after async operations:
+By default, `find()` automatically polls for up to 10 seconds, retrying every 5 seconds until the element is found. This means most elements that appear after short async operations will be found without any extra configuration.
+
+For longer operations, increase the `timeout`:
 
 ```javascript
-// Wait up to 30 seconds for element to appear (polls every 5 seconds)
+// Default behavior - polls for up to 10 seconds automatically
+const element = await testdriver.find('Loading complete indicator');
+await element.click();
+
+// Wait up to 30 seconds for slower operations
 const element = await testdriver.find('Loading complete indicator', { timeout: 30000 });
 await element.click();
 
@@ -17,8 +23,8 @@ await element.click();
 await testdriver.find('submit button').click();
 await testdriver.find('success message', { timeout: 15000 });
 
-// Short timeout for quick checks
-const toast = await testdriver.find('notification toast', { timeout: 5000 });
+// Disable polling for instant checks
+const toast = await testdriver.find('notification toast', { timeout: 0 });
 ```
 
 ## Flake Prevention

package/docs/v7/find.mdx

@@ -34,8 +34,8 @@ const element = await testdriver.find(description, options)
       Similarity threshold (0-1) for cache matching. Lower values require more similarity. Set to -1 to disable cache.
     </ParamField>
     
-    <ParamField path="timeout" type="number">
-      Maximum time in milliseconds to poll for the element. Retries every 5 seconds until found or timeout expires.
+    <ParamField path="timeout" type="number" default={10000}>
+      Maximum time in milliseconds to poll for the element. Retries every 5 seconds until found or timeout expires. Defaults to `10000` (10 seconds). Set to `0` to disable polling and make a single attempt.
     </ParamField>
     
     <ParamField path="confidence" type="number">
@@ -310,19 +310,28 @@ const el = await testdriver.find('the blue submit button', { type: 'any' });
 </Tip>
 ## Polling for Dynamic Elements
 
-For elements that may not be immediately visible, use the `timeout` option to automatically poll:
+By default, `find()` polls for up to 10 seconds (retrying every 5 seconds) until the element is found. You can customize this with the `timeout` option:
 
 ```javascript
-// Poll for element (retries every 5 seconds until found or timeout)
+// Uses default 10s timeout - polls every 5 seconds
+const element = await testdriver.find('login button');
+await element.click();
+
+// Custom timeout - wait up to 30 seconds
 const element = await testdriver.find('login button', { timeout: 30000 });
 await element.click();
+
+// Disable polling - single attempt only
+const element = await testdriver.find('login button', { timeout: 0 });
 ```
 
 The `timeout` option:
+- Defaults to `10000` (10 seconds)
 - Retries finding the element every 5 seconds
 - Stops when the element is found or the timeout expires
 - Logs progress during polling
 - Returns the element (check `element.found()` if not throwing on failure)
+- Set to `0` to disable polling and make a single attempt
 
 ## Zoom Mode for Crowded UIs
 

package/docs/v7/waiting-for-elements.mdx

@@ -6,10 +6,16 @@ icon: "clock"
 
 ## Waiting for Elements
 
-Use the `timeout` option with `find()` to wait for elements that appear after async operations:
+By default, `find()` automatically polls for up to 10 seconds, retrying every 5 seconds until the element is found. This means most elements that appear after short async operations will be found without any extra configuration.
+
+For longer operations, increase the `timeout`:
 
 ```javascript
-// Wait up to 30 seconds for element to appear (polls every 5 seconds)
+// Default behavior - polls for up to 10 seconds automatically
+const element = await testdriver.find('Loading complete indicator');
+await element.click();
+
+// Wait up to 30 seconds for slower operations
 const element = await testdriver.find('Loading complete indicator', { timeout: 30000 });
 await element.click();
 
@@ -17,8 +23,8 @@ await element.click();
 await testdriver.find('submit button').click();
 await testdriver.find('success message', { timeout: 15000 });
 
-// Short timeout for quick checks
-const toast = await testdriver.find('notification toast', { timeout: 5000 });
+// Disable polling for instant checks
+const toast = await testdriver.find('notification toast', { timeout: 0 });
 ```
 
 ## Flake Prevention

package/examples/hover-image.test.mjs

@@ -13,11 +13,20 @@ import { getDefaults } from "./config.mjs";
  * @param {string} username - Username (default: 'standard_user')
  */
 async function performLogin(client, username = "standard_user") {
+  
+  console.log('Performing login with username:', username);
   await client.focusApplication("Google Chrome");
+
+  console.log('Extracting password from page');
   const password = await client.extract("the password");
+
+  console.log('Password extracted:', password ? '***' : 'not found');
+
   const usernameField = await client.find(
     "username input",
   );
+  
+  console.log('Clicking on username field and entering credentials');
   await usernameField.click();
   await client.type(username);
   await client.pressKeys(["tab"]);
@@ -35,6 +44,8 @@ describe("Hover Image Test", () => {
       url: 'http://testdriver-sandbox.vercel.app/login'
     });
 
+    console.log('starting login')
+
     // Perform login first
     await performLogin(testdriver);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.3.44",
+  "version": "7.4.1",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",