testdriverai 7.2.50 → 7.2.52

package/agents.md

@@ -88,11 +88,11 @@ The SDK has TypeScript types in `sdk.d.ts`. Key methods:
 |--------|---------|
 | `find(description)` | Find element by natural language |
 | `findAll(description)` | Find all matching elements |
-| `assert(assertion)` | AI-powered assertion |
-| `type(text)` | Type text |
+| `assert(assertion)` | AI-powered assertion || `screenshot()` | Capture and save screenshot locally || `type(text)` | Type text |
 | `pressKeys([keys])` | Press keyboard keys |
 | `scroll(direction)` | Scroll the page |
 | `exec(language, code)` | Execute code in sandbox |
+| `screenshot(scale, silent, mouse)` | Capture screenshot as base64 PNG |
 | `ai(task)` | AI exploratory loop (see note below) |
 
 ### About `ai()` - Use for Exploration, Not Final Tests
@@ -146,6 +146,39 @@ await element.mouseUp();      // release mouse
 element.found();              // check if found (boolean)
 ```
 
+### Screenshots for Debugging
+
+**Use `screenshot()` liberally during development** to see exactly what the sandbox screen looks like. Screenshots are saved locally and organized by test file.
+
+```javascript
+// Capture a screenshot - saved to .testdriverai/screenshots/<test-file>/
+const screenshotPath = await testdriver.screenshot();
+console.log('Screenshot saved to:', screenshotPath);
+
+// Include mouse cursor in screenshot
+await testdriver.screenshot(1, false, true);
+```
+
+**When to use screenshots:**
+- After `provision.chrome()` to verify the page loaded correctly
+- Before/after clicking elements to see state changes
+- When a `find()` fails to see what the AI is actually seeing
+- Before `assert()` calls to debug assertion failures
+- When tests behave unexpectedly
+
+**Screenshot file organization:**
+```
+.testdriverai/
+  screenshots/
+    login.test/           # Folder per test file
+      screenshot-1737633600000.png
+      screenshot-1737633605000.png
+    checkout.test/
+      screenshot-1737633700000.png
+```
+
+> **Note:** The screenshot folder for each test file is automatically cleared when the test starts, so you only see screenshots from the most recent run.
+
 ## Best Workflow: Two-File Pattern
 
 **The most efficient workflow for building tests uses two files.** This prevents having to restart from scratch when experimenting with new steps.
@@ -308,6 +341,9 @@ it("should incrementally build test", async (context) => {
   const testdriver = TestDriver(context);
   await testdriver.provision.chrome({ url: 'https://example.com' });
 
+  // Take a screenshot to see the initial state
+  await testdriver.screenshot();
+
   // Step 1: Find and inspect
   const element = await testdriver.find("Some button");
   console.log("Element found:", element.found());
@@ -317,6 +353,9 @@ it("should incrementally build test", async (context) => {
   // Step 2: Interact
   await element.click();
   
+  // Screenshot after interaction to see the result
+  await testdriver.screenshot();
+  
   // Step 3: Assert and log
   const result = await testdriver.assert("Something happened");
   console.log("Assertion result:", result);
@@ -382,6 +421,20 @@ const output = await testdriver.exec("sh", "ls -la", 5000);
 const date = await testdriver.exec("pwsh", "Get-Date", 5000);
 ```
 
+### Capturing Screenshots
+```javascript
+// Capture a screenshot and save to file
+const screenshot = await testdriver.screenshot();
+const filepath = 'screenshot.png';
+fs.writeFileSync(filepath, Buffer.from(screenshot, 'base64'));
+console.log('Screenshot saved to:', filepath);
+
+// Capture with mouse cursor visible
+const screenshotWithMouse = await testdriver.screenshot(1, false, true);
+fs.writeFileSync('screenshot-with-mouse.png', Buffer.from(screenshotWithMouse, 'base64'));
+console.log('Screenshot with mouse saved to: screenshot-with-mouse.png');
+```
+
 ## Tips for Agents
 
 1. **Always check `sdk.d.ts`** for method signatures and types
@@ -390,3 +443,13 @@ const date = await testdriver.exec("pwsh", "Get-Date", 5000);
 4. **Log element properties** to understand what the AI sees
 5. **Use `assert()` with specific, descriptive natural language**
 6. **Start simple** - get one step working before adding more
+7. **Take screenshots liberally** - use `await testdriver.screenshot()` after key steps to debug what the sandbox actually shows. Check `.testdriverai/screenshots/<test-file>/` to review them.
+8. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
+   ```json
+   // eslint.config.js (for TypeScript projects)
+   {
+     "rules": {
+       "@typescript-eslint/no-floating-promises": "error"
+     }
+   }
+   ```

package/docs/docs.json

@@ -82,6 +82,7 @@
                   "/v7/mouse-up",
                   "/v7/press-keys",
                   "/v7/right-click",
+                  "/v7/screenshot",
                   "/v7/type",
                   "/v7/scroll"
                 ]

package/docs/v7/device-config.mdx

@@ -120,7 +120,6 @@ describe("Chrome Extension Test", () => {
     const testdriver = TestDriver(context);
 
     // Clone extension from GitHub
-    await testdriver.ready();
     await testdriver.exec(
       'sh',
       'git clone https://github.com/user/my-extension.git /tmp/my-extension',
@@ -284,7 +283,6 @@ describe("VS Code Test", () => {
     const testdriver = TestDriver(context);
 
     // Create a test project
-    await testdriver.ready();
     await testdriver.exec('sh', 'mkdir -p /tmp/test-project && echo "print(1)" > /tmp/test-project/test.py', 10000);
 
     // Launch VS Code

package/docs/v7/screenshot.mdx

@@ -0,0 +1,151 @@
+---
+title: "screenshot()"
+sidebarTitle: "screenshot"
+description: "Capture and save screenshots during test execution"
+icon: "camera"
+---
+
+## Overview
+
+Capture a screenshot of the current screen and automatically save it to a local file. Screenshots are organized by test file for easy debugging and review.
+
+## Syntax
+
+```javascript
+const filePath = await testdriver.screenshot(scale, silent, mouse)
+```
+
+## Parameters
+
+<ParamField path="scale" type="number" default="1">
+  Scale factor for the screenshot (1 = original size, 0.5 = half size, 2 = double size)
+</ParamField>
+
+<ParamField path="silent" type="boolean" default="false">
+  Whether to suppress the log message showing where the screenshot was saved
+</ParamField>
+
+<ParamField path="mouse" type="boolean" default="false">
+  Whether to include the mouse cursor in the screenshot
+</ParamField>
+
+## Returns
+
+`Promise<string>` - The absolute file path where the screenshot was saved
+
+## File Organization
+
+Screenshots are automatically saved to `.testdriverai/screenshots/<test-file-name>/` in your project root:
+
+```
+.testdriverai/
+  screenshots/
+    login.test/
+      screenshot-1737633600000.png
+      screenshot-1737633605000.png
+    checkout.test/
+      screenshot-1737633700000.png
+```
+
+<Note>
+  The screenshot folder for each test file is automatically cleared when the test starts. This ensures you only see screenshots from the most recent test run.
+</Note>
+
+## Examples
+
+### Basic Screenshot
+
+```javascript
+// Capture a screenshot with default settings
+const screenshotPath = await testdriver.screenshot();
+console.log('Screenshot saved to:', screenshotPath);
+```
+
+### Screenshot with Mouse Cursor
+
+```javascript
+// Capture a screenshot showing the mouse cursor position
+const screenshotPath = await testdriver.screenshot(1, false, true);
+```
+
+### Silent Screenshot
+
+```javascript
+// Capture without logging the save location
+await testdriver.screenshot(1, true);
+```
+
+### Debugging with Screenshots
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+
+describe("Login Flow", () => {
+  it("should log in successfully", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({
+      url: 'https://myapp.com/login',
+    });
+
+    // Capture initial state
+    await testdriver.screenshot();
+
+    // Fill in login form
+    const emailInput = await testdriver.find("email input");
+    await emailInput.click();
+    await testdriver.type("user@example.com");
+
+    // Capture state after typing
+    await testdriver.screenshot();
+
+    const passwordInput = await testdriver.find("password input");
+    await passwordInput.click();
+    await testdriver.type("password123");
+
+    // Capture before clicking login
+    await testdriver.screenshot();
+
+    const loginButton = await testdriver.find("Login button");
+    await loginButton.click();
+
+    // Capture after login attempt
+    await testdriver.screenshot();
+
+    const result = await testdriver.assert("dashboard is visible");
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Use screenshots for debugging flaky tests">
+    When a test fails intermittently, add screenshots at key steps to capture the actual screen state. This helps identify timing issues or unexpected UI states.
+  </Accordion>
+
+  <Accordion title="Capture before assertions">
+    Take a screenshot before making assertions. If the assertion fails, you'll have a visual record of what the screen looked like.
+    
+    ```javascript
+    await testdriver.screenshot();
+    const result = await testdriver.assert("checkout button is visible");
+    ```
+  </Accordion>
+
+  <Accordion title="Add to .gitignore">
+    Add `.testdriverai/screenshots/` to your `.gitignore` to avoid committing screenshots to version control:
+    
+    ```
+    # .gitignore
+    .testdriverai/screenshots/
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [assert()](/v7/assert) - Make AI-powered assertions
+- [find()](/v7/find) - Locate elements on screen

package/eslint.config.js

@@ -45,6 +45,12 @@ module.exports = [
         ...globals.node,
       },
     },
+    rules: {
+      // Warn about floating promises (unawaited async calls)
+      // This catches missing `await` on async methods like click(), assert(), etc.
+      // Note: For TypeScript projects, use @typescript-eslint/no-floating-promises instead
+      "require-await": "warn",
+    },
   },
   {
     // this needs to be it's own object for some reason

package/examples/assert.test.mjs

@@ -17,6 +17,9 @@ describe("Assert Test", () => {
       url: 'http://testdriver-sandbox.vercel.app/login',
     });
 
+    // Take a screenshot
+    await testdriver.screenshot();
+
     // Assert the TestDriver.ai Sandbox login page is displayed
     const result = await testdriver.assert(
       "the TestDriver.ai Sandbox login page is displayed",

package/examples/chrome-extension.test.mjs

@@ -17,9 +17,6 @@ describe("Chrome Extension Test", () => {
 
     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();
-    
     // Determine OS-specific paths and commands
     const shell = testdriver.os === 'windows' ? 'pwsh' : 'sh';
     const extensionsDir = testdriver.os === 'windows' 

package/examples/no-provision.test.mjs

@@ -0,0 +1,23 @@
+/**
+ * TestDriver SDK - Assert Test (Vitest)
+ * Converted from: testdriver/acceptance/assert.yaml
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Assert Test", () => {
+  it("should assert the testdriver login page shows", async (context) => {
+    const testdriver = TestDriver(context, {
+      ip: context.ip || process.env.TD_IP,
+    });
+    
+    // Assert the TestDriver.ai Sandbox login page is displayed
+    const result = await testdriver.assert(
+      "A desktop is visible",
+    );
+
+    expect(result).toBeTruthy();
+  });
+});
+

package/lib/vitest/hooks.mjs

@@ -9,7 +9,6 @@
  * test('my test', async (context) => {
  *   const testdriver = TestDriver(context, { headless: true });
  *   
- *   await testdriver.ready();
  *   await testdriver.provision.chrome({ url: 'https://example.com' });
  *   await testdriver.find('button').click();
  * });
@@ -254,46 +253,50 @@ export function TestDriver(context, options = {}) {
   // Pass test file name to SDK for debugger display
   testdriver.testFile = testFile;
   
-  // Auto-connect if enabled (default: true)
-  const autoConnect = config.autoConnect !== undefined ? config.autoConnect : true;
   const debugConsoleSpy = process.env.TD_DEBUG_CONSOLE_SPY === 'true';
   
-  if (autoConnect) {
-    testdriver.__connectionPromise = (async () => {
-        if (debugConsoleSpy) {
-          console.log('[DEBUG] Before auth - sandbox.instanceSocketConnected:', testdriver.sandbox?.instanceSocketConnected);
-        }
-        
-        await testdriver.auth();
-        await testdriver.connect();
-                
-        if (debugConsoleSpy) {
-          console.log('[DEBUG] After connect - sandbox.instanceSocketConnected:', testdriver.sandbox?.instanceSocketConnected);
-          console.log('[DEBUG] After connect - sandbox.send:', typeof testdriver.sandbox?.send);
-        }
-        
-        // Set up console spy using vi.spyOn (test-isolated)
-        setupConsoleSpy(testdriver, context.task.id);
-        
-        // Create the log file on the remote machine
-        const shell = testdriver.os === "windows" ? "pwsh" : "sh";
-        const logPath = testdriver.os === "windows" 
-          ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
-          : "/tmp/testdriver.log";
-        
-        const createLogCmd = testdriver.os === "windows"
-          ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
-          : `touch ${logPath}`;
-        
-        await testdriver.exec(shell, createLogCmd, 10000, true);
-        
-        // Add automatic log tracking when dashcam starts
-        // Store original start method
-
+  testdriver.__connectionPromise = (async () => {
+      if (debugConsoleSpy) {
+        console.log('[DEBUG] Before auth - sandbox.instanceSocketConnected:', testdriver.sandbox?.instanceSocketConnected);
+      }
+      
+      await testdriver.auth();
+      await testdriver.connect();
+      
+      // Clear the connection promise now that we're connected
+      // This prevents deadlock when exec() is called below (exec() lazy-awaits __connectionPromise)
+      testdriver.__connectionPromise = null;
+              
+      if (debugConsoleSpy) {
+        console.log('[DEBUG] After connect - sandbox.instanceSocketConnected:', testdriver.sandbox?.instanceSocketConnected);
+        console.log('[DEBUG] After connect - sandbox.send:', typeof testdriver.sandbox?.send);
+      }
+      
+      // Set up console spy using vi.spyOn (test-isolated)
+      setupConsoleSpy(testdriver, context.task.id);
+      
+      // Create the log file on the remote machine
+      const shell = testdriver.os === "windows" ? "pwsh" : "sh";
+      const logPath = testdriver.os === "windows" 
+        ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
+        : "/tmp/testdriver.log";
+      
+      const createLogCmd = testdriver.os === "windows"
+        ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
+        : `touch ${logPath}`;
+      
+      await testdriver.exec(shell, createLogCmd, 10000, true);
+      
+      // Only set up dashcam if enabled (default: true)
+      if (testdriver.dashcamEnabled) {
+        // Add testdriver log to dashcam tracking
         await testdriver.dashcam.addFileLog(logPath, "TestDriver Log");
+        
+        // Start dashcam recording (always, regardless of provision method)
+        await testdriver.dashcam.start();
+      }
 
     })();
-  }
   
   // Register cleanup handler with dashcam.stop()
   // We always register a new cleanup handler because on retry we need to clean up the new instance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.50",
+  "version": "7.2.52",
   "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

@@ -244,6 +244,8 @@ export interface TestDriverOptions {
   cacheKey?: string;
   /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists. */
   reconnect?: boolean;
+  /** Enable/disable Dashcam video recording (default: true) */
+  dashcam?: boolean;
   /** Redraw configuration for screen change detection */
   redraw?: boolean | {
     /** Enable redraw detection (default: true) */
@@ -810,6 +812,11 @@ export default class TestDriverSDK {
    */
   readonly dashcam: DashcamAPI;
 
+  /**
+   * Whether Dashcam recording is enabled (default: true)
+   */
+  readonly dashcamEnabled: boolean;
+
   /**
    * Wait for the sandbox to be ready
    * Called automatically by provision methods
@@ -1129,20 +1136,20 @@ export default class TestDriverSDK {
   // Utility Methods
 
   /**
-   * Capture a screenshot of the current screen
+   * Capture a screenshot of the current screen and save it to .testdriverai/screenshots
    * @param scale - Scale factor for the screenshot (default: 1 = original size)
    * @param silent - Whether to suppress logging (default: false)
    * @param mouse - Whether to include mouse cursor (default: false)
-   * @returns Base64 encoded PNG screenshot
+   * @returns The file path where the screenshot was saved
    *
    * @example
-   * // Capture a screenshot
-   * const screenshot = await client.screenshot();
-   * fs.writeFileSync('screenshot.png', Buffer.from(screenshot, 'base64'));
+   * // Capture a screenshot (saves to .testdriverai/screenshots)
+   * const screenshotPath = await client.screenshot();
+   * console.log('Screenshot saved to:', screenshotPath);
    *
    * @example
    * // Capture with mouse cursor visible
-   * const screenshot = await client.screenshot(1, false, true);
+   * const screenshotPath = await client.screenshot(1, false, true);
    */
   screenshot(
     scale?: number,

package/sdk.js

@@ -1258,6 +1258,9 @@ class TestDriverSDK {
     // Store reconnect preference from options
     this.reconnect = options.reconnect !== undefined ? options.reconnect : false;
 
+    // Store dashcam preference (default: true)
+    this.dashcamEnabled = options.dashcam !== false;
+
     // Cache threshold configuration
     // threshold = pixel difference allowed (0.05 = 5% difference, 95% similarity)
     // By default, cache is DISABLED (threshold = -1) to avoid unnecessary AI costs
@@ -1333,6 +1336,13 @@ class TestDriverSDK {
 
     // Set up dashcam API lazily
     this._dashcam = null;
+
+    // Last-promise tracking for unawaited promise detection
+    this._lastPromiseSettled = true;
+    this._lastCommandName = null;
+
+    // Set up command methods that lazy-await connection
+    this._setupCommandMethods();
   }
 
   /**
@@ -1344,19 +1354,36 @@ class TestDriverSDK {
       await this.__connectionPromise;
     }
     if (!this.connected) {
-      throw new Error('Not connected to sandbox. Call connect() first or use autoConnect option.');
+      throw new Error('Not connected to sandbox. Call connect() first.');
     }
   }
 
   /**
    * Get or create the Dashcam instance
-   * @returns {Dashcam} Dashcam instance
+   * @returns {Dashcam} Dashcam instance (or no-op stub if dashcam is disabled)
    */
   get dashcam() {
     if (!this._dashcam) {
-      const { Dashcam } = require("./lib/core/index.js");
-      // Don't pass apiKey - let Dashcam use its default key
-      this._dashcam = new Dashcam(this);
+      // If dashcam is disabled, return a no-op stub
+      if (!this.dashcamEnabled) {
+        this._dashcam = {
+          start: async () => {},
+          stop: async () => null,
+          auth: async () => {},
+          addFileLog: async () => {},
+          addWebLog: async () => {},
+          addApplicationLog: async () => {},
+          addLog: async () => {},
+          isRecording: async () => false,
+          getElapsedTime: () => null,
+          recording: false,
+          url: null,
+        };
+      } else {
+        const { Dashcam } = require("./lib/core/index.js");
+        // Don't pass apiKey - let Dashcam use its default key
+        this._dashcam = new Dashcam(this);
+      }
     }
     return this._dashcam;
   }
@@ -1406,40 +1433,16 @@ class TestDriverSDK {
        * @returns {Promise<void>}
        */
       chrome: async (options = {}) => {
-        // Automatically wait for connection to be ready
-        await this.ready();
-        
         const {
           url = 'http://testdriver-sandbox.vercel.app/',
           maximized = true,
           guest = false,
         } = options;
 
-        // If dashcam is available, add web logs for all websites using "**" pattern
+        // 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) {
-    
-            // Create the log file on the remote machine
-            const shell = this.os === "windows" ? "pwsh" : "sh";
-            const logPath = this.os === "windows" 
-            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
-            : "/tmp/testdriver.log";
-            
-            const createLogCmd = this.os === "windows"
-            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
-            : `touch ${logPath}`;
-            
-            await this.exec(shell, createLogCmd, 60000, true);
-          
-            // Track all websites by default with "**" pattern
-            await this._dashcam.addWebLog('**', 'Web Logs');
-
-            await this._dashcam.addFileLog(logPath, "TestDriver Log");
-
-        }
-        
-        // Automatically start dashcam if not already recording
-        if (!this._dashcam || !this._dashcam.recording) {
-          await this.dashcam.start();
+          await this._dashcam.addWebLog('**', 'Web Logs');
         }
 
         // Set up Chrome profile with preferences
@@ -1571,9 +1574,6 @@ class TestDriverSDK {
        * });
        */
       chromeExtension: async (options = {}) => {
-        // Automatically wait for connection to be ready
-        await this.ready();
-        
         const {
           extensionPath: providedExtensionPath,
           extensionId,
@@ -1694,27 +1694,10 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           console.log(`[provision.chromeExtension] Extension ${extensionId} extracted to ${extensionPath}`);
         }
 
-        // If dashcam is available, set up file and web logging
+        // 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) {
-          // Create the log file on the remote machine
-          const logPath = this.os === "windows" 
-            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
-            : "/tmp/testdriver.log";
-          
-          const createLogCmd = this.os === "windows"
-            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
-            : `touch ${logPath}`;
-          
-          await this.exec(shell, createLogCmd, 60000, true);
-          
-          // Track all websites by default with "**" pattern
           await this._dashcam.addWebLog('**', 'Web Logs');
-          await this._dashcam.addFileLog(logPath, "TestDriver Log");
-        }
-        
-        // Automatically start dashcam if not already recording
-        if (!this._dashcam || !this._dashcam.recording) {
-          await this.dashcam.start();
         }
 
         // Set up Chrome profile with preferences
@@ -1827,9 +1810,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        * @returns {Promise<void>}
        */
       vscode: async (options = {}) => {
-        // Automatically wait for connection to be ready
-        await this.ready();
-        
         const {
           workspace = null,
           extensions = [],
@@ -1837,27 +1817,10 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
         const shell = this.os === 'windows' ? 'pwsh' : 'sh';
 
-        // If dashcam is available, set up file and web logging
+        // 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) {
-          // Create the log file on the remote machine
-          const logPath = this.os === "windows" 
-            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
-            : "/tmp/testdriver.log";
-          
-          const createLogCmd = this.os === "windows"
-            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
-            : `touch ${logPath}`;
-          
-          await this.exec(shell, createLogCmd, 60000, true);
-          
-          // Track all websites by default with "**" pattern
           await this._dashcam.addWebLog('**', 'Web Logs');
-          await this._dashcam.addFileLog(logPath, "TestDriver Log");
-        }
-        
-        // Automatically start dashcam if not already recording
-        if (!this._dashcam || !this._dashcam.recording) {
-          await this.dashcam.start();
         }
 
         // Install extensions if provided
@@ -1920,9 +1883,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        * await testdriver.exec('sh', `chmod +x "${filePath}" && "${filePath}" &`, 10000);
        */
       installer: async (options = {}) => {
-        // Automatically wait for connection to be ready
-        await this.ready();
-        
         const {
           url,
           filename,
@@ -1936,26 +1896,10 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
         const shell = this.os === 'windows' ? 'pwsh' : 'sh';
 
-        // If dashcam is available, set up file and web logging
+        // 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) {
-          const logPath = this.os === "windows" 
-            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
-            : "/tmp/testdriver.log";
-          
-          const createLogCmd = this.os === "windows"
-            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
-            : `touch ${logPath}`;
-          
-          await this.exec(shell, createLogCmd, 60000, true);
-          
-          // Track all websites by default with "**" pattern
           await this._dashcam.addWebLog('**', 'Web Logs');
-          await this._dashcam.addFileLog(logPath, "TestDriver Log");
-        }
-        
-        // Automatically start dashcam if not already recording
-        if (!this._dashcam || !this._dashcam.recording) {
-          await this.dashcam.start();
         }
 
         // Determine download directory
@@ -2085,9 +2029,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        * @returns {Promise<void>}
        */
       electron: async (options = {}) => {
-        // Automatically wait for connection to be ready
-        await this.ready();
-        
         const { appPath, args = [] } = options;
         
         if (!appPath) {
@@ -2096,26 +2037,10 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
         const shell = this.os === 'windows' ? 'pwsh' : 'sh';
 
-        // If dashcam is available, set up file and web logging
+        // 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) {
-          const logPath = this.os === "windows" 
-            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
-            : "/tmp/testdriver.log";
-          
-          const createLogCmd = this.os === "windows"
-            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
-            : `touch ${logPath}`;
-          
-          await this.exec(shell, createLogCmd, 60000, true);
-          
-          // Track all websites by default with "**" pattern
           await this._dashcam.addWebLog('**', 'Web Logs');
-          await this._dashcam.addFileLog(logPath, "TestDriver Log");
-        }
-        
-        // Automatically start dashcam if not already recording
-        if (!this._dashcam || !this._dashcam.recording) {
-          await this.dashcam.start();
         }
 
         const argsString = args.join(' ');
@@ -2190,6 +2115,15 @@ 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(), ".testdriverai", "screenshots", testFileName);
+      if (fs.existsSync(screenshotsDir)) {
+        fs.rmSync(screenshotsDir, { recursive: true, force: true });
+      }
+    }
+
     // Authenticate first if not already authenticated
     if (!this.authenticated) {
       await this.auth();
@@ -2317,8 +2251,8 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     this.agent.commands = commandsResult.commands;
     this.agent.redraw = commandsResult.redraw;
 
-    // Dynamically create command methods based on available commands
-    this._setupCommandMethods();
+    // Command methods are already set up in constructor with lazy-await
+    // They will use this.commands which is now populated
 
     this.connected = true;
     this.analytics.track("sdk.connect", {
@@ -2408,9 +2342,33 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
    * await element.click();
    */
   find(description, options) {
-    this._ensureConnected();
-    const element = new Element(description, this, this.system, this.commands);
-    const findPromise = element.find(null, options);
+    // Wrap in async IIFE to support lazy-await and promise tracking
+    const findPromise = (async () => {
+      // Lazy-await: wait for connection if still pending
+      if (this.__connectionPromise) {
+        await this.__connectionPromise;
+      }
+
+      // Warn if previous command may not have been awaited
+      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.`
+        );
+      }
+
+      this._ensureConnected();
+
+      // Track this promise for unawaited detection
+      this._lastCommandName = 'find';
+      this._lastPromiseSettled = false;
+
+      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()
@@ -2440,8 +2398,26 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
    * }
    */
   async findAll(description, options) {
+    // Lazy-await: wait for connection if still pending
+    if (this.__connectionPromise) {
+      await this.__connectionPromise;
+    }
+
+    // Warn if previous command may not have been awaited
+    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.`
+      );
+    }
+
     this._ensureConnected();
 
+    // Track this promise for unawaited detection
+    this._lastCommandName = 'findAll';
+    this._lastPromiseSettled = false;
+
     // Capture absolute timestamp at the very start of the command
     // Frontend will calculate relative time using: timestamp - replay.clientStartDate
     const absoluteTimestamp = Date.now();
@@ -2589,6 +2565,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           this.emitter.emit(events.log.debug, `  Time: ${duration}ms`);
         }
 
+        this._lastPromiseSettled = true;
         return elements;
       } else {
         const duration = Date.now() - startTime;
@@ -2625,6 +2602,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         }
 
         // No elements found - return empty array
+        this._lastPromiseSettled = true;
         return [];
       }
     } catch (error) {
@@ -2657,6 +2635,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         });
       }
 
+      this._lastPromiseSettled = true;
       return [];
     }
   }
@@ -2706,251 +2685,74 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
    * @private
    */
   _setupCommandMethods() {
-    // Mapping from command names to SDK method names with type definitions
-    // Each command supports both positional args (legacy) and object args (new)
+    // Mapping from internal command names to SDK method names
     const commandMapping = {
-      "hover-text": {
-        name: "hoverText",
-        /**
-         * Hover over text on screen
-         * @deprecated Use find() and element.click() instead
-         * @param {Object|string} options - Options object or text (legacy positional)
-         * @param {string} options.text - Text to find and hover over
-         * @param {string|null} [options.description] - Optional description of the element
-         * @param {ClickAction} [options.action='click'] - Action to perform
-         * @param {number} [options.timeout=5000] - Timeout in milliseconds
-         * @returns {Promise<{x: number, y: number, centerX: number, centerY: number}>}
-         */
-        doc: "Hover over text on screen (deprecated - use find() instead)",
-      },
-      "hover-image": {
-        name: "hoverImage",
-        /**
-         * Hover over an image on screen
-         * @deprecated Use find() and element.click() instead
-         * @param {Object|string} options - Options object or description (legacy positional)
-         * @param {string} options.description - Description of the image to find
-         * @param {ClickAction} [options.action='click'] - Action to perform
-         * @returns {Promise<{x: number, y: number, centerX: number, centerY: number}>}
-         */
-        doc: "Hover over an image on screen (deprecated - use find() instead)",
-      },
-      "match-image": {
-        name: "matchImage",
-        /**
-         * Match and interact with an image template
-         * @param {Object|string} options - Options object or path (legacy positional)
-         * @param {string} options.path - Path to the image template
-         * @param {ClickAction} [options.action='click'] - Action to perform
-         * @param {boolean} [options.invert=false] - Invert the match
-         * @returns {Promise<boolean>}
-         */
-        doc: "Match and interact with an image template",
-      },
-      type: {
-        name: "type",
-        /**
-         * Type text
-         * @param {string|number} text - Text to type
-         * @param {Object} [options] - Additional options
-         * @param {number} [options.delay=250] - Delay between keystrokes in milliseconds
-         * @param {boolean} [options.secret=false] - If true, text is treated as sensitive (not logged or stored)
-         * @returns {Promise<void>}
-         */
-        doc: "Type text (use { secret: true } for passwords)",
-      },
-      "press-keys": {
-        name: "pressKeys",
-        /**
-         * Press keyboard keys
-         * @param {KeyboardKey[]} keys - Array of keys to press
-         * @param {Object} [options] - Additional options (reserved for future use)
-         * @returns {Promise<void>}
-         */
-        doc: "Press keyboard keys",
-      },
-      click: {
-        name: "click",
-        /**
-         * Click at coordinates
-         * @param {Object|number} options - Options object or x coordinate (legacy positional)
-         * @param {number} options.x - X coordinate
-         * @param {number} options.y - Y coordinate
-         * @param {ClickAction} [options.action='click'] - Type of click action
-         * @returns {Promise<void>}
-         */
-        doc: "Click at coordinates",
-      },
-      hover: {
-        name: "hover",
-        /**
-         * Hover at coordinates
-         * @param {Object|number} options - Options object or x coordinate (legacy positional)
-         * @param {number} options.x - X coordinate
-         * @param {number} options.y - Y coordinate
-         * @returns {Promise<void>}
-         */
-        doc: "Hover at coordinates",
-      },
-      scroll: {
-        name: "scroll",
-        /**
-         * Scroll the page
-         * @param {ScrollDirection} [direction='down'] - Direction to scroll
-         * @param {Object} [options] - Additional options
-         * @param {number} [options.amount=300] - Amount to scroll in pixels
-         * @returns {Promise<void>}
-         */
-        doc: "Scroll the page",
-      },
-      wait: {
-        name: "wait",
-        /**
-         * Wait for specified time
-         * @deprecated Consider using element polling with find() instead of arbitrary waits
-         * @param {number} [timeout=3000] - Time to wait in milliseconds
-         * @param {Object} [options] - Additional options (reserved for future use)
-         * @returns {Promise<void>}
-         */
-        doc: "Wait for specified time (deprecated - consider element polling instead)",
-      },
-      "wait-for-text": {
-        name: "waitForText",
-        /**
-         * Wait for text to appear on screen
-         * @deprecated Use find() in a polling loop instead
-         * @param {Object|string} options - Options object or text (legacy positional)
-         * @param {string} options.text - Text to wait for
-         * @param {number} [options.timeout=5000] - Timeout in milliseconds
-         * @returns {Promise<void>}
-         */
-        doc: "Wait for text to appear on screen (deprecated - use find() in a loop instead)",
-      },
-      "wait-for-image": {
-        name: "waitForImage",
-        /**
-         * Wait for image to appear on screen
-         * @deprecated Use find() in a polling loop instead
-         * @param {Object|string} options - Options object or description (legacy positional)
-         * @param {string} options.description - Description of the image
-         * @param {number} [options.timeout=10000] - Timeout in milliseconds
-         * @returns {Promise<void>}
-         */
-        doc: "Wait for image to appear on screen (deprecated - use find() in a loop instead)",
-      },
-      "scroll-until-text": {
-        name: "scrollUntilText",
-        /**
-         * Scroll until text is found
-         * @param {Object|string} options - Options object or text (legacy positional)
-         * @param {string} options.text - Text to find
-         * @param {ScrollDirection} [options.direction='down'] - Scroll direction
-         * @param {number} [options.maxDistance=10000] - Maximum distance to scroll in pixels
-         * @param {boolean} [options.invert=false] - Invert the match
-         * @returns {Promise<void>}
-         */
-        doc: "Scroll until text is found",
-      },
-      "scroll-until-image": {
-        name: "scrollUntilImage",
-        /**
-         * Scroll until image is found
-         * @param {Object|string} [options] - Options object or description (legacy positional)
-         * @param {string} [options.description] - Description of the image
-         * @param {ScrollDirection} [options.direction='down'] - Scroll direction
-         * @param {number} [options.maxDistance=10000] - Maximum distance to scroll in pixels
-         * @param {string} [options.method='mouse'] - Scroll method
-         * @param {string} [options.path] - Path to image template
-         * @param {boolean} [options.invert=false] - Invert the match
-         * @returns {Promise<void>}
-         */
-        doc: "Scroll until image is found",
-      },
-      "focus-application": {
-        name: "focusApplication",
-        /**
-         * Focus an application by name
-         * @param {string} name - Application name
-         * @param {Object} [options] - Additional options (reserved for future use)
-         * @returns {Promise<string>}
-         */
-        doc: "Focus an application by name",
-      },
-      extract: {
-        name: "extract",
-        /**
-         * Extract information from the screen using AI
-         * @param {Object|string} options - Options object or description (legacy positional)
-         * @param {string} options.description - What to extract
-         * @returns {Promise<string>}
-         */
-        doc: "Extract information from the screen",
-      },
-      assert: {
-        name: "assert",
-        /**
-         * Make an AI-powered assertion
-         * @param {string} assertion - Assertion to check
-         * @param {Object} [options] - Additional options (reserved for future use)
-         * @returns {Promise<boolean>}
-         */
-        doc: "Make an AI-powered assertion",
-      },
-      exec: {
-        name: "exec",
-        /**
-         * Execute code in the sandbox
-         * @param {Object|ExecLanguage} options - Options object or language (legacy positional)
-         * @param {ExecLanguage} [options.language='pwsh'] - Language ('js', 'pwsh', or 'sh')
-         * @param {string} options.code - Code to execute
-         * @param {number} [options.timeout] - Timeout in milliseconds
-         * @param {boolean} [options.silent=false] - Suppress output
-         * @returns {Promise<string>}
-         */
-        doc: "Execute code in the sandbox",
-      },
+      "hover-text": "hoverText",
+      "hover-image": "hoverImage",
+      "match-image": "matchImage",
+      "type": "type",
+      "press-keys": "pressKeys",
+      "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",
     };
 
-    // Create SDK methods dynamically from commands
-    Object.keys(this.commands).forEach((commandName) => {
-      const command = this.commands[commandName];
-      const methodInfo = commandMapping[commandName];
-
-      if (!methodInfo) {
-        // Skip commands not in mapping
-        return;
-      }
+    // Create SDK methods that lazy-await connection then forward to this.commands
+    for (const [commandName, methodName] of Object.entries(commandMapping)) {
+      this[methodName] = async function (...args) {
+        // Lazy-await: wait for connection if still pending
+        if (this.__connectionPromise) {
+          await this.__connectionPromise;
+        }
 
-      const methodName = methodInfo.name;
+        // Warn if previous command may not have been awaited
+        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.`
+          );
+        }
 
-      // Create the wrapper method with proper stack trace handling
-      this[methodName] = async function (...args) {
         this._ensureConnected();
 
         // Capture the call site for better error reporting
         const callSite = {};
         Error.captureStackTrace(callSite, this[methodName]);
 
+        // Track this promise for unawaited detection
+        this._lastCommandName = methodName;
+        this._lastPromiseSettled = false;
+
         try {
-          return await command(...args);
+          const result = await this.commands[commandName](...args);
+          this._lastPromiseSettled = true;
+          return result;
         } catch (error) {
+          this._lastPromiseSettled = true;
           // Ensure we have a proper Error object with a message
           let properError = error;
           if (!(error instanceof Error)) {
-            // If it's not an Error object, create one with a proper message
             const errorMessage =
               error?.message || error?.reason || JSON.stringify(error);
             properError = new Error(errorMessage);
-            // Preserve additional properties
             if (error?.code) properError.code = error.code;
             if (error?.fullError) properError.fullError = error.fullError;
           }
 
           // Replace the stack trace to point to the actual caller instead of SDK internals
           if (Error.captureStackTrace && callSite.stack) {
-            // Preserve the error message but use the captured call site stack
             const errorMessage = properError.stack?.split("\n")[0];
-            const callerStack = callSite.stack?.split("\n").slice(1); // Skip "Error" line
+            const callerStack = callSite.stack?.split("\n").slice(1);
             properError.stack = errorMessage + "\n" + callerStack.join("\n");
           }
           throw properError;
@@ -2962,7 +2764,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         value: methodName,
         writable: false,
       });
-    });
+    }
   }
 
   // ====================================
@@ -2970,24 +2772,49 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
   // ====================================
 
   /**
-   * Capture a screenshot of the current screen
+   * Capture a screenshot of the current screen and save it to .testdriverai/screenshots
    * @param {number} [scale=1] - Scale factor for the screenshot (1 = original size)
    * @param {boolean} [silent=false] - Whether to suppress logging
    * @param {boolean} [mouse=false] - Whether to include mouse cursor
-   * @returns {Promise<string>} Base64 encoded PNG screenshot
+   * @returns {Promise<string>} The file path where the screenshot was saved
    *
    * @example
-   * // Capture a screenshot
-   * const screenshot = await client.screenshot();
-   * fs.writeFileSync('screenshot.png', Buffer.from(screenshot, 'base64'));
+   * // Capture a screenshot (saves to .testdriverai/screenshots)
+   * const screenshotPath = await client.screenshot();
+   * console.log('Screenshot saved to:', screenshotPath);
    *
    * @example
    * // Capture with mouse cursor visible
-   * const screenshot = await client.screenshot(1, false, true);
+   * const screenshotPath = await client.screenshot(1, false, true);
    */
   async screenshot(scale = 1, silent = false, mouse = false) {
     this._ensureConnected();
-    return await this.system.captureScreenBase64(scale, silent, mouse);
+    const base64Data = await this.system.captureScreenBase64(scale, silent, mouse);
+    
+    // Save to .testdriverai/screenshots/<test-file-name> directory
+    let screenshotsDir = path.join(process.cwd(), ".testdriverai", "screenshots");
+    if (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 filename = `screenshot-${Date.now()}.png`;
+    const filePath = path.join(screenshotsDir, filename);
+    
+    // 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);
+    
+    if (!silent) {
+      this.emitter.emit("log:info", `📸 Screenshot saved to: ${filePath}`);
+    }
+    
+    return filePath;
   }
 
   /**

package/test/manual-unawaited-promise.test.mjs

@@ -0,0 +1,31 @@
+/**
+ * Manual test to verify unawaited promise detection
+ * 
+ * Run with: vitest run test/manual-unawaited-promise.test.mjs
+ * 
+ * Expected: You should see a warning like:
+ * ⚠️  Warning: Previous find() may not have been awaited.
+ */
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../lib/vitest/hooks.mjs";
+
+describe("Unawaited Promise Detection", () => {
+  it("should warn when a promise is not awaited", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({
+      url: 'https://example.com',
+    });
+
+    // INTENTIONALLY missing await - should trigger warning on next call
+    testdriver.find("some button");
+    
+    // This second call should print a warning about the previous unawaited find()
+    const element = await testdriver.find("Example Domain heading");
+    
+    console.log("Element found:", element.found());
+    
+    // If we got here without error and saw the warning, the feature works!
+    expect(true).toBeTruthy();
+  });
+});