testdriverai 7.2.46 → 7.2.48

package/.github/workflows/acceptance-linux-scheduled.yaml

@@ -31,7 +31,7 @@ jobs:
 
     - name: Run Linux tests with Sentry Cron monitoring
       run: |
-        sentry-cli monitors run testdriver-linux-acceptance -- npx vitest run test/testdriver/*.test.mjs
+        sentry-cli monitors run testdriver-linux-acceptance -- npx vitest run examples/*.test.mjs
       env:
         SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
         TD_API_KEY: ${{ secrets.TD_API_KEY }}

package/.github/workflows/acceptance.yaml

@@ -29,7 +29,7 @@ jobs:
       run: npm ci
     
     - name: Run Linux tests
-      run: npx vitest run test/testdriver/*.test.mjs
+      run: npx vitest run examples/*.test.mjs
       env:
         TD_API_KEY: ${{ secrets.TD_API_KEY }}
         TD_OS: linux
@@ -52,7 +52,7 @@ jobs:
     if: contains(github.event.pull_request.labels.*.name, 'test-windows')
     uses: ./.github/workflows/windows-self-hosted.yaml
     with:
-      test_pattern: 'test/testdriver/assert.test.mjs'
+      test_pattern: 'examples/assert.test.mjs'
     secrets:
       TD_API_KEY: ${{ secrets.TD_API_KEY }}
       TD_WEBSITE: ${{ secrets.TD_WEBSITE }}

package/.github/workflows/windows-self-hosted.yaml

@@ -7,7 +7,7 @@ on:
         description: 'Test file pattern to run'
         required: false
         type: string
-        default: 'test/testdriver/*.test.mjs'
+        default: 'examples/*.test.mjs'
     secrets:
       TD_API_KEY:
         required: true

package/README.md

@@ -11,7 +11,7 @@
 <br />
 <br />
   
-[🚀 **Quick Start**](#-quick-start) • [📖 **Documentation**](https://docs.testdriver.ai) • [💻 **Examples**](https://github.com/testdriverai/testdriverai/tree/main/test/testdriver) • [📖 **Pricing**](https://docs.testdriver.ai) • [💬 **Discord**](https://discord.com/invite/cWDFW8DzPm) • [🌐 **Website**](https://testdriver.ai)
+[🚀 **Quick Start**](#-quick-start) • [📖 **Documentation**](https://docs.testdriver.ai) • [💻 **Examples**](https://github.com/testdriverai/testdriverai/tree/main/examples) • [📖 **Pricing**](https://docs.testdriver.ai) • [💬 **Discord**](https://discord.com/invite/cWDFW8DzPm) • [🌐 **Website**](https://testdriver.ai)
 
 </div>
 
@@ -41,7 +41,7 @@ const result = await testdriver.assert(
 expect(result).toBeTruthy();
 ```
 
-[See Full Example](https://github.com/testdriverai/testdriverai/blob/main/test/testdriver/drag-and-drop.test.mjs) • [Browse All Examples](https://github.com/testdriverai/testdriverai/tree/main/test/testdriver)
+[See Full Example](https://github.com/testdriverai/testdriverai/blob/main/examples/drag-and-drop.test.mjs) • [Browse All Examples](https://github.com/testdriverai/testdriverai/tree/main/examples)
 
 ---
 

package/agent/lib/sdk.js

@@ -95,31 +95,126 @@ const createSDK = (emitter, config, sessionInstance) => {
   };
 
   const auth = async () => {
-    if (config["TD_API_KEY"]) {
-      const url = [config["TD_API_ROOT"], "auth/exchange-api-key"].join("/");
-      const c = {
-        method: "post",
-        headers: {
-          "Content-Type": "application/json",
-        },
-        data: {
-          apiKey: config["TD_API_KEY"],
-          version,
-        },
-      };
-
-      try {
-        let res = await axios(url, c);
-
-        token = res.data.token;
-        return token;
-      } catch (error) {
-        outputError(error);
-        throw error; // Re-throw the error so calling code can handle it properly
-      }
+    if (!config["TD_API_KEY"]) {
+      const error = new Error(
+        "TD_API_KEY is not configured. Get your API key at https://console.testdriver.ai/team"
+      );
+      error.code = "MISSING_API_KEY";
+      error.isAuthError = true;
+      throw error;
+    }
+
+    const url = [config["TD_API_ROOT"], "auth/exchange-api-key"].join("/");
+    const c = {
+      method: "post",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      timeout: 15000, // 15 second timeout for auth requests
+      data: {
+        apiKey: config["TD_API_KEY"],
+        version,
+      },
+    };
+
+    try {
+      let res = await axios(url, c);
+
+      token = res.data.token;
+      return token;
+    } catch (error) {
+      // Classify the error for better user feedback
+      const classifiedError = classifyAuthError(error, config["TD_API_ROOT"]);
+      outputError(classifiedError);
+      throw classifiedError;
     }
   };
 
+  /**
+   * Classify authentication errors into user-friendly categories
+   * @param {Error} error - The original axios error
+   * @param {string} apiRoot - The API root URL for context
+   * @returns {Error} A classified error with code and helpful message
+   */
+  function classifyAuthError(error, apiRoot) {
+    const status = error.response?.status;
+    const data = error.response?.data;
+
+    // Check for network-level errors (no response received)
+    if (!error.response) {
+      const networkError = new Error(
+        `Unable to reach TestDriver API at ${apiRoot}. ` +
+        getNetworkErrorHint(error.code)
+      );
+      networkError.code = "NETWORK_ERROR";
+      networkError.isNetworkError = true;
+      networkError.originalError = error;
+      return networkError;
+    }
+
+    // Invalid API key (401)
+    if (status === 401) {
+      const authError = new Error(
+        data?.message ||
+        "Invalid API key. Please check your TD_API_KEY and try again. " +
+        "Get your API key at https://console.testdriver.ai/team"
+      );
+      authError.code = data?.error || "INVALID_API_KEY";
+      authError.isAuthError = true;
+      authError.originalError = error;
+      return authError;
+    }
+
+    // Server errors (5xx) - API is down or having issues
+    if (status >= 500) {
+      const serverError = new Error(
+        data?.message ||
+        `TestDriver API is currently unavailable (HTTP ${status}). Please try again later.`
+      );
+      serverError.code = data?.error || "API_UNAVAILABLE";
+      serverError.isServerError = true;
+      serverError.originalError = error;
+      return serverError;
+    }
+
+    // Rate limiting (429)
+    if (status === 429) {
+      const rateLimitError = new Error(
+        "Too many requests to TestDriver API. Please wait a moment and try again."
+      );
+      rateLimitError.code = "RATE_LIMITED";
+      rateLimitError.isRateLimitError = true;
+      rateLimitError.originalError = error;
+      return rateLimitError;
+    }
+
+    // Other HTTP errors - return with context
+    const genericError = new Error(
+      `Authentication failed: ${status} ${error.response?.statusText || "Unknown error"}`
+    );
+    genericError.code = "AUTH_FAILED";
+    genericError.originalError = error;
+    return genericError;
+  }
+
+  /**
+   * Get a helpful hint based on the network error code
+   * @param {string} code - The error code (ECONNREFUSED, ETIMEDOUT, etc.)
+   * @returns {string} A helpful message for the user
+   */
+  function getNetworkErrorHint(code) {
+    const hints = {
+      ECONNREFUSED: "The server refused the connection. Check if the API is running.",
+      ETIMEDOUT: "The connection timed out. Check your internet connection.",
+      ENOTFOUND: "Could not resolve the hostname. Check your internet connection or DNS settings.",
+      ENETUNREACH: "Network is unreachable. Check your internet connection.",
+      ECONNRESET: "Connection was reset. This may be a temporary network issue.",
+      ERR_NETWORK: "A network error occurred. Check your internet connection.",
+      ECONNABORTED: "The request was aborted due to a timeout.",
+    };
+    return hints[code] || "Check your internet connection and try again.";
+  }
+
   const req = async (path, data, onChunk) => {
     // for each value of data, if it is empty remove it
     for (let key in data) {
@@ -219,6 +314,26 @@ const createSDK = (emitter, config, sessionInstance) => {
 
       return value;
     } catch (error) {
+      // Check for network-level errors (no response received)
+      if (!error.response) {
+        const networkError = new Error(
+          `Unable to reach TestDriver API at ${config["TD_API_ROOT"]}. ` +
+          getNetworkErrorHint(error.code)
+        );
+        networkError.code = "NETWORK_ERROR";
+        networkError.isNetworkError = true;
+        networkError.originalError = error;
+        networkError.path = path;
+        
+        emitter.emit(events.error.sdk, {
+          message: networkError.message,
+          code: networkError.code,
+          fullError: error,
+        });
+        
+        throw networkError;
+      }
+
       // Check if this is an API validation error with detailed problems
       if (error.response?.data?.problems) {
         const problems = error.response.data.problems;
@@ -239,6 +354,46 @@ const createSDK = (emitter, config, sessionInstance) => {
         
         throw detailedError;
       }
+
+      // Server errors (5xx) - API is down or having issues
+      const status = error.response?.status;
+      if (status >= 500) {
+        const serverError = new Error(
+          error.response?.data?.message ||
+          `TestDriver API is currently unavailable (HTTP ${status}). Please try again later.`
+        );
+        serverError.code = error.response?.data?.error || "API_UNAVAILABLE";
+        serverError.isServerError = true;
+        serverError.originalError = error;
+        serverError.path = path;
+        
+        emitter.emit(events.error.sdk, {
+          message: serverError.message,
+          code: serverError.code,
+          fullError: error,
+        });
+        
+        throw serverError;
+      }
+
+      // Rate limiting (429)
+      if (status === 429) {
+        const rateLimitError = new Error(
+          "Too many requests to TestDriver API. Please wait a moment and try again."
+        );
+        rateLimitError.code = "RATE_LIMITED";
+        rateLimitError.isRateLimitError = true;
+        rateLimitError.originalError = error;
+        rateLimitError.path = path;
+        
+        emitter.emit(events.error.sdk, {
+          message: rateLimitError.message,
+          code: rateLimitError.code,
+          fullError: error,
+        });
+        
+        throw rateLimitError;
+      }
       
       outputError(error);
       throw error; // Re-throw the error so calling code can handle it properly

package/docs/TEST-GITHUB-COMMENTS.md

@@ -38,7 +38,7 @@
 
 ## What the Test Does
 
-The workflow runs `test/testdriver/assert.test.mjs` which:
+The workflow runs `examples/assert.test.mjs` which:
 - Provisions a Chrome browser
 - Navigates to https://saucedemo.com
 - Performs login actions
@@ -72,7 +72,7 @@ Skipped: 0 ⏭️
 
 | Status | Test | File | Duration | Replay |
 |--------|------|------|----------|--------|
-| ✅ | Assert Test | `test/testdriver/assert.test.mjs` | 25.3s | [🎥 View](https://console.testdriver.ai/replay/...) |
+| ✅ | Assert Test | `examples/assert.test.mjs` | 25.3s | [🎥 View](https://console.testdriver.ai/replay/...) |
 
 ## 🎥 Dashcam Replays
 

package/docs/v7/_drafts/plugin-migration.mdx

@@ -142,7 +142,7 @@ export default defineConfig({
 
 ### Test Helpers
 
-- ✅ **Removed**: `test/testdriver/setup/` folder (legacy helpers)
+- ✅ **Removed**: `examples/setup/` folder (legacy helpers)
   - Code moved to `lib/vitest/hooks.mjs` framework
   - Tests now use `TestDriver(context, options)` pattern directly
 

package/docs/v7/aws-setup.mdx

@@ -257,7 +257,7 @@ jobs:
         run: npm ci
 
       - name: Run Windows tests with self-hosted instances
-        run: npx vitest run test/testdriver/*.test.mjs
+        run: npx vitest run examples/*.test.mjs
         env:
           TD_API_KEY: ${{ secrets.TD_API_KEY }}
           TD_OS: windows

package/docs/v7/examples.mdx

@@ -1,5 +1,5 @@
 ---
 title: "Examples"
-url: "https://github.com/testdriverai/testdriverai/tree/main/test/testdriver"
+url: "https://github.com/testdriverai/testdriverai/tree/main/examples"
 icon: 'code'
 ---

package/docs/v7/find.mdx

@@ -202,6 +202,41 @@ The `timeout` option:
 - Logs progress during polling
 - Returns the element (check `element.found()` if not throwing on failure)
 
+## Zoom Mode for Crowded UIs
+
+When dealing with many similar icons or elements clustered together (like browser toolbars), enable `zoom` mode for better precision:
+
+```javascript
+// Enable zoom for better precision in crowded UIs
+const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar', { zoom: true });
+await extensionsBtn.click();
+```
+
+### How Zoom Mode Works
+
+1. **Phase 1**: AI identifies the approximate location of the element
+2. **Phase 2**: A 30% crop of the screen is created around that location
+3. **Phase 3**: AI performs precise location on the zoomed/cropped image
+4. **Result**: Coordinates are converted back to absolute screen position
+
+This two-phase approach gives the AI a higher-resolution view of the target area, improving accuracy when multiple similar elements are close together.
+
+<Tip>
+  Use `zoom: true` when:
+  - Clicking small icons in toolbars
+  - Selecting from a grid of similar items
+  - Targeting elements in dense UI areas
+  - The default locate is clicking the wrong similar element
+</Tip>
+
+```javascript
+// Without zoom - may click wrong icon in toolbar
+const icon = await testdriver.find('settings icon');
+
+// With zoom - better precision for crowded areas
+const icon = await testdriver.find('settings icon', { zoom: true });
+```
+
 ### Manual Polling (Alternative)
 
 If you need custom polling logic:

package/{test/testdriver → examples}/chrome-extension.test.mjs

@@ -15,7 +15,7 @@ describe("Chrome Extension Test", () => {
 
     console.log('connecting to', process.env.TD_IP)
 
-    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP });
+    const testdriver = TestDriver(context, { ip: context.ip || process.env.TD_IP, cacheKey: new Date().getTime().toString() });
     
     // Wait for connection to be ready before running exec
     await testdriver.ready();
@@ -55,7 +55,7 @@ describe("Chrome Extension Test", () => {
     // When clicked, it shows a popup with "Hello Extensions"
 
     // Click on the extensions button (puzzle piece icon) in Chrome toolbar
-    const extensionsButton = await testdriver.find("The extensions button in the Chrome toolbar");
+    const extensionsButton = await testdriver.find("The extensions button in the Chrome toolbar", {zoom: true});
     await extensionsButton.click();
 
     // Look for the hello world extension in the extensions menu
@@ -87,7 +87,7 @@ describe("Chrome Extension Test", () => {
     expect(pageResult).toBeTruthy();
 
     // Click on the extensions button (puzzle piece icon) in Chrome toolbar
-    const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.");
+    const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.", {zoom: true});
     await extensionsButton.click();
 
     // Look for Loom in the extensions menu

package/interfaces/vitest-plugin.mjs

@@ -185,22 +185,87 @@ export function getPluginState() {
 
 // Export API helper functions for direct use from tests
 export async function authenticateWithApiKey(apiKey, apiRoot) {
+  if (!apiKey) {
+    const error = new Error(
+      "TD_API_KEY is not configured. Get your API key at https://console.testdriver.ai/team"
+    );
+    error.code = "MISSING_API_KEY";
+    error.isAuthError = true;
+    throw error;
+  }
+
   const url = `${apiRoot}/auth/exchange-api-key`;
-  const response = await withTimeout(
-    fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ apiKey }),
-    }),
-    10000,
-    "Authentication",
-  );
+  let response;
+
+  try {
+    response = await withTimeout(
+      fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ apiKey }),
+      }),
+      15000,
+      "Authentication",
+    );
+  } catch (fetchError) {
+    // Network-level error (fetch failed entirely)
+    const networkError = new Error(
+      `Unable to reach TestDriver API at ${apiRoot}. ` +
+      "Check your internet connection and try again."
+    );
+    networkError.code = "NETWORK_ERROR";
+    networkError.isNetworkError = true;
+    networkError.originalError = fetchError;
+    throw networkError;
+  }
 
   if (!response.ok) {
+    let data = {};
+    try {
+      data = await response.json();
+    } catch {
+      // Response wasn't JSON, use empty object
+    }
+
+    // Invalid API key (401)
+    if (response.status === 401) {
+      const authError = new Error(
+        data.message ||
+        "Invalid API key. Please check your TD_API_KEY and try again. " +
+        "Get your API key at https://console.testdriver.ai/team"
+      );
+      authError.code = data.error || "INVALID_API_KEY";
+      authError.isAuthError = true;
+      throw authError;
+    }
+
+    // Server errors (5xx) - API is down or having issues
+    if (response.status >= 500) {
+      const serverError = new Error(
+        data.message ||
+        `TestDriver API is currently unavailable (HTTP ${response.status}). Please try again later.`
+      );
+      serverError.code = data.error || "API_UNAVAILABLE";
+      serverError.isServerError = true;
+      throw serverError;
+    }
+
+    // Rate limiting (429)
+    if (response.status === 429) {
+      const rateLimitError = new Error(
+        "Too many requests to TestDriver API. Please wait a moment and try again."
+      );
+      rateLimitError.code = "RATE_LIMITED";
+      rateLimitError.isRateLimitError = true;
+      throw rateLimitError;
+    }
+
+    // Other HTTP errors
     throw new Error(
-      `Authentication failed: ${response.status} ${response.statusText}`,
+      `Authentication failed: ${response.status} ${response.statusText}` +
+      (data.message ? ` - ${data.message}` : "")
     );
   }
 

package/package.json

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

package/sdk.js

@@ -413,6 +413,7 @@ class Element {
       // Handle options - can be a number (cacheThreshold) or object with cacheKey/cacheThreshold
       let cacheKey = null;
       let cacheThreshold = null;
+      let zoom = false; // Default to disabled, enable with zoom: true
       
       if (typeof options === 'number') {
         // Legacy: options is just a number threshold
@@ -421,18 +422,26 @@ class Element {
         // New: options is an object with cacheKey and/or cacheThreshold
         cacheKey = options.cacheKey || null;
         cacheThreshold = options.cacheThreshold ?? null;
+        // zoom defaults to false unless explicitly set to true
+        zoom = options.zoom === true;
       }
 
       // Use default cacheKey from SDK constructor if not provided in find() options
-      if (!cacheKey && this.sdk.options?.cacheKey) {
+      // BUT only if cache is not explicitly disabled via cache: false option
+      if (!cacheKey && this.sdk.options?.cacheKey && this.sdk.cacheThresholds?.find !== -1) {
         cacheKey = this.sdk.options.cacheKey;
       }
 
       // Determine threshold: 
+      // - If cache is explicitly disabled (threshold = -1), don't use cache even with cacheKey
       // - If cacheKey is provided, enable cache (threshold = 0.01 or custom)
       // - If no cacheKey, disable cache (threshold = -1) unless explicitly overridden
       let threshold;
-      if (cacheKey) {
+      if (this.sdk.cacheThresholds?.find === -1) {
+        // Cache explicitly disabled via cache: false option
+        threshold = -1;
+        cacheKey = null; // Clear any cacheKey to ensure cache is truly disabled
+      } else if (cacheKey) {
         // cacheKey provided - enable cache with threshold
         threshold = cacheThreshold ?? 0.01;
       } else if (cacheThreshold !== null) {
@@ -466,6 +475,7 @@ class Element {
         cacheKey: cacheKey,
         os: this.sdk.os,
         resolution: this.sdk.resolution,
+        zoom: zoom,
       });
 
       const duration = Date.now() - startTime;
@@ -2449,15 +2459,21 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       }
 
       // Use default cacheKey from SDK constructor if not provided in findAll() options
-      if (!cacheKey && this.options?.cacheKey) {
+      // BUT only if cache is not explicitly disabled via cache: false option
+      if (!cacheKey && this.options?.cacheKey && this.cacheThresholds?.findAll !== -1) {
         cacheKey = this.options.cacheKey;
       }
 
       // Determine threshold: 
+      // - If cache is explicitly disabled (threshold = -1), don't use cache even with cacheKey
       // - If cacheKey is provided, enable cache (threshold = 0.01 or custom)
       // - If no cacheKey, disable cache (threshold = -1) unless explicitly overridden
       let threshold;
-      if (cacheKey) {
+      if (this.cacheThresholds?.findAll === -1) {
+        // Cache explicitly disabled via cache: false option
+        threshold = -1;
+        cacheKey = null; // Clear any cacheKey to ensure cache is truly disabled
+      } else if (cacheKey) {
         // cacheKey provided - enable cache with threshold
         threshold = cacheThreshold ?? 0.01;
       } else if (cacheThreshold !== null) {

package/test/manual/reconnect-provision.test.mjs

@@ -8,8 +8,8 @@
  * Run reconnect-signin.test.mjs within 2 minutes of this test completing.
  * 
  * Usage:
- *   1. npm test -- test/testdriver/reconnect-provision.test.mjs
- *   2. (within 2 minutes) npm test -- test/testdriver/reconnect-signin.test.mjs
+ *   1. npm test -- examples/reconnect-provision.test.mjs
+ *   2. (within 2 minutes) examples/reconnect-signin.test.mjs
  */
 
 import { afterAll, describe, expect, it } from "vitest";