testdriverai 7.2.55 → 7.2.57

package/sdk.js

@@ -19,13 +19,15 @@ function getCallerFilePath() {
     // Look for the first file that's not sdk.js, hooks.mjs, or node internals
     for (const callSite of stack) {
       const fileName = callSite.getFileName();
-      if (fileName && 
-          !fileName.includes('sdk.js') && 
-          !fileName.includes('hooks.mjs') &&
-          !fileName.includes('hooks.js') &&
-          !fileName.includes('node_modules') &&
-          !fileName.includes('node:internal') &&
-          fileName !== 'evalmachine.<anonymous>') {
+      if (
+        fileName &&
+        !fileName.includes("sdk.js") &&
+        !fileName.includes("hooks.mjs") &&
+        !fileName.includes("hooks.js") &&
+        !fileName.includes("node_modules") &&
+        !fileName.includes("node:internal") &&
+        fileName !== "evalmachine.<anonymous>"
+      ) {
         return fileName;
       }
     }
@@ -50,12 +52,12 @@ function getCallerFileHash() {
   try {
     // Handle file:// URLs by converting to file system path
     let fsPath = filePath;
-    if (filePath.startsWith('file://')) {
-      fsPath = filePath.replace('file://', '');
+    if (filePath.startsWith("file://")) {
+      fsPath = filePath.replace("file://", "");
     }
-    
-    const fileContent = fs.readFileSync(fsPath, 'utf-8');
-    const hash = crypto.createHash('sha256').update(fileContent).digest('hex');
+
+    const fileContent = fs.readFileSync(fsPath, "utf-8");
+    const hash = crypto.createHash("sha256").update(fileContent).digest("hex");
     // Return first 16 chars of hash for brevity
     return hash.substring(0, 16);
   } catch (error) {
@@ -298,7 +300,7 @@ class AIError extends Error {
     this.message += `\nTries: ${this.tries}/${this.maxTries}`;
     this.message += `\nDuration: ${this.duration}ms`;
     this.message += `\nTimestamp: ${this.timestamp}`;
-    
+
     if (this.cause) {
       this.message += `\nUnderlying error: ${this.cause.message}`;
     }
@@ -349,17 +351,21 @@ class Element {
     // Include response metadata if available
     if (this._response) {
       result.cache = {
-        hit: this._response.cacheHit || this._response.cache_hit || this._response.cached || false,
+        hit:
+          this._response.cacheHit ||
+          this._response.cache_hit ||
+          this._response.cached ||
+          false,
         strategy: this._response.cacheStrategy,
         createdAt: this._response.cacheCreatedAt,
         diffPercent: this._response.cacheDiffPercent,
         imageUrl: this._response.cachedImageUrl,
       };
-      
+
       result.similarity = this._response.similarity;
       result.confidence = this._response.confidence;
       result.selector = this._response.selector;
-      
+
       // Include AI response text if available
       if (this._response.response?.content?.[0]?.text) {
         result.aiResponse = this._response.response.content[0].text;
@@ -378,7 +384,7 @@ class Element {
    */
   async find(newDescription, options) {
     // Handle timeout/polling option
-    const timeout = typeof options === 'object' ? options?.timeout : null;
+    const timeout = typeof options === "object" ? options?.timeout : null;
     if (timeout && timeout > 0) {
       return this._findWithTimeout(newDescription, options, timeout);
     }
@@ -414,11 +420,11 @@ class Element {
       let cacheKey = null;
       let cacheThreshold = null;
       let zoom = false; // Default to disabled, enable with zoom: true
-      
-      if (typeof options === 'number') {
+
+      if (typeof options === "number") {
         // Legacy: options is just a number threshold
         cacheThreshold = options;
-      } else if (typeof options === 'object' && options !== null) {
+      } else if (typeof options === "object" && options !== null) {
         // New: options is an object with cacheKey and/or cacheThreshold
         cacheKey = options.cacheKey || null;
         cacheThreshold = options.cacheThreshold ?? null;
@@ -428,11 +434,15 @@ class Element {
 
       // Use default cacheKey from SDK constructor if not provided in find() options
       // BUT only if cache is not explicitly disabled via cache: false option
-      if (!cacheKey && this.sdk.options?.cacheKey && !this.sdk._cacheExplicitlyDisabled) {
+      if (
+        !cacheKey &&
+        this.sdk.options?.cacheKey &&
+        !this.sdk._cacheExplicitlyDisabled
+      ) {
         cacheKey = this.sdk.options.cacheKey;
       }
 
-      // Determine threshold: 
+      // Determine threshold:
       // - If cache is explicitly disabled, don't use cache even with cacheKey
       // - If cacheKey is provided, enable cache with threshold
       // - If no cacheKey, disable cache
@@ -458,9 +468,11 @@ class Element {
       // Debug log threshold
       if (debugMode) {
         const { events } = require("./agent/events.js");
-        const autoGenMsg = (this.sdk._autoGeneratedCacheKey && cacheKey === this.sdk.options.cacheKey) 
-          ? ' (auto-generated from file hash)' 
-          : '';
+        const autoGenMsg =
+          this.sdk._autoGeneratedCacheKey &&
+          cacheKey === this.sdk.options.cacheKey
+            ? " (auto-generated from file hash)"
+            : "";
         this.sdk.emitter.emit(
           events.log.debug,
           `🔍 find() threshold: ${threshold} (cache ${threshold < 0 ? "DISABLED" : "ENABLED"}${cacheKey ? `, cacheKey: ${cacheKey}${autoGenMsg}` : ""})`,
@@ -492,7 +504,7 @@ class Element {
         this._response = this._sanitizeResponse(response);
         this._found = false;
         findError = "Element not found";
-        
+
         // Log not found
         const duration = Date.now() - startTime;
         const { events } = require("./agent/events.js");
@@ -508,7 +520,7 @@ class Element {
       this._found = false;
       findError = error.message;
       response = error.response;
-      
+
       // Log not found with error
       const duration = Date.now() - startTime;
       const { events } = require("./agent/events.js");
@@ -517,27 +529,33 @@ class Element {
         error: error.message,
       });
       this.sdk.emitter.emit(events.log.log, notFoundMessage);
-      
+
       console.error("Error during find():", error);
     }
 
     // Track find interaction once at the end (fire-and-forget, don't block)
     const sessionId = this.sdk.getSessionId();
     if (sessionId && this.sdk.sandbox?.send) {
-      await this.sdk.sandbox.send({
-        type: "trackInteraction",
-        interactionType: "find",
-        session: sessionId,
-        prompt: description,
-        timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
-        success: this._found,
-        error: findError,
-        cacheHit: response?.cacheHit || response?.cache_hit || response?.cached || false,
-        selector: response?.selector,
-        selectorUsed: !!response?.selector,
-      }).catch(err => {
-        console.warn("Failed to track find interaction:", err.message);
-      });
+      await this.sdk.sandbox
+        .send({
+          type: "trackInteraction",
+          interactionType: "find",
+          session: sessionId,
+          prompt: description,
+          timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
+          success: this._found,
+          error: findError,
+          cacheHit:
+            response?.cacheHit ||
+            response?.cache_hit ||
+            response?.cached ||
+            false,
+          selector: response?.selector,
+          selectorUsed: !!response?.selector,
+        })
+        .catch((err) => {
+          console.warn("Failed to track find interaction:", err.message);
+        });
     }
 
     return this;
@@ -555,46 +573,58 @@ class Element {
     const POLL_INTERVAL = 5000; // 5 seconds between attempts
     const startTime = Date.now();
     const description = newDescription || this.description;
-    
+
     // Log that we're starting a polling find
     const { events } = require("./agent/events.js");
-    this.sdk.emitter.emit(events.log.log, `🔄 Polling for "${description}" (timeout: ${timeout}ms)`);
-    
+    this.sdk.emitter.emit(
+      events.log.log,
+      `🔄 Polling for "${description}" (timeout: ${timeout}ms)`,
+    );
+
     // Create options without timeout to avoid infinite recursion
-    const findOptions = typeof options === 'object' ? { ...options } : {};
+    const findOptions = typeof options === "object" ? { ...options } : {};
     delete findOptions.timeout;
-    
+
     let attempts = 0;
     while (Date.now() - startTime < timeout) {
       attempts++;
-      
+
       // Call the regular find (without timeout option)
       await this.find(newDescription, findOptions);
-      
+
       if (this._found) {
-        this.sdk.emitter.emit(events.log.log, `✅ Found "${description}" after ${attempts} attempt(s)`);
+        this.sdk.emitter.emit(
+          events.log.log,
+          `✅ Found "${description}" after ${attempts} attempt(s)`,
+        );
         return this;
       }
-      
+
       const elapsed = Date.now() - startTime;
       const remaining = timeout - elapsed;
-      
+
       if (remaining > POLL_INTERVAL) {
-        this.sdk.emitter.emit(events.log.log, `⏳ Element not found, retrying in 5s... (${Math.round(remaining / 1000)}s remaining)`);
-        await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL));
+        this.sdk.emitter.emit(
+          events.log.log,
+          `⏳ Element not found, retrying in 5s... (${Math.round(remaining / 1000)}s remaining)`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
       } else if (remaining > 0) {
         // Less than 5s remaining, wait the remaining time and try once more
-        await new Promise(resolve => setTimeout(resolve, remaining));
+        await new Promise((resolve) => setTimeout(resolve, remaining));
       }
     }
-    
+
     // Final attempt after timeout
     await this.find(newDescription, findOptions);
-    
+
     if (!this._found) {
-      this.sdk.emitter.emit(events.log.log, `❌ Element "${description}" not found after ${timeout}ms (${attempts} attempts)`);
+      this.sdk.emitter.emit(
+        events.log.log,
+        `❌ Element "${description}" not found after ${timeout}ms (${attempts} attempts)`,
+      );
     }
-    
+
     return this;
   }
 
@@ -881,13 +911,22 @@ class Element {
       edgeDetectedImageUrl: this._response?.edgeSavedImagePath || null,
       cacheHit: this._response?.cacheHit,
       selectorUsed: !!this._response?.selector,
-      selector: this._response?.selector
+      selector: this._response?.selector,
     };
 
     if (action === "hover") {
-      await this.commands.hover(this.coordinates.x, this.coordinates.y, elementData);
+      await this.commands.hover(
+        this.coordinates.x,
+        this.coordinates.y,
+        elementData,
+      );
     } else {
-      await this.commands.click(this.coordinates.x, this.coordinates.y, action, elementData);
+      await this.commands.click(
+        this.coordinates.x,
+        this.coordinates.y,
+        action,
+        elementData,
+      );
     }
   }
 
@@ -921,10 +960,14 @@ class Element {
       edgeDetectedImageUrl: this._response?.edgeSavedImagePath || null,
       cacheHit: this._response?.cacheHit,
       selectorUsed: !!this._response?.selector,
-      selector: this._response?.selector
+      selector: this._response?.selector,
     };
 
-    await this.commands.hover(this.coordinates.x, this.coordinates.y, elementData);
+    await this.commands.hover(
+      this.coordinates.x,
+      this.coordinates.y,
+      elementData,
+    );
   }
 
   /**
@@ -1119,54 +1162,69 @@ class Element {
 /**
  * Creates a chainable promise that allows method chaining on find() results
  * This enables syntax like: await testdriver.find("button").click()
- * 
+ *
  * @param {Promise<Element>} promise - The promise that resolves to an Element
  * @returns {Promise<Element> & ChainableElement} A promise with chainable element methods
  */
 function createChainablePromise(promise) {
   // Define the chainable methods that should be available
-  const chainableMethods = ['click', 'hover', 'doubleClick', 'rightClick', 'mouseDown', 'mouseUp'];
-  
+  const chainableMethods = [
+    "click",
+    "hover",
+    "doubleClick",
+    "rightClick",
+    "mouseDown",
+    "mouseUp",
+  ];
+
   // Create a new promise that wraps the original
-  const chainablePromise = promise.then(element => element);
-  
+  const chainablePromise = promise.then((element) => element);
+
   // Add chainable methods to the promise
   for (const method of chainableMethods) {
-    chainablePromise[method] = function(...args) {
+    chainablePromise[method] = function (...args) {
       // Return a promise that waits for the element, then calls the method
-      return promise.then(element => element[method](...args));
+      return promise.then((element) => element[method](...args));
     };
   }
-  
+
   // Add getters for element properties (these return promises)
-  Object.defineProperty(chainablePromise, 'x', {
-    get() { return promise.then(el => el.x); }
+  Object.defineProperty(chainablePromise, "x", {
+    get() {
+      return promise.then((el) => el.x);
+    },
   });
-  Object.defineProperty(chainablePromise, 'y', {
-    get() { return promise.then(el => el.y); }
+  Object.defineProperty(chainablePromise, "y", {
+    get() {
+      return promise.then((el) => el.y);
+    },
   });
-  Object.defineProperty(chainablePromise, 'centerX', {
-    get() { return promise.then(el => el.centerX); }
+  Object.defineProperty(chainablePromise, "centerX", {
+    get() {
+      return promise.then((el) => el.centerX);
+    },
   });
-  Object.defineProperty(chainablePromise, 'centerY', {
-    get() { return promise.then(el => el.centerY); }
+  Object.defineProperty(chainablePromise, "centerY", {
+    get() {
+      return promise.then((el) => el.centerY);
+    },
   });
-  
+
   // Add found() method
-  chainablePromise.found = function() {
-    return promise.then(el => el.found());
+  chainablePromise.found = function () {
+    return promise.then((el) => el.found());
   };
-  
+
   // Add getCoordinates() method
-  chainablePromise.getCoordinates = function() {
-    return promise.then(el => el.getCoordinates());
+  chainablePromise.getCoordinates = function () {
+    return promise.then((el) => el.getCoordinates());
   };
-  
+
   // Add getResponse() method
-  chainablePromise.getResponse = function() {
-    return promise.then(el => el.getResponse());
+  chainablePromise.getResponse = function () {
+    return promise.then((el) => el.getResponse());
   };
-  
+
   return chainablePromise;
 }
 
@@ -1256,7 +1314,8 @@ class TestDriverSDK {
     this.sandboxInstance = options.sandboxInstance || null;
 
     // Store reconnect preference from options
-    this.reconnect = options.reconnect !== undefined ? options.reconnect : false;
+    this.reconnect =
+      options.reconnect !== undefined ? options.reconnect : false;
 
     // Store dashcam preference (default: true)
     this.dashcamEnabled = options.dashcam !== false;
@@ -1281,7 +1340,7 @@ class TestDriverSDK {
     } else {
       // Cache enabled by default when cacheKey is provided
       this.cacheThresholds = {
-        find: options.cacheThreshold?.find ?? 0.01,  // Default: 1% threshold
+        find: options.cacheThreshold?.find ?? 0.01, // Default: 1% threshold
         findAll: options.cacheThreshold?.findAll ?? 0.01,
       };
     }
@@ -1293,14 +1352,16 @@ class TestDriverSDK {
     // The `redraw` option takes precedence and matches the per-command API
     if (options.redraw !== undefined) {
       // New unified API: redraw object (matches per-command options)
-      this.redrawOptions = typeof options.redraw === 'object' 
-        ? options.redraw 
-        : { enabled: options.redraw }; // Support redraw: false as shorthand
+      this.redrawOptions =
+        typeof options.redraw === "object"
+          ? options.redraw
+          : { enabled: options.redraw }; // Support redraw: false as shorthand
     } else if (options.redrawThreshold !== undefined) {
       // Legacy API: redrawThreshold number or object
-      this.redrawOptions = typeof options.redrawThreshold === 'object'
-        ? options.redrawThreshold
-        : { diffThreshold: options.redrawThreshold };
+      this.redrawOptions =
+        typeof options.redrawThreshold === "object"
+          ? options.redrawThreshold
+          : { diffThreshold: options.redrawThreshold };
     } else {
       // Default: enabled (as of v7.2)
       this.redrawOptions = { enabled: true };
@@ -1354,7 +1415,7 @@ class TestDriverSDK {
       await this.__connectionPromise;
     }
     if (!this.connected) {
-      throw new Error('Not connected to sandbox. Call connect() first.');
+      throw new Error("Not connected to sandbox. Call connect() first.");
     }
   }
 
@@ -1411,18 +1472,18 @@ class TestDriverSDK {
    * @private
    */
   async _getDashcamChromeExtensionPath() {
-    if (this.os !== 'windows') {
-      return '/usr/lib/node_modules/dashcam-chrome/build';
+    if (this.os !== "windows") {
+      return "/usr/lib/node_modules/dashcam-chrome/build";
     }
 
     // dashcam-chrome is preinstalled on Windows at C:\Program Files\nodejs\node_modules\dashcam-chrome\build
     // Use the actual long path - we'll handle quoting in the chrome launch
-    return 'C:\\PROGRA~1\\nodejs\\node_modules\\dashcam-chrome\\build';
+    return "C:\\PROGRA~1\\nodejs\\node_modules\\dashcam-chrome\\build";
   }
 
   _createProvisionAPI() {
     const self = this;
-    
+
     const provisionMethods = {
       /**
        * Launch Chrome browser
@@ -1434,7 +1495,7 @@ class TestDriverSDK {
        */
       chrome: async (options = {}) => {
         const {
-          url = 'http://testdriver-sandbox.vercel.app/',
+          url = "http://testdriver-sandbox.vercel.app/",
           maximized = true,
           guest = false,
         } = options;
@@ -1442,69 +1503,84 @@ class TestDriverSDK {
         // If dashcam is available, add web logs for all websites
         // Note: File log and dashcam.start() are handled by the connection promise in hooks.mjs
         if (this._dashcam) {
-          await this._dashcam.addWebLog('**', 'Web Logs');
+          await this._dashcam.addWebLog("**", "Web Logs");
         }
 
         // Set up Chrome profile with preferences
-        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
-        const userDataDir = this.os === 'windows' 
-          ? 'C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Chrome'
-          : '/tmp/testdriver-chrome-profile';
-        
+        const shell = this.os === "windows" ? "pwsh" : "sh";
+        const userDataDir =
+          this.os === "windows"
+            ? "C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Chrome"
+            : "/tmp/testdriver-chrome-profile";
+
         // Create user data directory and Default profile directory
-        const defaultProfileDir = this.os === 'windows'
-          ? `${userDataDir}\\Default`
-          : `${userDataDir}/Default`;
-        
-        const createDirCmd = this.os === 'windows'
-          ? `New-Item -ItemType Directory -Path "${defaultProfileDir}" -Force | Out-Null`
-          : `mkdir -p "${defaultProfileDir}"`;
-        
+        const defaultProfileDir =
+          this.os === "windows"
+            ? `${userDataDir}\\Default`
+            : `${userDataDir}/Default`;
+
+        const createDirCmd =
+          this.os === "windows"
+            ? `New-Item -ItemType Directory -Path "${defaultProfileDir}" -Force | Out-Null`
+            : `mkdir -p "${defaultProfileDir}"`;
+
         await this.exec(shell, createDirCmd, 60000, true);
-        
+
         // Write Chrome preferences
         const chromePrefs = {
           credentials_enable_service: false,
           profile: {
             password_manager_enabled: false,
-            default_content_setting_values: {}
+            default_content_setting_values: {},
           },
           signin: {
-            allowed: false
+            allowed: false,
           },
           sync: {
             requested: false,
             first_setup_complete: true,
-            sync_all_os_types: false
+            sync_all_os_types: false,
           },
           autofill: {
-            enabled: false
+            enabled: false,
           },
           local_state: {
             browser: {
-              has_seen_welcome_page: true
-            }
-          }
+              has_seen_welcome_page: true,
+            },
+          },
         };
-        
-        const prefsPath = this.os === 'windows'
-          ? `${defaultProfileDir}\\Preferences`
-          : `${defaultProfileDir}/Preferences`;
-        
+
+        const prefsPath =
+          this.os === "windows"
+            ? `${defaultProfileDir}\\Preferences`
+            : `${defaultProfileDir}/Preferences`;
+
         const prefsJson = JSON.stringify(chromePrefs, null, 2);
-        const writePrefCmd = this.os === 'windows'
-          // Use compact JSON and [System.IO.File]::WriteAllText to avoid Set-Content hanging issues
-          ? `[System.IO.File]::WriteAllText("${prefsPath}", '${JSON.stringify(chromePrefs).replace(/'/g, "''")}')`
-          : `cat > "${prefsPath}" << 'EOF'\n${prefsJson}\nEOF`;
-        
+        const writePrefCmd =
+          this.os === "windows"
+            ? // Use compact JSON and [System.IO.File]::WriteAllText to avoid Set-Content hanging issues
+              `[System.IO.File]::WriteAllText("${prefsPath}", '${JSON.stringify(chromePrefs).replace(/'/g, "''")}')`
+            : `cat > "${prefsPath}" << 'EOF'\n${prefsJson}\nEOF`;
+
         await this.exec(shell, writePrefCmd, 60000, true);
 
         // Build Chrome launch command
         const chromeArgs = [];
-        if (maximized) chromeArgs.push('--start-maximized');
-        if (guest) chromeArgs.push('--guest');
-        chromeArgs.push('--disable-fre', '--no-default-browser-check', '--no-first-run', '--no-experiments', '--disable-infobars', `--user-data-dir=${userDataDir}`);
-        
+        if (maximized) chromeArgs.push("--start-maximized");
+        if (guest) chromeArgs.push("--guest");
+        chromeArgs.push(
+          "--disable-fre",
+          "--no-default-browser-check",
+          "--no-first-run",
+          "--no-experiments",
+          "--disable-infobars",
+          `--user-data-dir=${userDataDir}`,
+        );
+
+        // Add remote debugging port for captcha solving support
+        chromeArgs.push("--remote-debugging-port=9222");
+
         // Add dashcam-chrome extension
         const dashcamChromePath = await this._getDashcamChromeExtensionPath();
         if (dashcamChromePath) {
@@ -1512,44 +1588,47 @@ class TestDriverSDK {
         }
 
         // Launch Chrome
-        
-        if (this.os === 'windows') {
-          const argsString = chromeArgs.map(arg => `"${arg}"`).join(', ');
+
+        if (this.os === "windows") {
+          const argsString = chromeArgs.map((arg) => `"${arg}"`).join(", ");
           await this.exec(
             shell,
             `Start-Process "C:\\ChromeForTesting\\chrome-win64\\chrome.exe" -ArgumentList ${argsString}, "${url}"`,
-            30000
+            30000,
           );
         } else {
-          const argsString = chromeArgs.join(' ');
+          const argsString = chromeArgs.join(" ");
           await this.exec(
             shell,
             `chrome-for-testing ${argsString} "${url}" >/dev/null 2>&1 &`,
-            30000
+            30000,
           );
         }
 
         // Wait for Chrome to be ready
-        await this.focusApplication('Google Chrome');
+        await this.focusApplication("Google Chrome");
 
         // Wait for URL to load
         try {
           const urlObj = new URL(url);
           const domain = urlObj.hostname;
-                    
+
           for (let attempt = 0; attempt < 30; attempt++) {
             const result = await this.find(`${domain}`);
 
             if (result.found()) {
               break;
             } else {
-              await new Promise(resolve => setTimeout(resolve, 1000));
+              await new Promise((resolve) => setTimeout(resolve, 1000));
             }
           }
-          
-          await this.focusApplication('Google Chrome');
+
+          await this.focusApplication("Google Chrome");
         } catch (e) {
-          console.warn(`[provision.chrome] ⚠️  Could not parse URL "${url}":`, e.message);
+          console.warn(
+            `[provision.chrome] ⚠️  Could not parse URL "${url}":`,
+            e.message,
+          );
         }
       },
 
@@ -1566,7 +1645,7 @@ class TestDriverSDK {
        * await testdriver.provision.chromeExtension({
        *   extensionPath: '/tmp/extension'
        * });
-       * 
+       *
        * @example
        * // Load extension by Chrome Web Store ID
        * await testdriver.provision.chromeExtension({
@@ -1581,55 +1660,62 @@ class TestDriverSDK {
         } = options;
 
         if (!providedExtensionPath && !extensionId) {
-          throw new Error('[provision.chromeExtension] Either extensionPath or extensionId is required');
+          throw new Error(
+            "[provision.chromeExtension] Either extensionPath or extensionId is required",
+          );
         }
 
         let extensionPath = providedExtensionPath;
-        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+        const shell = this.os === "windows" ? "pwsh" : "sh";
 
         // If extensionId is provided, download and extract the extension from Chrome Web Store
         if (extensionId && !extensionPath) {
-          console.log(`[provision.chromeExtension] Downloading extension ${extensionId} from Chrome Web Store...`);
-          
-          const extensionDir = this.os === 'windows'
-            ? `C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Extensions\\${extensionId}`
-            : `/tmp/testdriver-extensions/${extensionId}`;
-          
+          console.log(
+            `[provision.chromeExtension] Downloading extension ${extensionId} from Chrome Web Store...`,
+          );
+
+          const extensionDir =
+            this.os === "windows"
+              ? `C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Extensions\\${extensionId}`
+              : `/tmp/testdriver-extensions/${extensionId}`;
+
           // Create extension directory
-          const mkdirCmd = this.os === 'windows'
-            ? `New-Item -ItemType Directory -Path "${extensionDir}" -Force | Out-Null`
-            : `mkdir -p "${extensionDir}"`;
+          const mkdirCmd =
+            this.os === "windows"
+              ? `New-Item -ItemType Directory -Path "${extensionDir}" -Force | Out-Null`
+              : `mkdir -p "${extensionDir}"`;
           await this.exec(shell, mkdirCmd, 60000, true);
-          
+
           // Download CRX from Chrome Web Store
           // The CRX download URL format for Chrome Web Store
           const crxUrl = `https://clients2.google.com/service/update2/crx?response=redirect&prodversion=131.0.0.0&acceptformat=crx2,crx3&x=id%3D${extensionId}%26installsource%3Dondemand%26uc`;
-          const crxPath = this.os === 'windows'
-            ? `${extensionDir}\\extension.crx`
-            : `${extensionDir}/extension.crx`;
-          
-          if (this.os === 'windows') {
+          const crxPath =
+            this.os === "windows"
+              ? `${extensionDir}\\extension.crx`
+              : `${extensionDir}/extension.crx`;
+
+          if (this.os === "windows") {
             await this.exec(
-              'pwsh',
+              "pwsh",
               `Invoke-WebRequest -Uri "${crxUrl}" -OutFile "${crxPath}"`,
               60000,
-              true
+              true,
             );
           } else {
             await this.exec(
-              'sh',
+              "sh",
               `curl -L -o "${crxPath}" "${crxUrl}"`,
               60000,
-              true
+              true,
             );
           }
-          
+
           // Extract the CRX file (CRX is a ZIP with a header)
           // Skip the CRX header and extract as ZIP
-          if (this.os === 'windows') {
+          if (this.os === "windows") {
             // PowerShell: Read CRX, skip header, extract ZIP
             await this.exec(
-              'pwsh',
+              "pwsh",
               `
 $crxBytes = [System.IO.File]::ReadAllBytes("${crxPath}")
 # CRX3 header: 4 bytes magic + 4 bytes version + 4 bytes header length + header
@@ -1647,13 +1733,13 @@ $zipPath = "${extensionDir}\\extension.zip"
 Expand-Archive -Path $zipPath -DestinationPath "${extensionDir}\\unpacked" -Force
               `,
               30000,
-              true
+              true,
             );
             extensionPath = `${extensionDir}\\unpacked`;
           } else {
             // Linux: Use unzip with offset or python to extract
             await this.exec(
-              'sh',
+              "sh",
               `
 cd "${extensionDir}"
 # Extract CRX (skip header and unzip)
@@ -1686,120 +1772,140 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 "
               `,
               30000,
-              true
+              true,
             );
             extensionPath = `${extensionDir}/unpacked`;
           }
-          
-          console.log(`[provision.chromeExtension] Extension ${extensionId} extracted to ${extensionPath}`);
+
+          console.log(
+            `[provision.chromeExtension] Extension ${extensionId} extracted to ${extensionPath}`,
+          );
         }
 
         // If dashcam is available, add web logs for all websites
         // Note: File log and dashcam.start() are handled by the connection promise in hooks.mjs
         if (this._dashcam) {
-          await this._dashcam.addWebLog('**', 'Web Logs');
+          await this._dashcam.addWebLog("**", "Web Logs");
         }
 
         // Set up Chrome profile with preferences
-        const userDataDir = this.os === 'windows' 
-          ? 'C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Chrome'
-          : '/tmp/testdriver-chrome-profile';
-        
+        const userDataDir =
+          this.os === "windows"
+            ? "C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Chrome"
+            : "/tmp/testdriver-chrome-profile";
+
         // Create user data directory and Default profile directory
-        const defaultProfileDir = this.os === 'windows'
-          ? `${userDataDir}\\Default`
-          : `${userDataDir}/Default`;
-        
-        const createDirCmd = this.os === 'windows'
-          ? `New-Item -ItemType Directory -Path "${defaultProfileDir}" -Force | Out-Null`
-          : `mkdir -p "${defaultProfileDir}"`;
-        
+        const defaultProfileDir =
+          this.os === "windows"
+            ? `${userDataDir}\\Default`
+            : `${userDataDir}/Default`;
+
+        const createDirCmd =
+          this.os === "windows"
+            ? `New-Item -ItemType Directory -Path "${defaultProfileDir}" -Force | Out-Null`
+            : `mkdir -p "${defaultProfileDir}"`;
+
         await this.exec(shell, createDirCmd, 60000, true);
-        
+
         // Write Chrome preferences
         const chromePrefs = {
           credentials_enable_service: false,
           profile: {
             password_manager_enabled: false,
-            default_content_setting_values: {}
+            default_content_setting_values: {},
           },
           signin: {
-            allowed: false
+            allowed: false,
           },
           sync: {
             requested: false,
             first_setup_complete: true,
-            sync_all_os_types: false
+            sync_all_os_types: false,
           },
           autofill: {
-            enabled: false
+            enabled: false,
           },
           local_state: {
             browser: {
-              has_seen_welcome_page: true
-            }
-          }
+              has_seen_welcome_page: true,
+            },
+          },
         };
-        
-        const prefsPath = this.os === 'windows'
-          ? `${defaultProfileDir}\\Preferences`
-          : `${defaultProfileDir}/Preferences`;
-        
+
+        const prefsPath =
+          this.os === "windows"
+            ? `${defaultProfileDir}\\Preferences`
+            : `${defaultProfileDir}/Preferences`;
+
         const prefsJson = JSON.stringify(chromePrefs, null, 2);
-        const writePrefCmd = this.os === 'windows'
-          // Use compact JSON and [System.IO.File]::WriteAllText to avoid Set-Content hanging issues
-          ? `[System.IO.File]::WriteAllText("${prefsPath}", '${JSON.stringify(chromePrefs).replace(/'/g, "''")}')`
-          : `cat > "${prefsPath}" << 'EOF'\n${prefsJson}\nEOF`;
-        
+        const writePrefCmd =
+          this.os === "windows"
+            ? // Use compact JSON and [System.IO.File]::WriteAllText to avoid Set-Content hanging issues
+              `[System.IO.File]::WriteAllText("${prefsPath}", '${JSON.stringify(chromePrefs).replace(/'/g, "''")}')`
+            : `cat > "${prefsPath}" << 'EOF'\n${prefsJson}\nEOF`;
+
         await this.exec(shell, writePrefCmd, 60000, true);
 
         // Build Chrome launch command
         const chromeArgs = [];
-        if (maximized) chromeArgs.push('--start-maximized');
-        chromeArgs.push('--disable-fre', '--no-default-browser-check', '--no-first-run', '--no-experiments', '--disable-infobars', '--disable-features=ChromeLabs', `--user-data-dir=${userDataDir}`);
-        
+        if (maximized) chromeArgs.push("--start-maximized");
+        chromeArgs.push(
+          "--disable-fre",
+          "--no-default-browser-check",
+          "--no-first-run",
+          "--no-experiments",
+          "--disable-infobars",
+          "--disable-features=ChromeLabs",
+          `--user-data-dir=${userDataDir}`,
+        );
+
+        // Add remote debugging port for captcha solving support
+        chromeArgs.push("--remote-debugging-port=9222");
+
         // Add user extension and dashcam-chrome extension
         const dashcamChromePath = await this._getDashcamChromeExtensionPath();
         if (dashcamChromePath) {
           // Load both user extension and dashcam-chrome for web log capture
-          chromeArgs.push(`--load-extension=${extensionPath},${dashcamChromePath}`);
+          chromeArgs.push(
+            `--load-extension=${extensionPath},${dashcamChromePath}`,
+          );
         } else {
           // If dashcam-chrome unavailable, just load user extension
           chromeArgs.push(`--load-extension=${extensionPath}`);
         }
 
         // Launch Chrome (opens to New Tab by default)
-        if (this.os === 'windows') {
-          const argsString = chromeArgs.map(arg => `"${arg}"`).join(', ');
+        if (this.os === "windows") {
+          const argsString = chromeArgs.map((arg) => `"${arg}"`).join(", ");
           await this.exec(
             shell,
             `Start-Process "C:\\ChromeForTesting\\chrome-win64\\chrome.exe" -ArgumentList ${argsString}`,
-            30000
+            30000,
           );
         } else {
-          const argsString = chromeArgs.join(' ');
+          const argsString = chromeArgs.join(" ");
           await this.exec(
             shell,
             `chrome-for-testing ${argsString} >/dev/null 2>&1 &`,
-            30000
+            30000,
           );
         }
 
         // Wait for Chrome to be ready
-        await this.focusApplication('Google Chrome');
+        await this.focusApplication("Google Chrome");
 
         // Wait for New Tab to appear
         for (let attempt = 0; attempt < 30; attempt++) {
-          const result = await this.find('New Tab');
+          const result = await this.find("New Tab");
 
           if (result.found()) {
             break;
           } else {
-            await new Promise(resolve => setTimeout(resolve, 1000));
+            await new Promise((resolve) => setTimeout(resolve, 1000));
           }
         }
-        
-        await this.focusApplication('Google Chrome');
+
+        await this.focusApplication("Google Chrome");
       },
 
       /**
@@ -1810,17 +1916,14 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        * @returns {Promise<void>}
        */
       vscode: async (options = {}) => {
-        const {
-          workspace = null,
-          extensions = [],
-        } = options;
+        const { workspace = null, extensions = [] } = options;
 
-        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+        const shell = this.os === "windows" ? "pwsh" : "sh";
 
         // If dashcam is available, add web logs for all websites
         // Note: File log and dashcam.start() are handled by the connection promise in hooks.mjs
         if (this._dashcam) {
-          await this._dashcam.addWebLog('**', 'Web Logs');
+          await this._dashcam.addWebLog("**", "Web Logs");
         }
 
         // Install extensions if provided
@@ -1830,33 +1933,35 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
             shell,
             `code --install-extension ${extension} --force`,
             120000,
-            true
+            true,
+          );
+          console.log(
+            `[provision.vscode] ✅ Extension installed: ${extension}`,
           );
-          console.log(`[provision.vscode] ✅ Extension installed: ${extension}`);
         }
 
         // Launch VS Code
-        const workspaceArg = workspace ? `"${workspace}"` : '';
-        
-        if (this.os === 'windows') {
+        const workspaceArg = workspace ? `"${workspace}"` : "";
+
+        if (this.os === "windows") {
           await this.exec(
             shell,
             `Start-Process code -ArgumentList ${workspaceArg}`,
-            30000
+            30000,
           );
         } else {
           await this.exec(
             shell,
             `code ${workspaceArg} >/dev/null 2>&1 &`,
-            30000
+            30000,
           );
         }
 
         // Wait for VS Code to start up
-        await new Promise(resolve => setTimeout(resolve, 3000));
+        await new Promise((resolve) => setTimeout(resolve, 3000));
 
         // Wait for VS Code to be ready
-        await this.focusApplication('Visual Studio Code');
+        await this.focusApplication("Visual Studio Code");
       },
 
       /**
@@ -1873,7 +1978,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        *   url: 'https://example.com/app.deb',
        *   appName: 'MyApp'
        * });
-       * 
+       *
        * @example
        * // Download and run custom commands
        * const filePath = await testdriver.provision.installer({
@@ -1883,39 +1988,33 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        * await testdriver.exec('sh', `chmod +x "${filePath}" && "${filePath}" &`, 10000);
        */
       installer: async (options = {}) => {
-        const {
-          url,
-          filename,
-          appName,
-          launch = true,
-        } = options;
+        const { url, filename, appName, launch = true } = options;
 
         if (!url) {
-          throw new Error('[provision.installer] url is required');
+          throw new Error("[provision.installer] url is required");
         }
 
-        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+        const shell = this.os === "windows" ? "pwsh" : "sh";
 
         // If dashcam is available, add web logs for all websites
         // Note: File log and dashcam.start() are handled by the connection promise in hooks.mjs
         if (this._dashcam) {
-          await this._dashcam.addWebLog('**', 'Web Logs');
+          await this._dashcam.addWebLog("**", "Web Logs");
         }
 
         // Determine download directory
-        const downloadDir = this.os === 'windows' 
-          ? 'C:\\Users\\testdriver\\Downloads'
-          : '/tmp';
+        const downloadDir =
+          this.os === "windows" ? "C:\\Users\\testdriver\\Downloads" : "/tmp";
 
         console.log(`[provision.installer] Downloading ${url}...`);
 
         let actualFilePath;
 
         // Download the file and get the actual filename (handles redirects)
-        if (this.os === 'windows') {
+        if (this.os === "windows") {
           // Simple approach: download first, then get the actual filename from the response
           const tempFile = `${downloadDir}\\installer_temp_${Date.now()}`;
-          
+
           const downloadScript = `
             $ProgressPreference = 'SilentlyContinue'
             $response = Invoke-WebRequest -Uri "${url}" -OutFile "${tempFile}" -PassThru -UseBasicParsing
@@ -1942,12 +2041,12 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
             Move-Item -Path "${tempFile}" -Destination $finalPath -Force
             Write-Output $finalPath
           `;
-          
+
           const result = await this.exec(shell, downloadScript, 300000, true);
           actualFilePath = result ? result.trim() : null;
-          
+
           if (!actualFilePath) {
-            throw new Error('[provision.installer] Failed to download file');
+            throw new Error("[provision.installer] Failed to download file");
           }
         } else {
           // Use curl with options to get the final filename
@@ -1956,21 +2055,21 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
             cd "${downloadDir}"
             curl -L -J -O -w "%{filename_effective}" "${url}" 2>/dev/null || echo "${tempMarker}"
           `;
-          
+
           const result = await this.exec(shell, downloadScript, 300000, true);
           const downloadedFile = result ? result.trim() : null;
-          
+
           if (downloadedFile && downloadedFile !== tempMarker) {
             actualFilePath = `${downloadDir}/${downloadedFile}`;
           } else {
             // Fallback: use curl without -J and specify output file
-            const fallbackFilename = filename || 'installer';
+            const fallbackFilename = filename || "installer";
             actualFilePath = `${downloadDir}/${fallbackFilename}`;
             await this.exec(
               shell,
               `curl -L -o "${actualFilePath}" "${url}"`,
               300000,
-              true
+              true,
             );
           }
         }
@@ -1978,30 +2077,30 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         console.log(`[provision.installer] ✅ Downloaded to ${actualFilePath}`);
 
         // Auto-detect install command based on file extension (use actualFilePath for extension detection)
-        const actualFilename = actualFilePath.split(/[/\\]/).pop() || '';
-        const ext = actualFilename.split('.').pop()?.toLowerCase();
+        const actualFilename = actualFilePath.split(/[/\\]/).pop() || "";
+        const ext = actualFilename.split(".").pop()?.toLowerCase();
         let installCommand = null;
-        
-        if (this.os === 'windows') {
-          if (ext === 'msi') {
+
+        if (this.os === "windows") {
+          if (ext === "msi") {
             installCommand = `Start-Process msiexec -ArgumentList '/i', '"${actualFilePath}"', '/quiet', '/norestart' -Wait`;
-          } else if (ext === 'exe') {
+          } else if (ext === "exe") {
             installCommand = `Start-Process "${actualFilePath}" -ArgumentList '/S' -Wait`;
           }
-        } else if (this.os === 'linux') {
-          if (ext === 'deb') {
+        } else if (this.os === "linux") {
+          if (ext === "deb") {
             installCommand = `sudo dpkg -i "${actualFilePath}" && sudo apt-get install -f -y`;
-          } else if (ext === 'rpm') {
+          } else if (ext === "rpm") {
             installCommand = `sudo rpm -i "${actualFilePath}"`;
-          } else if (ext === 'appimage') {
+          } else if (ext === "appimage") {
             installCommand = `chmod +x "${actualFilePath}"`;
-          } else if (ext === 'sh') {
+          } else if (ext === "sh") {
             installCommand = `chmod +x "${actualFilePath}" && "${actualFilePath}"`;
           }
-        } else if (this.os === 'darwin') {
-          if (ext === 'dmg') {
+        } else if (this.os === "darwin") {
+          if (ext === "dmg") {
             installCommand = `hdiutil attach "${actualFilePath}" -mountpoint /Volumes/installer && cp -R /Volumes/installer/*.app /Applications/ && hdiutil detach /Volumes/installer`;
-          } else if (ext === 'pkg') {
+          } else if (ext === "pkg") {
             installCommand = `sudo installer -pkg "${actualFilePath}" -target /`;
           }
         }
@@ -2014,7 +2113,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
         // Launch and focus the app if appName is provided and launch is true
         if (appName && launch) {
-          await new Promise(resolve => setTimeout(resolve, 2000));
+          await new Promise((resolve) => setTimeout(resolve, 2000));
           await this.focusApplication(appName);
         }
 
@@ -2030,36 +2129,36 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        */
       electron: async (options = {}) => {
         const { appPath, args = [] } = options;
-        
+
         if (!appPath) {
-          throw new Error('provision.electron requires appPath option');
+          throw new Error("provision.electron requires appPath option");
         }
 
-        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+        const shell = this.os === "windows" ? "pwsh" : "sh";
 
         // If dashcam is available, add web logs for all websites
         // Note: File log and dashcam.start() are handled by the connection promise in hooks.mjs
         if (this._dashcam) {
-          await this._dashcam.addWebLog('**', 'Web Logs');
+          await this._dashcam.addWebLog("**", "Web Logs");
         }
 
-        const argsString = args.join(' ');
-        
-        if (this.os === 'windows') {
+        const argsString = args.join(" ");
+
+        if (this.os === "windows") {
           await this.exec(
             shell,
             `Start-Process electron -ArgumentList "${appPath}", ${argsString}`,
-            30000
+            30000,
           );
         } else {
           await this.exec(
             shell,
             `electron "${appPath}" ${argsString} >/dev/null 2>&1 &`,
-            30000
+            30000,
           );
         }
 
-        await this.focusApplication('Electron');
+        await this.focusApplication("Electron");
       },
     };
 
@@ -2067,19 +2166,204 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     return new Proxy(provisionMethods, {
       get(target, prop) {
         const method = target[prop];
-        if (typeof method === 'function') {
+        if (typeof method === "function") {
           return async (...args) => {
             // Skip provisioning if reconnecting to existing sandbox
             if (self.reconnect) {
-              console.log(`[provision.${prop}] Skipping provisioning (reconnect mode)`);
+              console.log(
+                `[provision.${prop}] Skipping provisioning (reconnect mode)`,
+              );
               return;
             }
             return method(...args);
           };
         }
         return method;
-      }
+      },
+    });
+  }
+
+  /**
+   * Solve a captcha on the current page using 2captcha service
+   * Requires Chrome to be launched with remote debugging (--remote-debugging-port=9222)
+   *
+   * @param {Object} options - Captcha solving options
+   * @param {string} options.apiKey - 2captcha API key (required)
+   * @param {string} [options.sitekey] - Captcha sitekey (auto-detected if not provided)
+   * @param {string} [options.type='recaptcha_v3'] - Captcha type: 'recaptcha_v2', 'recaptcha_v3', 'hcaptcha', 'turnstile'
+   * @param {string} [options.action='verify'] - Action parameter for reCAPTCHA v3
+   * @param {boolean} [options.autoSubmit=true] - Automatically click submit button after solving
+   * @param {number} [options.pollInterval=5000] - Polling interval in ms for 2captcha
+   * @param {number} [options.timeout=120000] - Timeout in ms for solving
+   * @returns {Promise<{success: boolean, message: string, token?: string}>}
+   *
+   * @example
+   * // Auto-detect and solve captcha
+   * await testdriver.captcha({
+   *   apiKey: 'your-2captcha-api-key'
+   * });
+   *
+   * @example
+   * // Solve with known sitekey
+   * await testdriver.captcha({
+   *   apiKey: 'your-2captcha-api-key',
+   *   sitekey: '6LfB5_IbAAAAAMCtsjEHEHKqcB9iQocwwxTiihJu',
+   *   action: 'demo_action'
+   * });
+   */
+  async captcha(options = {}) {
+    const {
+      apiKey,
+      sitekey,
+      type = "recaptcha_v3",
+      action = "verify",
+      autoSubmit = true,
+      pollInterval = 5000,
+      timeout = 120000,
+    } = options;
+
+    if (!apiKey) {
+      throw new Error(
+        "[captcha] apiKey is required. Get your API key at https://2captcha.com",
+      );
+    }
+
+    const shell = this.os === "windows" ? "pwsh" : "sh";
+    const isWindows = this.os === "windows";
+
+    // Paths for config and solver script
+    const configPath = isWindows
+      ? "C:\\Users\\testdriver\\AppData\\Local\\Temp\\td-captcha-config.json"
+      : "/tmp/td-captcha-config.json";
+    const solverPath = isWindows
+      ? "C:\\Users\\testdriver\\AppData\\Local\\Temp\\td-captcha-solver.js"
+      : "/tmp/td-captcha-solver.js";
+
+    // Ensure chrome-remote-interface is installed
+    if (isWindows) {
+      await this.exec(
+        shell,
+        "npm install -g chrome-remote-interface 2>$null; $true",
+        60000,
+        true,
+      );
+    } else {
+      await this.exec(
+        shell,
+        "sudo npm install -g chrome-remote-interface 2>/dev/null || npm install -g chrome-remote-interface",
+        60000,
+        true,
+      );
+    }
+
+    // Build config JSON for the solver
+    const config = JSON.stringify({
+      apiKey,
+      sitekey: sitekey || null,
+      type,
+      action,
+      autoSubmit,
+      pollInterval,
+      timeout,
     });
+
+    // Write config file
+    if (isWindows) {
+      // Use PowerShell's Set-Content with escaped JSON
+      const escapedConfig = config.replace(/'/g, "''");
+      await this.exec(
+        shell,
+        `[System.IO.File]::WriteAllText('${configPath}', '${escapedConfig}')`,
+        5000,
+        true,
+      );
+    } else {
+      // Use heredoc for Linux
+      await this.exec(
+        shell,
+        `cat > ${configPath} << 'CONFIGEOF'
+${config}
+CONFIGEOF`,
+        5000,
+        true,
+      );
+    }
+
+    // Load the solver script from file (avoids escaping issues with string concatenation)
+    const solverScriptPath = path.join(
+      __dirname,
+      "lib",
+      "captcha",
+      "solver.js",
+    );
+    const solverScript = fs.readFileSync(solverScriptPath, "utf8");
+
+    // Write the solver script to sandbox
+    if (isWindows) {
+      // For Windows, write the script using base64 encoding to avoid escaping issues
+      const base64Script = Buffer.from(solverScript).toString("base64");
+      await this.exec(
+        shell,
+        `[System.IO.File]::WriteAllBytes('${solverPath}', [System.Convert]::FromBase64String('${base64Script}'))`,
+        10000,
+        true,
+      );
+    } else {
+      // Use heredoc for Linux
+      await this.exec(
+        shell,
+        `cat > ${solverPath} << 'CAPTCHA_SOLVER_EOF'
+${solverScript}
+CAPTCHA_SOLVER_EOF`,
+        10000,
+        true,
+      );
+    }
+
+    // Run the solver (capture output even on failure)
+    let result;
+    try {
+      if (isWindows) {
+        // Set environment variable and run node on Windows
+        result = await this.exec(
+          shell,
+          `$env:NODE_PATH = (npm root -g).Trim(); $env:TD_CAPTCHA_CONFIG_PATH='${configPath}'; node '${solverPath}' 2>&1 | Out-String; Write-Output "EXIT_CODE:$LASTEXITCODE"`,
+          timeout + 30000,
+        );
+      } else {
+        result = await this.exec(
+          shell,
+          `NODE_PATH=/usr/lib/node_modules node ${solverPath} 2>&1; echo "EXIT_CODE:$?"`,
+          timeout + 30000,
+        );
+      }
+    } catch (err) {
+      // If exec throws, try to get output from the error
+      result = err.message || err.toString();
+      if (err.responseData && err.responseData.stdout) {
+        result = err.responseData.stdout;
+      }
+    }
+
+    const tokenMatch = result.match(/TOKEN:\s*(\S+)/);
+    const success = result.includes('"success":true');
+    const hasError = result.includes("ERROR:");
+
+    if (hasError && !success) {
+      const errorMatch = result.match(/ERROR:\s*(.+)/);
+      throw new Error(
+        `[captcha] ${errorMatch ? errorMatch[1] : "Unknown error"}\nOutput: ${result}`,
+      );
+    }
+
+    return {
+      success,
+      message: success
+        ? "Captcha solved successfully"
+        : "Captcha solving failed",
+      token: tokenMatch ? tokenMatch[1] : null,
+      output: result,
+    };
   }
 
   /**
@@ -2117,8 +2401,16 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
     // Clean up screenshots folder for this test file before running
     if (this.testFile) {
-      const testFileName = path.basename(this.testFile, path.extname(this.testFile));
-      const screenshotsDir = path.join(process.cwd(), ".testdriver", "screenshots", testFileName);
+      const testFileName = path.basename(
+        this.testFile,
+        path.extname(this.testFile),
+      );
+      const screenshotsDir = path.join(
+        process.cwd(),
+        ".testdriver",
+        "screenshots",
+        testFileName,
+      );
       if (fs.existsSync(screenshotsDir)) {
         fs.rmSync(screenshotsDir, { recursive: true, force: true });
       }
@@ -2149,23 +2441,24 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
     // Handle reconnect option - use last sandbox file
     // Check both connectOptions and constructor options
-    const shouldReconnect = connectOptions.reconnect !== undefined 
-      ? connectOptions.reconnect 
-      : this.reconnect;
-    
+    const shouldReconnect =
+      connectOptions.reconnect !== undefined
+        ? connectOptions.reconnect
+        : this.reconnect;
+
     // Skip reconnect if IP is supplied - directly connect to the provided IP
     const hasIp = Boolean(connectOptions.ip || this.ip);
-    
+
     if (shouldReconnect && !hasIp) {
       const lastSandbox = this.agent.getLastSandboxId();
       if (!lastSandbox || !lastSandbox.sandboxId) {
         throw new Error(
-          "Cannot reconnect: No previous sandbox found. Run a test first to create a sandbox, or remove the reconnect option."
+          "Cannot reconnect: No previous sandbox found. Run a test first to create a sandbox, or remove the reconnect option.",
         );
       }
       this.agent.sandboxId = lastSandbox.sandboxId;
       buildEnvOptions.new = false;
-      
+
       // Use OS from last sandbox if not explicitly specified
       if (!connectOptions.os && lastSandbox.os) {
         this.agent.sandboxOs = lastSandbox.os;
@@ -2226,7 +2519,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     if (this.agent.sandboxOs) {
       this.os = this.agent.sandboxOs;
     }
-    
+
     // Also ensure sandbox.os is set for consistency
     if (this.agent.sandbox && this.os) {
       this.agent.sandbox.os = this.os;
@@ -2276,7 +2569,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
     // Always close the sandbox WebSocket connection to clean up resources
     // This ensures we don't leave orphaned connections even if connect() failed
-    if (this.sandbox && typeof this.sandbox.close === 'function') {
+    if (this.sandbox && typeof this.sandbox.close === "function") {
       this.sandbox.close();
     }
 
@@ -2353,23 +2646,28 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       if (this._lastCommandName && !this._lastPromiseSettled) {
         console.warn(
           `⚠️  Warning: Previous ${this._lastCommandName}() may not have been awaited.\n` +
-          `   Add "await" before the call: await testdriver.${this._lastCommandName}(...)\n` +
-          `   Unawaited promises can cause race conditions and flaky tests.`
+            `   Add "await" before the call: await testdriver.${this._lastCommandName}(...)\n` +
+            `   Unawaited promises can cause race conditions and flaky tests.`,
         );
       }
 
       this._ensureConnected();
 
       // Track this promise for unawaited detection
-      this._lastCommandName = 'find';
+      this._lastCommandName = "find";
       this._lastPromiseSettled = false;
 
-      const element = new Element(description, this, this.system, this.commands);
+      const element = new Element(
+        description,
+        this,
+        this.system,
+        this.commands,
+      );
       const result = await element.find(null, options);
       this._lastPromiseSettled = true;
       return result;
     })();
-    
+
     // Create a chainable promise that allows direct method chaining
     // e.g., await testdriver.find("button").click()
     return createChainablePromise(findPromise);
@@ -2407,15 +2705,15 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     if (this._lastCommandName && !this._lastPromiseSettled) {
       console.warn(
         `⚠️  Warning: Previous ${this._lastCommandName}() may not have been awaited.\n` +
-        `   Add "await" before the call: await testdriver.${this._lastCommandName}(...)\n` +
-        `   Unawaited promises can cause race conditions and flaky tests.`
+          `   Add "await" before the call: await testdriver.${this._lastCommandName}(...)\n` +
+          `   Unawaited promises can cause race conditions and flaky tests.`,
       );
     }
 
     this._ensureConnected();
 
     // Track this promise for unawaited detection
-    this._lastCommandName = 'findAll';
+    this._lastCommandName = "findAll";
     this._lastPromiseSettled = false;
 
     // Capture absolute timestamp at the very start of the command
@@ -2431,11 +2729,11 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       // Handle options - can be a number (cacheThreshold) or object with cacheKey/cacheThreshold
       let cacheKey = null;
       let cacheThreshold = null;
-      
-      if (typeof options === 'number') {
+
+      if (typeof options === "number") {
         // Legacy: options is just a number threshold
         cacheThreshold = options;
-      } else if (typeof options === 'object' && options !== null) {
+      } else if (typeof options === "object" && options !== null) {
         // New: options is an object with cacheKey and/or cacheThreshold
         cacheKey = options.cacheKey || null;
         cacheThreshold = options.cacheThreshold ?? null;
@@ -2443,11 +2741,15 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
       // Use default cacheKey from SDK constructor if not provided in findAll() options
       // BUT only if cache is not explicitly disabled via cache: false option
-      if (!cacheKey && this.options?.cacheKey && !this._cacheExplicitlyDisabled) {
+      if (
+        !cacheKey &&
+        this.options?.cacheKey &&
+        !this._cacheExplicitlyDisabled
+      ) {
         cacheKey = this.options.cacheKey;
       }
 
-      // Determine threshold: 
+      // Determine threshold:
       // - If cache is explicitly disabled, don't use cache even with cacheKey
       // - If cacheKey is provided, enable cache with threshold
       // - If no cacheKey, disable cache
@@ -2468,11 +2770,13 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       }
 
       // Debug log threshold
-      const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
+      const debugMode =
+        process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
       if (debugMode) {
-        const autoGenMsg = (this._autoGeneratedCacheKey && cacheKey === this.options.cacheKey) 
-          ? ' (auto-generated from file hash)' 
-          : '';
+        const autoGenMsg =
+          this._autoGeneratedCacheKey && cacheKey === this.options.cacheKey
+            ? " (auto-generated from file hash)"
+            : "";
         this.emitter.emit(
           events.log.debug,
           `🔍 findAll() threshold: ${threshold} (cache ${threshold < 0 ? "DISABLED" : "ENABLED"}${cacheKey ? `, cacheKey: ${cacheKey}${autoGenMsg}` : ""})`,
@@ -2536,20 +2840,22 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         // Track successful findAll interaction (fire-and-forget, don't block)
         const sessionId = this.getSessionId();
         if (sessionId && this.sandbox?.send) {
-          this.sandbox.send({
-            type: "trackInteraction",
-            interactionType: "findAll",
-            session: sessionId,
-            prompt: description,
-            timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
-            success: true,
-            input: { count: elements.length },
-            cacheHit: response.cached || false,
-            selector: response.selector,
-            selectorUsed: !!response.selector,
-          }).catch(err => {
-            console.warn("Failed to track findAll interaction:", err.message);
-          });
+          this.sandbox
+            .send({
+              type: "trackInteraction",
+              interactionType: "findAll",
+              session: sessionId,
+              prompt: description,
+              timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
+              success: true,
+              input: { count: elements.length },
+              cacheHit: response.cached || false,
+              selector: response.selector,
+              selectorUsed: !!response.selector,
+            })
+            .catch((err) => {
+              console.warn("Failed to track findAll interaction:", err.message);
+            });
         }
 
         // Log debug information when elements are found
@@ -2569,7 +2875,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         return elements;
       } else {
         const duration = Date.now() - startTime;
-        
+
         // Single log at the end - no elements found
         const formattedMessage = formatter.formatFindAllSingleLine(
           description,
@@ -2584,21 +2890,23 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         // No elements found - track interaction (fire-and-forget, don't block)
         const sessionId = this.getSessionId();
         if (sessionId && this.sandbox?.send) {
-          this.sandbox.send({
-            type: "trackInteraction",
-            interactionType: "findAll",
-            session: sessionId,
-            prompt: description,
-            timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
-            success: false,
-            error: "No elements found",
-            input: { count: 0 },
-            cacheHit: response?.cached || false,
-            selector: response?.selector,
-            selectorUsed: !!response?.selector,
-          }).catch(err => {
-            console.warn("Failed to track findAll interaction:", err.message);
-          });
+          this.sandbox
+            .send({
+              type: "trackInteraction",
+              interactionType: "findAll",
+              session: sessionId,
+              prompt: description,
+              timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
+              success: false,
+              error: "No elements found",
+              input: { count: 0 },
+              cacheHit: response?.cached || false,
+              selector: response?.selector,
+              selectorUsed: !!response?.selector,
+            })
+            .catch((err) => {
+              console.warn("Failed to track findAll interaction:", err.message);
+            });
         }
 
         // No elements found - return empty array
@@ -2607,7 +2915,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       }
     } catch (error) {
       const duration = Date.now() - startTime;
-      
+
       // Single log at the end - error
       const formattedMessage = formatter.formatFindAllSingleLine(
         description,
@@ -2621,18 +2929,20 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       // Track findAll error interaction (fire-and-forget, don't block)
       const sessionId = this.getSessionId();
       if (sessionId && this.sandbox?.send) {
-        this.sandbox.send({
-          type: "trackInteraction",
-          interactionType: "findAll",
-          session: sessionId,
-          prompt: description,
-          timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
-          success: false,
-          error: error.message,
-          input: { count: 0 },
-        }).catch(err => {
-          console.warn("Failed to track findAll interaction:", err.message);
-        });
+        this.sandbox
+          .send({
+            type: "trackInteraction",
+            interactionType: "findAll",
+            session: sessionId,
+            prompt: description,
+            timestamp: absoluteTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
+            success: false,
+            error: error.message,
+            input: { count: 0 },
+          })
+          .catch((err) => {
+            console.warn("Failed to track findAll interaction:", err.message);
+          });
       }
 
       this._lastPromiseSettled = true;
@@ -2690,20 +3000,20 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       "hover-text": "hoverText",
       "hover-image": "hoverImage",
       "match-image": "matchImage",
-      "type": "type",
+      type: "type",
       "press-keys": "pressKeys",
-      "click": "click",
-      "hover": "hover",
-      "scroll": "scroll",
-      "wait": "wait",
+      click: "click",
+      hover: "hover",
+      scroll: "scroll",
+      wait: "wait",
       "wait-for-text": "waitForText",
       "wait-for-image": "waitForImage",
       "scroll-until-text": "scrollUntilText",
       "scroll-until-image": "scrollUntilImage",
       "focus-application": "focusApplication",
-      "extract": "extract",
-      "assert": "assert",
-      "exec": "exec",
+      extract: "extract",
+      assert: "assert",
+      exec: "exec",
     };
 
     // Create SDK methods that lazy-await connection then forward to this.commands
@@ -2718,8 +3028,8 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         if (this._lastCommandName && !this._lastPromiseSettled) {
           console.warn(
             `⚠️  Warning: Previous ${this._lastCommandName}() may not have been awaited.\n` +
-            `   Add "await" before the call: await testdriver.${this._lastCommandName}(...)\n` +
-            `   Unawaited promises can cause race conditions and flaky tests.`
+              `   Add "await" before the call: await testdriver.${this._lastCommandName}(...)\n` +
+              `   Unawaited promises can cause race conditions and flaky tests.`,
           );
         }
 
@@ -2787,33 +3097,38 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
    */
   async screenshot(filename) {
     this._ensureConnected();
-    
-    const finalFilename = filename 
-      ? (filename.endsWith('.png') ? filename : `${filename}.png`)
+
+    const finalFilename = filename
+      ? filename.endsWith(".png")
+        ? filename
+        : `${filename}.png`
       : `screenshot-${Date.now()}.png`;
-    
+
     const base64Data = await this.system.captureScreenBase64(1, false, false);
-    
+
     // Save to .testdriver/screenshots/<test-file-name> directory
     let screenshotsDir = path.join(process.cwd(), ".testdriver", "screenshots");
     if (this.testFile) {
-      const testFileName = path.basename(this.testFile, path.extname(this.testFile));
+      const testFileName = path.basename(
+        this.testFile,
+        path.extname(this.testFile),
+      );
       screenshotsDir = path.join(screenshotsDir, testFileName);
     }
     if (!fs.existsSync(screenshotsDir)) {
       fs.mkdirSync(screenshotsDir, { recursive: true });
     }
-    
+
     const filePath = path.join(screenshotsDir, finalFilename);
-    
+
     // Remove data:image/png;base64, prefix if present
     const cleanBase64 = base64Data.replace(/^data:image\/\w+;base64,/, "");
     const buffer = Buffer.from(cleanBase64, "base64");
-    
+
     fs.writeFileSync(filePath, buffer);
-    
+
     this.emitter.emit("log:info", `📸 Screenshot saved to: ${filePath}`);
-    
+
     return filePath;
   }
 
@@ -2872,13 +3187,14 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
   _setupLogging() {
     // Track the last fatal error message to throw on exit
     let lastFatalError = null;
-    const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
+    const debugMode =
+      process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
 
     // Set up markdown logger
     createMarkdownLogger(this.emitter);
 
     // Set up basic event logging
-    // Note: We only console.log here - the console spy in vitest/hooks.mjs 
+    // Note: We only console.log here - the console spy in vitest/hooks.mjs
     // handles forwarding to sandbox. This prevents duplicate output to server.
     this.emitter.on("log:**", (message) => {
       const event = this.emitter.event;
@@ -2900,7 +3216,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       if (this.loggingEnabled) {
         const event = this.emitter.event;
         console.error(event, ":", data);
-        
+
         // Capture fatal errors
         if (event === events.error.fatal) {
           lastFatalError = data;
@@ -2919,9 +3235,9 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     this.emitter.on(events.exit, (exitCode) => {
       if (exitCode !== 0) {
         // Create an error with the fatal error message if available
-        const errorMessage = lastFatalError || 'TestDriver fatal error';
+        const errorMessage = lastFatalError || "TestDriver fatal error";
         const error = new Error(errorMessage);
-        error.name = 'TestDriverFatalError';
+        error.name = "TestDriverFatalError";
         error.exitCode = exitCode;
         throw error;
       }
@@ -2946,7 +3262,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           console.log(url);
           await this._openBrowser(url);
         }
-        
       }
     });
   }
@@ -3037,7 +3352,12 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
     // Auto-detect sandbox ID from the active sandbox if not provided
     // For E2B (Linux), the instance has sandboxId; for AWS (Windows), it has instanceId
-    const sandboxId = options.sandboxId || this.instance?.sandboxId || this.instance?.instanceId || this.agent?.sandboxId || null;
+    const sandboxId =
+      options.sandboxId ||
+      this.instance?.sandboxId ||
+      this.instance?.instanceId ||
+      this.agent?.sandboxId ||
+      null;
 
     // Get or create session ID using the agent's newSession method
     let sessionId = this.agent?.sessionInstance?.get() || null;
@@ -3208,7 +3528,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     // Store original checkLimit and set custom one if provided
     const originalCheckLimit = this.agent.checkLimit;
     this.agent.checkLimit = tries;
-    
+
     // Reset check count for this act() call
     const originalCheckCount = this.agent.checkCount;
     this.agent.checkCount = 0;
@@ -3218,17 +3538,25 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
     try {
       // Use the agent's exploratoryLoop method directly
-      const response = await this.agent.exploratoryLoop(task, false, true, false);
-      
+      const response = await this.agent.exploratoryLoop(
+        task,
+        false,
+        true,
+        false,
+      );
+
       const duration = Date.now() - startTime;
       const triesUsed = this.agent.checkCount;
-      
-      this.emitter.emit(events.log.log, formatter.formatAIComplete(duration, true));
-      
+
+      this.emitter.emit(
+        events.log.log,
+        formatter.formatAIComplete(duration, true),
+      );
+
       // Restore original checkLimit
       this.agent.checkLimit = originalCheckLimit;
       this.agent.checkCount = originalCheckCount;
-      
+
       return {
         success: true,
         task,
@@ -3240,13 +3568,16 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     } catch (error) {
       const duration = Date.now() - startTime;
       const triesUsed = this.agent.checkCount;
-      
-      this.emitter.emit(events.log.log, formatter.formatAIComplete(duration, false, error.message));
-      
+
+      this.emitter.emit(
+        events.log.log,
+        formatter.formatAIComplete(duration, false, error.message),
+      );
+
       // Restore original checkLimit
       this.agent.checkLimit = originalCheckLimit;
       this.agent.checkCount = originalCheckCount;
-      
+
       // Create an enhanced error with additional context using AIError class
       throw new AIError(`AI failed: ${error.message}`, {
         task,