testdriverai 7.3.12 → 7.3.13

package/.github/workflows/update-examples.yaml

@@ -0,0 +1,53 @@
+name: Update Example Docs
+permissions:
+  contents: write
+on:
+  schedule:
+    - cron: "0 0 * * *" # Daily at midnight UTC
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  update-examples:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run example tests
+        run: set -o pipefail && npx vitest run examples/*.test.mjs 2>&1 | tee test-output.log
+        env:
+          TD_API_KEY: ${{ secrets.TD_API_KEY }}
+          TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}
+          TD_OS: linux
+
+      - name: Extract example URLs
+        if: success()
+        run: node docs/_scripts/extract-example-urls.js --file=test-output.log
+
+      - name: Generate example docs
+        if: success()
+        run: node docs/_scripts/generate-examples.js --skip-ai
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+      - name: Commit and push updated docs
+        if: success()
+        run: |
+          git add docs/
+          git diff --staged --quiet || (git commit -m "docs: update example documentation [skip ci]" && git push origin main)

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [7.3.13](https://github.com/testdriverai/testdriverai/compare/v7.3.12...v7.3.13) (2026-02-17)
+
+
+
 ## [7.3.12](https://github.com/testdriverai/testdriverai/compare/v7.3.11...v7.3.12) (2026-02-17)
 
 

package/agent/events.js

@@ -91,6 +91,7 @@ const events = {
     request: "sdk:request",
     response: "sdk:response",
     progress: "sdk:progress",
+    retry: "sdk:retry",
   },
   sandbox: {
     connected: "sandbox:connected",

package/agent/index.js

@@ -1791,6 +1791,14 @@ ${regression}
         ip: this.ip,
       });
 
+      // Store sandboxId (for self-hosted, use the IP as identifier) so messages include it
+      // This enables the API to reconnect if the websocket connection is rerouted
+      this.sandbox._lastConnectParams = {
+        sandboxId: instance?.instance?.instanceId || instance?.instance?.sandboxId || this.ip,
+        persist: true,
+        keepAlive: this.keepAlive,
+      };
+
       // Mark instance socket as connected so console logs are forwarded
       this.sandbox.instanceSocketConnected = true;
       this.emitter.emit(events.sandbox.connected);

package/agent/lib/commands.js

@@ -51,24 +51,43 @@ class CommandError extends Error {
   }
 }
 
+/**
+ * Normalize redraw options from new thresholds format or legacy format.
+ * New:    { enabled: true, thresholds: { screen: 0.05, network: true } }
+ * Legacy: { enabled: true, diffThreshold: 0.1, screenRedraw: true, networkMonitor: true }
+ * @param {Object} opts - Raw redraw options object
+ * @returns {Object} Normalised { enabled, screenRedraw, networkMonitor }
+ */
+const normalizeRedrawOpts = (opts) => {
+  if (!opts || typeof opts !== 'object') return { enabled: !!opts };
+  const result = { enabled: opts.enabled !== false };
+  if (opts.thresholds && typeof opts.thresholds === 'object') {
+    result.screenRedraw = opts.thresholds.screen !== false;
+    result.networkMonitor = !!opts.thresholds.network;
+  } else {
+    result.screenRedraw = opts.screenRedraw !== undefined ? opts.screenRedraw : true;
+    result.networkMonitor = opts.networkMonitor !== undefined ? opts.networkMonitor : false;
+  }
+  return result;
+};
+
 /**
  * Extract redraw options from command options
  * @param {Object} options - Command options that may contain redraw settings
  * @returns {Object} Redraw options object
  */
 const extractRedrawOptions = (options = {}) => {
-  const redrawOpts = {};
-  
-  // Support nested redraw object: { redraw: { enabled: false, diffThreshold: 0.5 } }
+  // Support nested redraw object (new or legacy format)
   if (options.redraw && typeof options.redraw === 'object') {
-    return options.redraw;
+    return normalizeRedrawOpts(options.redraw);
   }
   
-  // Support flat options for convenience
+  // Support flat options for convenience (legacy)
+  const redrawOpts = {};
   if ('redrawEnabled' in options) redrawOpts.enabled = options.redrawEnabled;
   if ('redrawScreenRedraw' in options) redrawOpts.screenRedraw = options.redrawScreenRedraw;
   if ('redrawNetworkMonitor' in options) redrawOpts.networkMonitor = options.redrawNetworkMonitor;
-  if ('redrawDiffThreshold' in options) redrawOpts.diffThreshold = options.redrawDiffThreshold;
+  if ('redrawDiffThreshold' in options) redrawOpts.screenRedraw = true;
   
   return redrawOpts;
 };
@@ -226,8 +245,8 @@ const createCommands = (
     const assertTimestamp = Date.now();
     const assertStartTime = assertTimestamp;
     
-    // Extract cache and AI options
-    const { threshold = -1, cacheKey, os, resolution, ai } = options;
+    // Extract cache options
+    const { threshold = 0.05, cacheKey, os, resolution, ai } = options;
     
     // Debug log cache settings
     emitter.emit(
@@ -318,9 +337,9 @@ const createCommands = (
    * @param {number} [options.amount=300] - Amount to scroll in pixels
    * @param {Object} [options.redraw] - Redraw detection options
    * @param {boolean} [options.redraw.enabled=true] - Enable/disable redraw detection
-   * @param {boolean} [options.redraw.screenRedraw=true] - Enable/disable screen redraw detection
-   * @param {boolean} [options.redraw.networkMonitor=true] - Enable/disable network monitoring
-   * @param {number} [options.redraw.diffThreshold=0.1] - Screen diff threshold percentage
+   * @param {Object} [options.redraw.thresholds] - Threshold configuration
+   * @param {number|boolean} [options.redraw.thresholds.screen=0.05] - Screen diff threshold (false to disable)
+   * @param {boolean} [options.redraw.thresholds.network=false] - Enable/disable network monitoring
    */
   const scroll = async (direction = 'down', options = {}) => {
     // Capture absolute timestamp at the very start of the command
@@ -461,9 +480,9 @@ const createCommands = (
    * @param {boolean} [options.selectorUsed] - Whether selector was used
    * @param {Object} [options.redraw] - Redraw detection options
    * @param {boolean} [options.redraw.enabled=true] - Enable/disable redraw detection
-   * @param {boolean} [options.redraw.screenRedraw=true] - Enable/disable screen redraw detection
-   * @param {boolean} [options.redraw.networkMonitor=true] - Enable/disable network monitoring
-   * @param {number} [options.redraw.diffThreshold=0.1] - Screen diff threshold percentage
+   * @param {Object} [options.redraw.thresholds] - Threshold configuration
+   * @param {number|boolean} [options.redraw.thresholds.screen=0.05] - Screen diff threshold (false to disable)
+   * @param {boolean} [options.redraw.thresholds.network=false] - Enable/disable network monitoring
    */
   const click = async (...args) => {
     // Capture absolute timestamp at the very start of the command
@@ -904,9 +923,9 @@ const createCommands = (
      * @param {boolean} [options.secret=false] - If true, text is treated as sensitive (not logged or stored)
      * @param {Object} [options.redraw] - Redraw detection options
      * @param {boolean} [options.redraw.enabled=true] - Enable/disable redraw detection
-     * @param {boolean} [options.redraw.screenRedraw=true] - Enable/disable screen redraw detection
-     * @param {boolean} [options.redraw.networkMonitor=true] - Enable/disable network monitoring
-     * @param {number} [options.redraw.diffThreshold=0.1] - Screen diff threshold percentage
+     * @param {Object} [options.redraw.thresholds] - Threshold configuration
+     * @param {number|boolean} [options.redraw.thresholds.screen=0.05] - Screen diff threshold (false to disable)
+     * @param {boolean} [options.redraw.thresholds.network=false] - Enable/disable network monitoring
      */
     "type": async (text, options = {}) => {
       const { formatter } = require("../../sdk-log-formatter.js");
@@ -976,9 +995,9 @@ const createCommands = (
      * @param {Object} [options] - Additional options
      * @param {Object} [options.redraw] - Redraw detection options
      * @param {boolean} [options.redraw.enabled=true] - Enable/disable redraw detection
-     * @param {boolean} [options.redraw.screenRedraw=true] - Enable/disable screen redraw detection
-     * @param {boolean} [options.redraw.networkMonitor=true] - Enable/disable network monitoring
-     * @param {number} [options.redraw.diffThreshold=0.1] - Screen diff threshold percentage
+     * @param {Object} [options.redraw.thresholds] - Threshold configuration
+     * @param {number|boolean} [options.redraw.thresholds.screen=0.05] - Screen diff threshold (false to disable)
+     * @param {boolean} [options.redraw.thresholds.network=false] - Enable/disable network monitoring
      */
     "press-keys": async (keys, options = {}) => {
       const { formatter } = require("../../sdk-log-formatter.js");
@@ -1183,9 +1202,9 @@ const createCommands = (
      * @param {number} [options.timeout=5000] - Timeout in milliseconds
      * @param {Object} [options.redraw] - Redraw detection options
      * @param {boolean} [options.redraw.enabled=true] - Enable/disable redraw detection
-     * @param {boolean} [options.redraw.screenRedraw=true] - Enable/disable screen redraw detection
-     * @param {boolean} [options.redraw.networkMonitor=true] - Enable/disable network monitoring
-     * @param {number} [options.redraw.diffThreshold=0.1] - Screen diff threshold percentage
+     * @param {Object} [options.redraw.thresholds] - Threshold configuration
+     * @param {number|boolean} [options.redraw.thresholds.screen=0.05] - Screen diff threshold (false to disable)
+     * @param {boolean} [options.redraw.thresholds.network=false] - Enable/disable network monitoring
      */
     "wait-for-text": async (...args) => {
       // Capture absolute timestamp at the very start of the command
@@ -1294,9 +1313,9 @@ const createCommands = (
      * @param {boolean} [options.invert=false] - Invert the match
      * @param {Object} [options.redraw] - Redraw detection options
      * @param {boolean} [options.redraw.enabled=true] - Enable/disable redraw detection
-     * @param {boolean} [options.redraw.screenRedraw=true] - Enable/disable screen redraw detection
-     * @param {boolean} [options.redraw.networkMonitor=true] - Enable/disable network monitoring
-     * @param {number} [options.redraw.diffThreshold=0.1] - Screen diff threshold percentage
+     * @param {Object} [options.redraw.thresholds] - Threshold configuration
+     * @param {number|boolean} [options.redraw.thresholds.screen=0.05] - Screen diff threshold (false to disable)
+     * @param {boolean} [options.redraw.thresholds.network=false] - Enable/disable network monitoring
      */
     "scroll-until-text": async (...args) => {
       let text, direction, maxDistance, invert, redrawOptions;
@@ -1448,9 +1467,9 @@ const createCommands = (
      * @param {Object} [options] - Additional options
      * @param {Object} [options.redraw] - Redraw detection options
      * @param {boolean} [options.redraw.enabled=true] - Enable/disable redraw detection
-     * @param {boolean} [options.redraw.screenRedraw=true] - Enable/disable screen redraw detection
-     * @param {boolean} [options.redraw.networkMonitor=true] - Enable/disable network monitoring
-     * @param {number} [options.redraw.diffThreshold=0.1] - Screen diff threshold percentage
+     * @param {Object} [options.redraw.thresholds] - Threshold configuration
+     * @param {number|boolean} [options.redraw.thresholds.screen=0.05] - Screen diff threshold (false to disable)
+     * @param {boolean} [options.redraw.thresholds.network=false] - Enable/disable network monitoring
      */
     "focus-application": async (name, options = {}) => {
       const redrawOptions = extractRedrawOptions(options);

package/agent/lib/redraw.js

@@ -348,9 +348,11 @@ const createRedraw = (
       });
       resolve("true");
     } else {
+      // Poll at 500ms intervals to reduce websocket traffic
+      // (previously 250ms = up to 20 polls per 5s timeout, now max 10)
       setTimeout(() => {
         checkCondition(resolve, startTime, timeoutMs, options);
-      }, 250);
+      }, 500);
     }
   }
 

package/agent/lib/sandbox.js

@@ -39,10 +39,14 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       this.sessionInstance = sessionInstance; // Store session instance to include in messages
       this.traceId = null; // Sentry trace ID for debugging
       this.reconnectAttempts = 0;
-      this.maxReconnectAttempts = 5;
+      this.maxReconnectAttempts = 10;
       this.intentionalDisconnect = false;
       this.apiRoot = null;
       this.apiKey = null;
+      this.reconnectTimer = null; // Track reconnect setTimeout
+      this.reconnecting = false; // Prevent duplicate reconnection attempts
+      this.pendingTimeouts = new Map(); // Track per-message timeouts
+      this.pendingRetryQueue = []; // Queue of requests to retry after reconnection
     }
 
     /**
@@ -89,6 +93,12 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           }
         }
 
+        // Add sandboxId to every message if we have a connected sandbox
+        // This allows the API to reconnect if the connection was rerouted
+        if (this._lastConnectParams?.sandboxId && !message.sandboxId) {
+          message.sandboxId = this._lastConnectParams.sandboxId;
+        }
+
         let p = new Promise((resolve, reject) => {
           this.socket.send(JSON.stringify(message));
           emitter.emit(events.sandbox.sent, message);
@@ -100,6 +110,7 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
 
         // Set up timeout to prevent hanging requests
         const timeoutId = setTimeout(() => {
+          this.pendingTimeouts.delete(requestId);
           if (this.ps[requestId]) {
             delete this.ps[requestId];
             rejectPromise(
@@ -110,20 +121,32 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           }
         }, timeout);
 
+        // Track timeout so close() can clear it
+        this.pendingTimeouts.set(requestId, timeoutId);
+
         this.ps[requestId] = {
           promise: p,
           resolve: (result) => {
             clearTimeout(timeoutId);
+            this.pendingTimeouts.delete(requestId);
             resolvePromise(result);
           },
           reject: (error) => {
             clearTimeout(timeoutId);
+            this.pendingTimeouts.delete(requestId);
             rejectPromise(error);
           },
           message,
           startTime: Date.now(),
         };
 
+        // Fire-and-forget message types: attach .catch() to prevent
+        // unhandled promise rejections if nobody awaits the result
+        const fireAndForgetTypes = ["output", "trackInteraction"];
+        if (fireAndForgetTypes.includes(message.type)) {
+          p.catch(() => {});
+        }
+
         return p;
       }
 
@@ -156,6 +179,9 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
     }
 
     async connect(sandboxId, persist = false, keepAlive = null) {
+      // Store connection params so we can re-establish after reconnection
+      this._lastConnectParams = { sandboxId, persist, keepAlive };
+
       let reply = await this.send({
         type: "connect",
         persist,
@@ -177,34 +203,129 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
     async handleConnectionLoss() {
       if (this.intentionalDisconnect) return;
 
+      // Prevent duplicate reconnection attempts (both 'error' and 'close' fire)
+      if (this.reconnecting) return;
+      this.reconnecting = true;
+
+      // Remove listeners from the old socket to prevent "No pending promise found" warnings
+      // when late responses arrive on the dying connection
+      if (this.socket) {
+        try {
+          this.socket.removeAllListeners("message");
+        } catch (e) {
+          // Ignore errors removing listeners from closed socket
+        }
+      }
+
+      // Queue pending requests for retry after reconnection
+      // (they were sent on the old socket and will never receive responses)
+      const pendingRequestIds = Object.keys(this.ps);
+      if (pendingRequestIds.length > 0) {
+        console.log(`[Sandbox] Queuing ${pendingRequestIds.length} pending request(s) for retry after reconnection`);
+        for (const requestId of pendingRequestIds) {
+          const pending = this.ps[requestId];
+          if (pending) {
+            // Clear the timeout - we'll set a new one when we retry
+            const timeoutId = this.pendingTimeouts.get(requestId);
+            if (timeoutId) {
+              clearTimeout(timeoutId);
+              this.pendingTimeouts.delete(requestId);
+            }
+            // Queue for retry (store message and promise handlers)
+            this.pendingRetryQueue.push({
+              message: pending.message,
+              resolve: pending.resolve,
+              reject: pending.reject,
+            });
+          }
+        }
+        this.ps = {};
+      }
+
+      // Cancel any existing reconnect timer
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+      }
+
       if (this.reconnectAttempts >= this.maxReconnectAttempts) {
         const errorMsg =
           "Unable to reconnect to TestDriver sandbox after multiple attempts. Please check your internet connection.";
         emitter.emit(events.error.sandbox, errorMsg);
         console.error(errorMsg);
+        
+        // Reject all queued requests since reconnection failed
+        if (this.pendingRetryQueue.length > 0) {
+          console.log(`[Sandbox] Rejecting ${this.pendingRetryQueue.length} queued request(s) - reconnection failed`);
+          for (const queued of this.pendingRetryQueue) {
+            queued.reject(new Error("Sandbox reconnection failed after multiple attempts"));
+          }
+          this.pendingRetryQueue = [];
+        }
+        
+        this.reconnecting = false;
         return;
       }
 
       this.reconnectAttempts++;
-      const delay = Math.min(1000 * 2 ** (this.reconnectAttempts - 1), 30000);
+      const delay = Math.min(1000 * 2 ** (this.reconnectAttempts - 1), 60000);
 
       console.log(
         `[Sandbox] Connection lost. Reconnecting in ${delay}ms... (Attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`,
       );
 
-      setTimeout(async () => {
+      this.reconnectTimer = setTimeout(async () => {
+        this.reconnectTimer = null;
         try {
           await this.boot(this.apiRoot);
           if (this.apiKey) {
             await this.auth(this.apiKey);
           }
+          // Re-establish sandbox connection on the new API instance
+          // Without this, the new API instance has no connection.desktop
+          // and all Linux operations will fail with "sandbox not initialized"
+          if (this._lastConnectParams) {
+            const { sandboxId, persist, keepAlive } = this._lastConnectParams;
+            console.log(`[Sandbox] Re-establishing sandbox connection (${sandboxId})...`);
+            await this.connect(sandboxId, persist, keepAlive);
+          }
           console.log("[Sandbox] Reconnected successfully.");
+          
+          // Retry queued requests
+          await this._retryQueuedRequests();
         } catch (e) {
-          // Ignore error here as the boot's error handler will trigger handleConnectionLoss again
+          // boot's close handler will trigger handleConnectionLoss again
+        } finally {
+          this.reconnecting = false;
         }
       }, delay);
     }
 
+    /**
+     * Retry queued requests after successful reconnection
+     * @private
+     */
+    async _retryQueuedRequests() {
+      if (this.pendingRetryQueue.length === 0) return;
+
+      console.log(`[Sandbox] Retrying ${this.pendingRetryQueue.length} queued request(s)...`);
+      
+      // Take all queued requests and clear the queue
+      const toRetry = this.pendingRetryQueue.splice(0);
+      
+      for (const queued of toRetry) {
+        try {
+          // Re-send the message and resolve/reject the original promise
+          const result = await this.send(queued.message);
+          queued.resolve(result);
+        } catch (err) {
+          queued.reject(err);
+        }
+      }
+      
+      console.log(`[Sandbox] Finished retrying queued requests.`);
+    }
+
     async boot(apiRoot) {
       if (apiRoot) this.apiRoot = apiRoot;
       return new Promise((resolve, reject) => {
@@ -233,10 +354,11 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
         // handle errors
         this.socket.on("close", () => {
           clearInterval(this.heartbeat);
-          // Emit a clear error event for API key issues
-          reject();
           this.apiSocketConnected = false;
+          // Reset reconnecting flag so handleConnectionLoss can run for this new disconnection
+          this.reconnecting = false;
           this.handleConnectionLoss();
+          reject();
         });
 
         this.socket.on("error", (err) => {
@@ -245,13 +367,14 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           clearInterval(this.heartbeat);
           emitter.emit(events.error.sandbox, err);
           this.apiSocketConnected = false;
-          this.handleConnectionLoss();
-          // We don't throw here to avoid crashing the process, let reconnection handle it
+          // Don't call handleConnectionLoss here - the 'close' event always fires
+          // after 'error', so let 'close' handle reconnection to avoid duplicate attempts
           reject(err);
         });
 
         this.socket.on("open", async () => {
           this.reconnectAttempts = 0;
+          this.reconnecting = false;
           this.apiSocketConnected = true;
 
           this.heartbeat = setInterval(() => {
@@ -259,6 +382,10 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
               this.socket.ping();
             }
           }, 5000);
+          // Don't let the heartbeat interval prevent Node process from exiting
+          if (this.heartbeat.unref) {
+            this.heartbeat.unref();
+          }
 
           resolve(this);
         });
@@ -276,15 +403,24 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           }
 
           if (!this.ps[message.requestId]) {
-            console.warn(
-              "No pending promise found for requestId:",
-              message.requestId,
-            );
+            // This can happen during reconnection (ps was cleared) or after timeout
+            // (promise was deleted). Only log at debug level since it's expected.
+            if (!this.reconnecting) {
+              console.warn(
+                "No pending promise found for requestId:",
+                message.requestId,
+              );
+            }
             return;
           }
 
           if (message.error) {
-            emitter.emit(events.error.sandbox, message.errorMessage);
+            // Don't emit error:sandbox for output (log forwarding) messages
+            // to prevent infinite loops: error → log → sendToSandbox → error → ...
+            const pendingMessage = this.ps[message.requestId]?.message;
+            if (pendingMessage?.type !== "output") {
+              emitter.emit(events.error.sandbox, message.errorMessage);
+            }
             const error = new Error(message.errorMessage || "Sandbox error");
             error.responseData = message;
             this.ps[message.requestId].reject(error);
@@ -302,12 +438,27 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
      */
     close() {
       this.intentionalDisconnect = true;
+      this.reconnecting = false;
+      // Cancel any pending reconnect timer
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+      }
+
       if (this.heartbeat) {
         clearInterval(this.heartbeat);
         this.heartbeat = null;
       }
 
+      // Clear all pending message timeouts to prevent timers keeping the process alive
+      for (const timeoutId of this.pendingTimeouts.values()) {
+        clearTimeout(timeoutId);
+      }
+      this.pendingTimeouts.clear();
+
       if (this.socket) {
+        // Remove all listeners before closing to prevent reconnect attempts
+        this.socket.removeAllListeners();
         try {
           this.socket.close();
         } catch (err) {
@@ -321,9 +472,10 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       this.authenticated = false;
       this.instance = null;
 
-      // Silently clear pending promises without rejecting
+      // Silently clear pending promises and retry queue without rejecting
       // (rejecting causes unhandled promise rejections during cleanup)
       this.ps = {};
+      this.pendingRetryQueue = [];
     }
   }