testdriverai 7.4.4 → 7.4.5

package/.github/copilot-instructions.md

@@ -670,7 +670,7 @@ await testdriver.screenshot(1, false, true);
 3. **⚠️ SHARE THE TEST REPORT URL** - After EVERY test run, find `TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/...` in the output and share it with the user. This is CRITICAL - users need to view the recording to understand what happened.
 3. **Screenshots are automatic** - TestDriver captures screenshots before/after every command by default. Each screenshot filename includes the line number (e.g., `001-click-before-L42-submit-button.png`) making it easy to trace issues.
 4. **⚠️ USE SCREENSHOT VIEWING FOR DEBUGGING** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` MCP commands to see exactly what the UI looked like. The filenames tell you which line of code triggered each screenshot.
-5. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
+5. **Use `wait()` for simple delays** - Use `await testdriver.wait(ms)` when you need a pause (e.g., after actions, for animations). For waiting for specific elements, prefer `find()` with a `timeout` option.
 6. **Use MCP tools for development** - Build tests interactively with visual feedback
 7. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
 8. **Look at test samples** in `node_modules/testdriverai/test` for working examples

package/.github/skills/testdriver:performing-actions/SKILL.md

@@ -29,6 +29,9 @@ await testdriver.find('dropdown menu').hover();
 await testdriver.scroll('down', 500);
 await testdriver.scrollUntilText('Footer content');
 
+// Waiting
+await testdriver.wait(2000); // Wait 2 seconds for animation/state change
+
 // Extracting information from screen
 const price = await testdriver.extract('the total price');
 const orderNumber = await testdriver.extract('the order confirmation number');

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

@@ -70,3 +70,19 @@ const testdriver = TestDriver(context, {
   }
 });
 ```
+
+## Simple Delays with `wait()`
+
+For simple pauses — waiting for animations, transitions, or state changes after an action — use `wait()`:
+
+```javascript
+// Wait for an animation to complete
+await testdriver.find('menu toggle').click();
+await testdriver.wait(2000);
+
+// Wait for a page transition to settle
+await testdriver.find('next page button').click();
+await testdriver.wait(1000);
+```
+
+For waiting for specific **elements** to appear, prefer `find()` with a `timeout` option. Use `wait()` only for simple time-based pauses.

package/agent/lib/sandbox.js

@@ -38,16 +38,9 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       this.os = null; // Store OS value to send with every message
       this.sessionInstance = sessionInstance; // Store session instance to include in messages
       this.traceId = null; // Sentry trace ID for debugging
-      this.reconnectAttempts = 0;
-      this.maxReconnectAttempts = 10;
-      this.intentionalDisconnect = false;
       this.apiRoot = null;
       this.apiKey = null;
-      this.reconnectTimer = null; // Track reconnect setTimeout
-      this.reconnecting = false; // Prevent duplicate reconnection attempts
-      this.pendingTimeouts = new Map(); // Track per-message timeouts
-      this.pendingRetryQueue = []; // Queue of requests to retry after reconnection
-      this._lastConnectParams = null; // Connection params for reconnection (per-instance, not shared)
+      this._lastConnectParams = null; // Connection params for sandboxId injection
     }
 
     /**
@@ -118,7 +111,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
 
         // Set up timeout to prevent hanging requests
         const timeoutId = setTimeout(() => {
-          this.pendingTimeouts.delete(requestId);
           if (this.ps[requestId]) {
             delete this.ps[requestId];
             rejectPromise(
@@ -133,19 +125,14 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           timeoutId.unref();
         }
 
-        // Track timeout so close() can clear it
-        this.pendingTimeouts.set(requestId, timeoutId);
-
         this.ps[requestId] = {
           promise: p,
           resolve: (result) => {
             clearTimeout(timeoutId);
-            this.pendingTimeouts.delete(requestId);
             resolvePromise(result);
           },
           reject: (error) => {
             clearTimeout(timeoutId);
-            this.pendingTimeouts.delete(requestId);
             rejectPromise(error);
           },
           message,
@@ -199,16 +186,9 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
     }
 
     /**
-     * Set connection params for reconnection logic and sandboxId injection.
-     * Use this instead of directly assigning this._lastConnectParams from
-     * external code. Keeps the shape consistent and avoids stale state
-     * leaking across concurrent test runs.
+     * Set connection params for sandboxId injection.
      * @param {Object|null} params
-     * @param {string} [params.type] - 'direct' for IP-based connections
-     * @param {string} [params.ip] - IP address for direct connections
      * @param {string} [params.sandboxId] - Sandbox/instance ID
-     * @param {boolean} [params.persist] - Whether to persist the sandbox
-     * @param {number|null} [params.keepAlive] - Keep-alive TTL in ms
      */
     setConnectionParams(params) {
       this._lastConnectParams = params ? { ...params } : null;
@@ -238,163 +218,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       }
     }
 
-    /**
-     * Reconnect to a direct IP-based sandbox after connection loss.
-     * Sends a 'direct' message instead of 'connect' to avoid the API
-     * treating the IP as an AWS instance ID.
-     */
-    async reconnectDirect(ip) {
-      let reply = await this.send({
-        type: "direct",
-        ip,
-      });
-
-      if (reply.success) {
-        this.instanceSocketConnected = true;
-        emitter.emit(events.sandbox.connected);
-        return reply;
-      } else {
-        throw new Error(reply.errorMessage || "Failed to reconnect to direct sandbox");
-      }
-    }
-
-    async handleConnectionLoss() {
-      if (this.intentionalDisconnect) return;
-
-      // Prevent duplicate reconnection attempts (both 'error' and 'close' fire)
-      if (this.reconnecting) return;
-      this.reconnecting = true;
-
-      // Remove listeners from the old socket to prevent "No pending promise found" warnings
-      // when late responses arrive on the dying connection
-      if (this.socket) {
-        try {
-          this.socket.removeAllListeners("message");
-        } catch (e) {
-          // Ignore errors removing listeners from closed socket
-        }
-      }
-
-      // Queue pending requests for retry after reconnection
-      // (they were sent on the old socket and will never receive responses)
-      const pendingRequestIds = Object.keys(this.ps);
-      if (pendingRequestIds.length > 0) {
-        console.log(`[Sandbox] Queuing ${pendingRequestIds.length} pending request(s) for retry after reconnection`);
-        for (const requestId of pendingRequestIds) {
-          const pending = this.ps[requestId];
-          if (pending) {
-            // Clear the timeout - we'll set a new one when we retry
-            const timeoutId = this.pendingTimeouts.get(requestId);
-            if (timeoutId) {
-              clearTimeout(timeoutId);
-              this.pendingTimeouts.delete(requestId);
-            }
-            // Queue for retry (store message and promise handlers)
-            this.pendingRetryQueue.push({
-              message: pending.message,
-              resolve: pending.resolve,
-              reject: pending.reject,
-            });
-          }
-        }
-        this.ps = {};
-      }
-
-      // Cancel any existing reconnect timer
-      if (this.reconnectTimer) {
-        clearTimeout(this.reconnectTimer);
-        this.reconnectTimer = null;
-      }
-
-      if (this.reconnectAttempts >= this.maxReconnectAttempts) {
-        const errorMsg =
-          "Unable to reconnect to TestDriver sandbox after multiple attempts. Please check your internet connection.";
-        emitter.emit(events.error.sandbox, errorMsg);
-        console.error(errorMsg);
-        
-        // Reject all queued requests since reconnection failed
-        if (this.pendingRetryQueue.length > 0) {
-          console.log(`[Sandbox] Rejecting ${this.pendingRetryQueue.length} queued request(s) - reconnection failed`);
-          for (const queued of this.pendingRetryQueue) {
-            queued.reject(new Error("Sandbox reconnection failed after multiple attempts"));
-          }
-          this.pendingRetryQueue = [];
-        }
-        
-        this.reconnecting = false;
-        return;
-      }
-
-      this.reconnectAttempts++;
-      const delay = Math.min(1000 * 2 ** (this.reconnectAttempts - 1), 60000);
-
-      console.log(
-        `[Sandbox] Connection lost. Reconnecting in ${delay}ms... (Attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`,
-      );
-
-      this.reconnectTimer = setTimeout(async () => {
-        this.reconnectTimer = null;
-        try {
-          await this.boot(this.apiRoot);
-          if (this.apiKey) {
-            await this.auth(this.apiKey);
-          }
-          // Re-establish sandbox connection on the new API instance
-          // Without this, the new API instance has no connection.desktop
-          // and all Linux operations will fail with "sandbox not initialized"
-          if (this._lastConnectParams) {
-            if (this._lastConnectParams.type === 'direct') {
-              // Direct IP connections must reconnect via 'direct' message, not 'connect'
-              const { ip, persist, keepAlive } = this._lastConnectParams;
-              console.log(`[Sandbox] Re-establishing direct connection (${ip})...`);
-              await this.reconnectDirect(ip);
-            } else {
-              const { sandboxId, persist, keepAlive } = this._lastConnectParams;
-              console.log(`[Sandbox] Re-establishing sandbox connection (${sandboxId})...`);
-              await this.connect(sandboxId, persist, keepAlive);
-            }
-          }
-          console.log("[Sandbox] Reconnected successfully.");
-          
-          // Retry queued requests
-          await this._retryQueuedRequests();
-        } catch (e) {
-          // boot's close handler will trigger handleConnectionLoss again
-        } finally {
-          this.reconnecting = false;
-        }
-      }, delay);
-      // Don't let reconnect timer prevent Node process from exiting
-      if (this.reconnectTimer.unref) {
-        this.reconnectTimer.unref();
-      }
-    }
-
-    /**
-     * Retry queued requests after successful reconnection
-     * @private
-     */
-    async _retryQueuedRequests() {
-      if (this.pendingRetryQueue.length === 0) return;
-
-      console.log(`[Sandbox] Retrying ${this.pendingRetryQueue.length} queued request(s)...`);
-      
-      // Take all queued requests and clear the queue
-      const toRetry = this.pendingRetryQueue.splice(0);
-      
-      for (const queued of toRetry) {
-        try {
-          // Re-send the message and resolve/reject the original promise
-          const result = await this.send(queued.message);
-          queued.resolve(result);
-        } catch (err) {
-          queued.reject(err);
-        }
-      }
-      
-      console.log(`[Sandbox] Finished retrying queued requests.`);
-    }
-
     async boot(apiRoot) {
       if (apiRoot) this.apiRoot = apiRoot;
       return new Promise((resolve, reject) => {
@@ -424,12 +247,7 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
         this.socket.on("close", () => {
           clearInterval(this.heartbeat);
           this.apiSocketConnected = false;
-          // Also mark instance socket as disconnected to prevent sending messages
-          // to a closed connection (e.g., when sandbox is killed due to test failure)
           this.instanceSocketConnected = false;
-          // Reset reconnecting flag so handleConnectionLoss can run for this new disconnection
-          this.reconnecting = false;
-          this.handleConnectionLoss();
           reject();
         });
 
@@ -439,14 +257,10 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           clearInterval(this.heartbeat);
           emitter.emit(events.error.sandbox, err);
           this.apiSocketConnected = false;
-          // Don't call handleConnectionLoss here - the 'close' event always fires
-          // after 'error', so let 'close' handle reconnection to avoid duplicate attempts
           reject(err);
         });
 
         this.socket.on("open", async () => {
-          this.reconnectAttempts = 0;
-          this.reconnecting = false;
           this.apiSocketConnected = true;
 
           this.heartbeat = setInterval(() => {
@@ -475,18 +289,15 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           }
 
           if (!this.ps[message.requestId]) {
-            // This can happen during reconnection (ps was cleared) or after timeout
-            // (promise was deleted). Expected during polling loops (e.g. Chrome
-            // debugger readiness checks) where short-timeout exec calls regularly
-            // expire before the sandbox responds.  Only log in debug/verbose mode.
-            if (!this.reconnecting) {
-              const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
-              if (debugMode) {
-                console.warn(
-                  "No pending promise found for requestId:",
-                  message.requestId,
-                );
-              }
+            // Can happen after timeout (promise was deleted). Expected during
+            // polling loops where short-timeout exec calls regularly expire
+            // before the sandbox responds. Only log in debug/verbose mode.
+            const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
+            if (debugMode) {
+              console.warn(
+                "No pending promise found for requestId:",
+                message.requestId,
+              );
             }
             return;
           }
@@ -514,27 +325,12 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
      * Close the WebSocket connection and clean up resources
      */
     close() {
-      this.intentionalDisconnect = true;
-      this.reconnecting = false;
-      // Cancel any pending reconnect timer
-      if (this.reconnectTimer) {
-        clearTimeout(this.reconnectTimer);
-        this.reconnectTimer = null;
-      }
-
       if (this.heartbeat) {
         clearInterval(this.heartbeat);
         this.heartbeat = null;
       }
 
-      // Clear all pending message timeouts to prevent timers keeping the process alive
-      for (const timeoutId of this.pendingTimeouts.values()) {
-        clearTimeout(timeoutId);
-      }
-      this.pendingTimeouts.clear();
-
       if (this.socket) {
-        // Remove all listeners before closing to prevent reconnect attempts
         this.socket.removeAllListeners();
         try {
           this.socket.close();
@@ -549,11 +345,7 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       this.authenticated = false;
       this.instance = null;
       this._lastConnectParams = null;
-
-      // Silently clear pending promises and retry queue without rejecting
-      // (rejecting causes unhandled promise rejections during cleanup)
       this.ps = {};
-      this.pendingRetryQueue = [];
     }
   }
 

package/ai/agents/testdriver.md

@@ -621,7 +621,7 @@ await testdriver.screenshot(1, false, true);
 3. **⚠️ SHARE THE TEST REPORT URL** - After EVERY test run, find `TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/...` in the output and share it with the user. This is CRITICAL - users need to view the recording to understand what happened.
 3. **Screenshots are automatic** - TestDriver captures screenshots before/after every command by default. Each screenshot filename includes the line number (e.g., `001-click-before-L42-submit-button.png`) making it easy to trace issues.
 4. **⚠️ USE SCREENSHOT VIEWING FOR DEBUGGING** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` MCP commands to see exactly what the UI looked like. The filenames tell you which line of code triggered each screenshot.
-5. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
+5. **Use `wait()` for simple delays** - Use `await testdriver.wait(ms)` when you need a pause (e.g., after actions, for animations). For waiting for specific elements, prefer `find()` with a `timeout` option.
 6. **Use MCP tools for development** - Build tests interactively with visual feedback
 7. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
 8. **Look at test samples** in `node_modules/testdriverai/test` for working examples

package/ai/skills/testdriver:performing-actions/SKILL.md

@@ -29,6 +29,9 @@ await testdriver.find('dropdown menu').hover();
 await testdriver.scroll('down', 500);
 await testdriver.scrollUntilText('Footer content');
 
+// Waiting
+await testdriver.wait(2000); // Wait 2 seconds for animation/state change
+
 // Extracting information from screen
 const price = await testdriver.extract('the total price');
 const orderNumber = await testdriver.extract('the order confirmation number');

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

@@ -611,7 +611,7 @@ await testdriver.screenshot(1, false, true);
 3. **⚠️ SHARE THE TEST REPORT URL** - After EVERY test run, find `TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/...` in the output and share it with the user. This is CRITICAL - users need to view the recording to understand what happened.
 3. **Screenshots are automatic** - TestDriver captures screenshots before/after every command by default. Each screenshot filename includes the line number (e.g., `001-click-before-L42-submit-button.png`) making it easy to trace issues.
 4. **⚠️ USE SCREENSHOT VIEWING FOR DEBUGGING** - When tests fail, use `list_local_screenshots` and `view_local_screenshot` MCP commands to see exactly what the UI looked like. The filenames tell you which line of code triggered each screenshot.
-5. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
+5. **Use `wait()` for simple delays** - Use `await testdriver.wait(ms)` when you need a pause (e.g., after actions, for animations). For waiting for specific elements, prefer `find()` with a `timeout` option.
 6. **Use MCP tools for development** - Build tests interactively with visual feedback
 7. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
 8. **Look at test samples** in `node_modules/testdriverai/test` for working examples

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

@@ -70,3 +70,19 @@ const testdriver = TestDriver(context, {
   }
 });
 ```
+
+## Simple Delays with `wait()`
+
+For simple pauses — waiting for animations, transitions, or state changes after an action — use `wait()`:
+
+```javascript
+// Wait for an animation to complete
+await testdriver.find('menu toggle').click();
+await testdriver.wait(2000);
+
+// Wait for a page transition to settle
+await testdriver.find('next page button').click();
+await testdriver.wait(1000);
+```
+
+For waiting for specific **elements** to appear, prefer `find()` with a `timeout` option. Use `wait()` only for simple time-based pauses.

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

@@ -1,10 +1,30 @@
 # Best Practices: Element Polling
 
-**⚠️ CRITICAL: Never use `wait()` for waiting for elements to appear.**
+**When waiting for elements to appear, prefer `find()` with a `timeout` option over `wait()`.**
 
-## Why Avoid `wait()`?
+## When to Use `wait()` vs `find()` with Timeout
 
-Arbitrary waits with `wait()` have several problems:
+`wait()` is useful for **simple pauses** — after actions, for animations, or for state changes to settle:
+
+```javascript
+await testdriver.find('submit button').click();
+await testdriver.wait(2000); // Wait for animation to complete
+```
+
+However, **don't use `wait()` to wait for elements to appear**. For that, use `find()` with a `timeout`:
+
+```javascript
+// ✅ GOOD: Polls until the element appears (up to 30s)
+const element = await testdriver.find('success message', { timeout: 30000 });
+
+// ❌ BAD: Arbitrary wait then hope the element is there
+await testdriver.wait(5000);
+const element = await testdriver.find('success message');
+```
+
+## Why Prefer `find()` with Timeout for Element Waiting?
+
+Using arbitrary waits for element detection has problems:
 
 1. **Brittle**: Fixed timeouts may be too short (causing flaky tests) or too long (wasting time)
 2. **Slow**: You always wait the full duration, even if the element appears sooner
@@ -147,8 +167,8 @@ await waitForElement(testdriver, "Processing complete indicator", 10, 2000);
 | Pattern | Use Case |
 |---------|----------|
 | **Polling with `find()`** | ✅ Waiting for UI elements to appear or disappear |
-| **`wait()`** | ❌ NEVER use for element waiting |
+| **`wait()`** | ✅ Simple delays (animations, state changes) — ❌ Don't use for element waiting |
 | **Helper function** | ✅ Recommended for cleaner, reusable code |
 | **Conditional polling** | ✅ For optional elements (dialogs, notifications) |
 
-Remember: **If you're waiting for something to appear on screen, use `find()` in a polling loop, not `wait()`.**
+Remember: **If you're waiting for something to appear on screen, use `find()` with a `timeout` option, not `wait()`. Use `wait()` for simple pauses between actions.**

package/docs/v7/performing-actions.mdx

@@ -29,6 +29,9 @@ await testdriver.find('dropdown menu').hover();
 await testdriver.scroll('down', 500);
 await testdriver.scrollUntilText('Footer content');
 
+// Waiting
+await testdriver.wait(2000); // Wait 2 seconds for animation/state change
+
 // Extracting information from screen
 const price = await testdriver.extract('the total price');
 const orderNumber = await testdriver.extract('the order confirmation number');

package/docs/v7/wait.mdx

@@ -0,0 +1,52 @@
+---
+title: "wait"
+sidebarTitle: "wait"
+description: "Pause the execution of the script for a specified duration."
+icon: "clock"
+"mode": "wide"
+---
+
+## Description
+
+The `wait` method pauses test execution for a specified number of milliseconds before continuing. This is useful for adding delays between actions, waiting for animations to complete, or pausing for state changes to settle.
+
+## Syntax
+
+```javascript
+await testdriver.wait(timeout);
+```
+
+## Arguments
+
+| Argument  | Type     | Default | Description                           |
+| --------- | -------- | ------- | ------------------------------------- |
+| `timeout` | `number` | `3000`  | The duration in milliseconds to wait. |
+
+## Examples
+
+```javascript
+// Wait 2 seconds for an animation to complete
+await testdriver.find('submit button').click();
+await testdriver.wait(2000);
+
+// Wait 5 seconds
+await testdriver.wait(5000);
+
+// Wait with default timeout (3 seconds)
+await testdriver.wait();
+```
+
+## Best Practices
+
+- **Use for simple delays** — waiting for animations, transitions, or state changes after an action.
+- **Avoid for element waiting** — if you're waiting for a specific element to appear, use `find()` with a `timeout` option instead:
+  ```javascript
+  // ✅ Better for waiting for elements
+  const element = await testdriver.find('success message', { timeout: 30000 });
+
+  // ❌ Don't do this for element waiting
+  await testdriver.wait(5000);
+  const element = await testdriver.find('success message');
+  ```
+- Avoid excessively long timeouts to keep tests efficient.
+- Use sparingly — TestDriver's [redraw detection](/v7/waiting-for-elements) automatically waits for screen and network stability after each action.

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

@@ -70,3 +70,21 @@ const testdriver = TestDriver(context, {
   }
 });
 ```
+
+## Simple Delays with `wait()`
+
+For simple pauses — waiting for animations, transitions, or state changes after an action — use `wait()`:
+
+```javascript
+// Wait for an animation to complete
+await testdriver.find('menu toggle').click();
+await testdriver.wait(2000);
+
+// Wait for a page transition to settle
+await testdriver.find('next page button').click();
+await testdriver.wait(1000);
+```
+
+<Note>
+  For waiting for specific **elements** to appear, prefer `find()` with a `timeout` option. Use `wait()` only for simple time-based pauses.
+</Note>

package/examples/chrome-extension.test.mjs

@@ -60,6 +60,8 @@ describe("Chrome Extension Test", () => {
     const helloExtension = await testdriver.find("Hello Extensions extension in the extensions dropdown");
     await helloExtension.click();
 
+    await testdriver.wait(2000); // wait for the popup to open
+
     // Verify the extension popup shows "Hello Extensions" text
     const popupResult = await testdriver.assert("a popup shows with the text 'Hello Extensions'");
     expect(popupResult).toBeTruthy();

package/examples/no-provision.test.mjs

@@ -10,6 +10,8 @@ import { getDefaults } from "./config.mjs";
 describe("Assert Test", () => {
   it("should assert the testdriver login page shows", async (context) => {
     const testdriver = TestDriver(context, { ...getDefaults(context) });
+
+    await testdriver.wait(10000)
     
     // Assert the TestDriver.ai Sandbox login page is displayed
     const result = await testdriver.assert(

package/package.json

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

package/sdk.d.ts

@@ -1408,10 +1408,22 @@ export default class TestDriverSDK {
   parse(): Promise<ParseResult>;
 
   /**
-   * Wait for specified time
-   * @deprecated Consider using element polling with find() instead of arbitrary waits
+   * Wait for specified time. Useful for adding delays between actions, waiting for
+   * animations to complete, or pausing for state changes to settle.
+   *
+   * For waiting for specific elements to appear, prefer `find()` with a `timeout` option instead.
+   *
    * @param timeout - Time to wait in milliseconds (default: 3000)
    * @param options - Additional options (reserved for future use)
+   *
+   * @example
+   * // Wait 2 seconds for an animation to complete
+   * await testdriver.wait(2000);
+   *
+   * @example
+   * // Wait after a click for state to settle
+   * await testdriver.find('submit button').click();
+   * await testdriver.wait(1000);
    */
   wait(timeout?: number, options?: object): Promise<void>;