testdriverai 7.2.9 → 7.2.10

package/docs/v7/{api/scroll.mdx → scroll.mdx}

@@ -295,6 +295,6 @@ describe('Scrolling', () => {
 
 ## Related Methods
 
-- [`find()`](/v7/api/find) - Locate elements after scrolling
-- [`pressKeys()`](/v7/api/pressKeys) - Use Page Down/Up keys
-- [`wait()`](/v7/api/wait) - Wait after scrolling
+- [`find()`](/v7/find) - Locate elements after scrolling
+- [`pressKeys()`](/v7/press-keys) - Use Page Down/Up keys
+- [`wait()`](/v7/wait) - Wait after scrolling

package/docs/v7/secrets.mdx

@@ -0,0 +1,115 @@
+---
+title: "Using Secrets"
+description: "Securely manage passwords and sensitive data in your tests"
+icon: "key"
+---
+
+Protect sensitive information like passwords, API keys, and tokens in your TestDriver tests.
+
+## Typing Secrets Securely
+
+When typing sensitive information like passwords, use the `secret: true` option to prevent the value from being logged or stored:
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('login with secure password', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: 'https://myapp.com/login' 
+  });
+
+  await testdriver.find('email input').click();
+  await testdriver.type(process.env.TD_USERNAME);
+  
+  await testdriver.find('password input').click();
+  // Password is masked in logs and recordings
+  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
+  
+  await testdriver.find('login button').click();
+  await testdriver.assert('dashboard is visible');
+});
+```
+
+<Note>
+When `secret: true` is set, the typed text appears as `****` in all logs, recordings, and dashcam output.
+</Note>
+
+## Storing Secrets in GitHub
+
+Store sensitive credentials as GitHub repository secrets so they're never exposed in your code:
+
+<Steps>
+  <Step title="Navigate to Repository Settings">
+    Go to your GitHub repository → **Settings** → **Secrets and variables** → **Actions**
+  </Step>
+  <Step title="Add Repository Secrets">
+    Click **New repository secret** and add your secrets:
+    - `TD_API_KEY` - Your TestDriver API key
+    - `TD_USERNAME` - Test account username
+    - `TD_PASSWORD` - Test account password
+  </Step>
+  <Step title="Use in GitHub Actions">
+    Reference secrets in your workflow file:
+    ```yaml .github/workflows/test.yml
+    - name: Run TestDriver tests
+      env:
+        TD_API_KEY: ${{ secrets.TD_API_KEY }}
+        TD_USERNAME: ${{ secrets.TD_USERNAME }}
+        TD_PASSWORD: ${{ secrets.TD_PASSWORD }}
+      run: npx vitest run
+    ```
+  </Step>
+</Steps>
+
+## Local Development
+
+For local development, store secrets in a `.env` file:
+
+```bash .env
+TD_API_KEY=your_api_key_here
+TD_USERNAME=testuser@example.com
+TD_PASSWORD=your_secure_password
+```
+
+<Warning>
+Never commit `.env` files to version control. Add `.env` to your `.gitignore` file.
+</Warning>
+
+## Complete Example
+
+Here's a full login test with proper secrets handling:
+
+```javascript tests/login.test.js
+import { test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('secure login flow', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: process.env.TD_WEBSITE || 'https://staging.myapp.com'
+  });
+
+  // Enter username (not sensitive)
+  await testdriver.find('email input').click();
+  await testdriver.type(process.env.TD_USERNAME);
+  
+  // Enter password securely
+  await testdriver.find('password input').click();
+  await testdriver.type(process.env.TD_PASSWORD, { secret: true });
+  
+  // Submit login
+  await testdriver.find('login button').click();
+  
+  // Verify successful login
+  const loggedIn = await testdriver.assert('user is logged in');
+  expect(loggedIn).toBeTruthy();
+});
+```
+
+<Card title="Secrets Best Practices" icon="shield-check">
+  - **Always use `secret: true`** when typing passwords, tokens, or sensitive data
+  - **Use environment variables** to keep secrets out of code
+  - **Store secrets in your CI provider** (GitHub Actions, GitLab CI, etc.)
+  - **Never commit secrets** to version control
+  - **Rotate secrets regularly** to maintain security
+</Card>

package/docs/v7/self-hosted.mdx

@@ -0,0 +1,66 @@
+---
+title: "Self-Hosted"
+sidebarTitle: "Self-Hosted"
+description: "Unlimited test execution, complete privacy, and the ability to customize everything — all for a predictable flat license fee."
+icon: "server"
+---
+
+Self-hosted pricing is based on **parallel test capacity**: the number of tests you can run simultaneously on **your infrastructure**. 
+
+With self-hosting, you get:.
+
+- **Flat license fee** per parallel test slot
+- **Unlimited test execution** — run as many tests as you want
+- **No device-second metering** — predictable monthly costs
+- **Use your own AI keys** — control data usage with your own OpenAI, Anthropic, or other AI provider keys
+- **Custom hardware & software** — choose instance types, resolution, install specific software, and configure networking as needed
+- **Debug & Customize** — RDP into test machines, install custom software, modify the AMI, and debug issues directly. No black boxes.
+
+## Get Started
+
+Ready to self-host? Follow our comprehensive AWS setup guide:
+
+<Card
+  title="AWS Setup Guide"
+  icon="aws"
+  href="/v7/aws-setup"
+>
+  Step-by-step instructions for deploying TestDriver on your AWS infrastructure using CloudFormation.
+</Card>
+
+
+## Who Should Self-Host?
+
+Self-hosting is ideal for teams that:
+
+- **Run high test volumes** — Flat pricing becomes more economical at scale
+- **Want infrastructure control** — Custom hardware, specific software dependencies, or network configurations
+- **Prefer predictable costs** — Budget with confidence using flat monthly fees
+
+
+## How It Works
+
+With self-hosting, you run test sandboxes on your own AWS infrastructure. TestDriver still provides:
+
+- **Dashboard** — View test results, analytics, and reports at [console.testdriver.ai](https://console.testdriver.ai)
+- **API** — Orchestration and AI-powered test execution
+- **License Management** — Your parallel test capacity
+
+You provide:
+
+- **AWS Infrastructure** — EC2 instances running in your account
+- **AI API Keys** — Use your own OpenAI, Anthropic, or other AI provider keys
+- **Custom Configuration** — Hardware specs, networking, installed software
+
+## Comparison vs Cloud
+
+| Feature | Cloud | Self-Hosted |
+|---------|-------|-------------|
+| **Setup Time** | Minutes | Hours |
+| **Pricing Model** | Device-seconds | Flat license fee |
+| **Infrastructure Management** | TestDriver | You |
+| **Device Location** | TestDriver cloud | Your AWS account |
+| **AI API Keys** | TestDriver's | Your own |
+| **Custom Software** | Limited | Full control |
+| **Hardware Selection** | Standard | Your choice |
+| **Debugging Access** | Replays only | Full RDP access |

package/docs/v7/{api/type.mdx → type.mdx}

@@ -353,6 +353,6 @@ describe('Form Filling with Type', () => {
 
 ## Related Methods
 
-- [`pressKeys()`](/v7/api/pressKeys) - Press keyboard keys and shortcuts
-- [`find()`](/v7/api/find) - Locate input fields
-- [`click()`](/v7/api/click) - Focus input fields
+- [`pressKeys()`](/v7/press-keys) - Press keyboard keys and shortcuts
+- [`find()`](/v7/find) - Locate input fields
+- [`click()`](/v7/click) - Focus input fields

package/docs/v7/variables.mdx

@@ -0,0 +1,111 @@
+---
+title: "Using Variables"
+description: "Use dynamic data and secure secrets in your tests"
+icon: "square-root-variable"
+---
+
+Scale your testing with dynamic data and secure secrets management. Choose the right approach based on your testing needs.
+
+## Environment Variables
+
+Environment variables are ideal for **configuration that changes between environments** (dev, staging, production) or for **secrets that shouldn't be committed to code**. Use this approach when you need to run the same tests against different servers or with different credentials.
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('multi-environment testing', async (context) => {
+  const env = process.env.TEST_ENV || 'staging';
+  const urls = {
+    dev: 'https://dev.myapp.com',
+    staging: 'https://staging.myapp.com',
+    production: 'https://myapp.com'
+  };
+
+  const { testdriver } = await chrome(context, { 
+    url: urls[env] 
+  });
+
+  await testdriver.assert('app is running');
+});
+```
+
+```bash
+# Run against different environments
+TEST_ENV=dev npx vitest run
+TEST_ENV=staging npx vitest run
+TEST_ENV=production npx vitest run
+```
+
+## Test Fixtures
+
+Test fixtures work best when you have **structured, reusable test data** that needs to be shared across multiple tests. Use fixtures when testing different user roles, product catalogs, or any scenario where you want to parameterize tests with a known set of data.
+
+```javascript test/fixtures/users.js
+export const testUsers = [
+  { email: 'admin@test.com', role: 'admin' },
+  { email: 'user@test.com', role: 'user' },
+  { email: 'guest@test.com', role: 'guest' }
+];
+
+export const products = [
+  { name: 'Laptop', price: 999 },
+  { name: 'Mouse', price: 29 },
+  { name: 'Keyboard', price: 89 }
+];
+```
+
+```javascript test/permissions.test.js
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+import { testUsers } from './fixtures/users.js';
+
+test.each(testUsers)('$role can access dashboard', async ({ email, role }, context) => {
+  const { testdriver } = await chrome(context, { url });
+  
+  await testdriver.find('email input').type(email);
+  await testdriver.find('password input').type('password123');
+  await testdriver.find('login button').click();
+  
+  if (role === 'admin') {
+    await testdriver.assert('admin panel is visible');
+  } else {
+    await testdriver.assert('user dashboard is visible');
+  }
+});
+```
+
+## Dynamic Data Generation
+
+Dynamic data generation is perfect for **creating unique test data on each run**, avoiding conflicts with existing records, and **testing edge cases with realistic data**. Use libraries like Faker when you need fresh emails, names, or other data that won't collide with previous test runs.
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+import { faker } from '@faker-js/faker';
+
+test('user registration with dynamic data', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+
+  // Generate unique test data for each run
+  const userData = {
+    firstName: faker.person.firstName(),
+    lastName: faker.person.lastName(),
+    email: faker.internet.email(),
+    password: faker.internet.password({ length: 12 })
+  };
+
+  await testdriver.find('first name input').type(userData.firstName);
+  await testdriver.find('last name input').type(userData.lastName);
+  await testdriver.find('email input').type(userData.email);
+  await testdriver.find('password input').type(userData.password);
+  await testdriver.find('register button').click();
+
+  await testdriver.assert('registration successful');
+  console.log('Registered user:', userData.email);
+});
+```
+
+```bash
+npm install --save-dev @faker-js/faker
+```

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

@@ -0,0 +1,66 @@
+---
+title: "Waiting for Elements"
+description: "Handle async operations and prevent flaky tests"
+icon: "clock"
+---
+
+## Waiting for Elements
+
+Use the `timeout` option with `find()` to wait for elements that appear after async operations:
+
+```javascript
+// Wait up to 30 seconds for element to appear (polls every 5 seconds)
+const element = await testdriver.find('Loading complete indicator', { timeout: 30000 });
+await element.click();
+
+// Useful after actions that trigger loading states
+await testdriver.find('submit button').click();
+await testdriver.find('success message', { timeout: 15000 });
+
+// Short timeout for quick checks
+const toast = await testdriver.find('notification toast', { timeout: 5000 });
+```
+
+## Flake Prevention
+
+TestDriver automatically waits for the screen and network to stabilize after each action using **redraw detection**. This prevents flaky tests caused by animations, loading states, or dynamic content updates.
+
+<Note>
+  Redraw detection adds a small delay after each action but significantly reduces test flakiness.
+</Note>
+
+For example, when clicking a submit button that navigates to a new page:
+
+```javascript
+// Click submit - TestDriver automatically waits for the new page to load
+await testdriver.find('submit button').click();
+
+// By the time this runs, the page has fully loaded and stabilized
+await testdriver.assert('dashboard is displayed');
+await testdriver.find('welcome message');
+```
+
+Without redraw detection, you'd need manual waits or retries to handle the page transition. TestDriver handles this automatically by detecting when the screen stops changing and network requests complete.
+
+You can disable redraw detection or customize its behavior:
+
+```javascript
+// Disable redraw detection for faster tests (less reliable)
+const testdriver = TestDriver(context, { 
+  redraw: false 
+});
+```
+
+Here is an example of customizing redraw detection:
+
+```javascript
+// Fine-tune redraw detection
+const testdriver = TestDriver(context, { 
+  redraw: {
+    enabled: true,
+    diffThreshold: 0.1,      // Pixel difference threshold (0-1)
+    screenRedraw: true,      // Monitor screen changes
+    networkMonitor: true,    // Wait for network idle
+  }
+});
+```

package/docs/v7/what-is-testdriver.mdx

@@ -0,0 +1,54 @@
+---
+title: "What is TestDriver?"
+description: "Reliably test your most difficult user flows"
+icon: "circle-info"
+---
+
+## The problem with modern testing tools
+
+Modern testing tools like Playwright are designed to test a single web application, running in a single browser tab using selectors.
+
+However, selectors are often either unreliable or unavailable in complex scenarios, leading to brittle and flaky tests:
+
+| Challenge | Problem | Examples |
+|-----------|---------|----------|
+| **Fast moving teams** | Frequently change UI structure, breaking CSS/XPath selectors | Agile teams, startups, vibe-coders |
+| **Dynamic content** | Cannot be targeted with selectors | AI chatbots, PDFs, images, videos |
+| **Software you don't own** | May lack proper accessibility attributes | Other websites, extensions, third-party applications |
+| **Multi-application workflows** | Cannot be tested with web-only tools | Desktop apps, browser extensions, IDEs |
+| **Visual states** | Impossible to verify with code-based selectors | Charts, graphs, videos, images, spelling errors, UI layout |
+
+## The TestDriver Solution
+
+TestDriver is a complete testing platform built specifically for handling these scenarios. It consists of a Javascript SDK, hosted infrastructure, and debugging tools that make it easy to write, run, and maintain tests for your most difficult user flows.
+
+### Javascript SDK
+
+Here is an example of a TestDriver test that installs a production Chrome extension from the Chrome Web Store and verifies that it appears in the extensions menu:
+
+```javascript Installing Loom from the Chrome Web Store
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/vitest/hooks";
+
+describe("Chrome Extension Test", () => {
+  const testdriver = TestDriver(context);
+
+  // Launch Chrome with Loom loaded by its Chrome Web Store ID
+  await testdriver.provision.chromeExtension({
+    extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb'
+  });
+
+  // Click on the extensions button (puzzle piece icon) in Chrome toolbar
+  const extensionsButton = await testdriver.find("The puzzle-shaped icon in the Chrome toolbar.");
+  await extensionsButton.click();
+
+  // Look for Loom in the extensions menu
+  const loomExtension = await testdriver.find("Loom extension in the extensions dropdown");
+  expect(loomExtension.found()).toBeTruthy();
+});
+```
+
+
+<Tip>[vitest](https://vitest.dev/) is the preferred test runner for TestDriver.</Tip>
+
+,

package/lib/vitest/hooks.mjs

@@ -154,9 +154,16 @@ export function TestDriver(context, options = {}) {
     throw new Error('TestDriver() requires Vitest context. Pass the context parameter from your test function: test("name", async (context) => { ... })');
   }
   
-  // Return existing instance if already created for this test
+  // Return existing instance if already created for this test AND it's still connected
+  // On retry, the previous instance will be disconnected, so we need to create a new one
   if (testDriverInstances.has(context.task)) {
-    return testDriverInstances.get(context.task);
+    const existingInstance = testDriverInstances.get(context.task);
+    if (existingInstance.connected) {
+      return existingInstance;
+    }
+    // Instance exists but is disconnected (likely a retry) - remove it and create fresh
+    testDriverInstances.delete(context.task);
+    lifecycleHandlers.delete(context.task);
   }
   
   // Get global plugin options if available
@@ -194,7 +201,6 @@ export function TestDriver(context, options = {}) {
   
   if (autoConnect) {
     testdriver.__connectionPromise = (async () => {
-        console.log('[testdriver] Connecting to sandbox...');
         if (debugConsoleSpy) {
           console.log('[DEBUG] Before auth - sandbox.instanceSocketConnected:', testdriver.sandbox?.instanceSocketConnected);
         }
@@ -231,74 +237,80 @@ export function TestDriver(context, options = {}) {
   }
   
   // Register cleanup handler with dashcam.stop()
-  if (!lifecycleHandlers.has(context.task)) {
-    const cleanup = async () => {
-      try {
-        // Stop dashcam if it was started - with timeout to prevent hanging
-        if (testdriver._dashcam && testdriver._dashcam.recording) {
-          try {
-            const dashcamUrl = await testdriver.dashcam.stop();
-            console.log('');
-            console.log('🎥' + chalk.yellow(` Dashcam URL`) + `: ${dashcamUrl}`);
-            console.log('');
-            
-            // Set test metadata directly on the Vitest task context
-            // This is the proper way to pass data from test to reporter
-            const platform = testdriver.os || 'linux';
-            const absolutePath = context.task.file?.filepath || context.task.file?.name || 'unknown';
-            const projectRoot = process.cwd();
-            const testFile = absolutePath !== 'unknown'
-              ? path.relative(projectRoot, absolutePath)
-              : absolutePath;
-            
-            // Set metadata on the task for the reporter to read
-            context.task.meta.dashcamUrl = dashcamUrl || null;
-            context.task.meta.platform = platform;
-            context.task.meta.testFile = testFile;
-            context.task.meta.testOrder = 0;
-            context.task.meta.sessionId = testdriver.getSessionId();
-            
-            // Also register in memory if plugin is available (for cross-process scenarios)
-            if (globalThis.__testdriverPlugin?.registerDashcamUrl) {
-              globalThis.__testdriverPlugin.registerDashcamUrl(context.task.id, dashcamUrl, platform);
-            }
-          } catch (error) {
-            // Log more detailed error information for debugging
-            console.error('❌ Failed to stop dashcam:', error.name || error.constructor?.name || 'Error');
-            if (error.message) console.error('   Message:', error.message);
-            // NotFoundError during cleanup is expected if sandbox already terminated
-            if (error.name === 'NotFoundError' || error.responseData?.error === 'NotFoundError') {
-              console.log('   ℹ️  Sandbox session already terminated - dashcam stop skipped');
-            }
-            // Mark as not recording to prevent retries
-            if (testdriver._dashcam) {
-              testdriver._dashcam.recording = false;
-            }
+  // We always register a new cleanup handler because on retry we need to clean up the new instance
+  const cleanup = async () => {
+    // Get the current instance from the WeakMap (not from closure)
+    // This ensures we clean up the correct instance on retries
+    const currentInstance = testDriverInstances.get(context.task);
+    if (!currentInstance) {
+      return; // Already cleaned up
+    }
+    
+    try {
+      // Stop dashcam if it was started - with timeout to prevent hanging
+      if (currentInstance._dashcam && currentInstance._dashcam.recording) {
+        try {
+          const dashcamUrl = await currentInstance.dashcam.stop();
+          console.log('');
+          console.log('🎥' + chalk.yellow(` Dashcam URL`) + `: ${dashcamUrl}`);
+          console.log('');
+          
+          // Set test metadata directly on the Vitest task context
+          // This is the proper way to pass data from test to reporter
+          const platform = currentInstance.os || 'linux';
+          const absolutePath = context.task.file?.filepath || context.task.file?.name || 'unknown';
+          const projectRoot = process.cwd();
+          const testFile = absolutePath !== 'unknown'
+            ? path.relative(projectRoot, absolutePath)
+            : absolutePath;
+          
+          // Set metadata on the task for the reporter to read
+          context.task.meta.dashcamUrl = dashcamUrl || null;
+          context.task.meta.platform = platform;
+          context.task.meta.testFile = testFile;
+          context.task.meta.testOrder = 0;
+          context.task.meta.sessionId = currentInstance.getSessionId();
+          
+          // Also register in memory if plugin is available (for cross-process scenarios)
+          if (globalThis.__testdriverPlugin?.registerDashcamUrl) {
+            globalThis.__testdriverPlugin.registerDashcamUrl(context.task.id, dashcamUrl, platform);
+          }
+        } catch (error) {
+          // Log more detailed error information for debugging
+          console.error('❌ Failed to stop dashcam:', error.name || error.constructor?.name || 'Error');
+          if (error.message) console.error('   Message:', error.message);
+          // NotFoundError during cleanup is expected if sandbox already terminated
+          if (error.name === 'NotFoundError' || error.responseData?.error === 'NotFoundError') {
+            console.log('   ℹ️  Sandbox session already terminated - dashcam stop skipped');
+          }
+          // Mark as not recording to prevent retries
+          if (currentInstance._dashcam) {
+            currentInstance._dashcam.recording = false;
           }
         }
-        
-        // Clean up console spies
-        cleanupConsoleSpy(testdriver);
-        
-        // Wait for connection to finish if it was initiated
-        if (testdriver.__connectionPromise) {
-          await testdriver.__connectionPromise.catch(() => {}); // Ignore connection errors during cleanup
-        }
-        
-        // Disconnect with timeout
-        await Promise.race([
-          testdriver.disconnect(),
-          new Promise((resolve) => setTimeout(resolve, 5000)) // 5s timeout for disconnect
-        ]);
-      } catch (error) {
-        console.error('Error disconnecting client:', error);
       }
-    };
-    lifecycleHandlers.set(context.task, cleanup);
-    
-    // Vitest will call this automatically after the test
-    context.onTestFinished?.(cleanup);
-  }
+      
+      // Clean up console spies
+      cleanupConsoleSpy(currentInstance);
+      
+      // Wait for connection to finish if it was initiated
+      if (currentInstance.__connectionPromise) {
+        await currentInstance.__connectionPromise.catch(() => {}); // Ignore connection errors during cleanup
+      }
+      
+      // Disconnect with timeout
+      await Promise.race([
+        currentInstance.disconnect(),
+        new Promise((resolve) => setTimeout(resolve, 5000)) // 5s timeout for disconnect
+      ]);
+    } catch (error) {
+      console.error('Error disconnecting client:', error);
+    }
+  };
+  lifecycleHandlers.set(context.task, cleanup);
+  
+  // Vitest will call this automatically after the test (each retry attempt)
+  context.onTestFinished?.(cleanup);
   
   return testdriver;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.9",
+  "version": "7.2.10",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "exports": {