testdriverai 7.2.3 → 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/interfaces/cli/commands/init.js

@@ -24,6 +24,7 @@ class InitCommand extends BaseCommand {
 
     console.log(chalk.green("\n✅ Project initialized successfully!\n"));
     this.printNextSteps();
+    process.exit(0);
   }
 
   /**
@@ -79,28 +80,41 @@ class InitCommand extends BaseCommand {
    */
   async promptHidden(question) {
     return new Promise((resolve) => {
-      const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-      });
-
-      // Mute output to hide the input
+      process.stdout.write(question);
+      
       const stdin = process.stdin;
-      const muted = {
-        write: () => {},
+      const wasRaw = stdin.isRaw;
+      stdin.setRawMode(true);
+      stdin.resume();
+      stdin.setEncoding("utf8");
+
+      let input = "";
+
+      const onData = (char) => {
+        // Handle Ctrl+C
+        if (char === "\u0003") {
+          stdin.setRawMode(wasRaw);
+          process.exit();
+        }
+        // Handle Enter
+        if (char === "\r" || char === "\n") {
+          stdin.setRawMode(wasRaw);
+          stdin.removeListener("data", onData);
+          stdin.pause();
+          console.log(""); // New line after hidden input
+          resolve(input);
+          return;
+        }
+        // Handle Backspace
+        if (char === "\u007F" || char === "\b") {
+          input = input.slice(0, -1);
+          return;
+        }
+        // Add character to input (but don't echo it)
+        input += char;
       };
 
-      rl.question(question, (answer) => {
-        rl.close();
-        stdin.removeListener("data", muted.write);
-        console.log(""); // New line after hidden input
-        resolve(answer);
-      });
-
-      // Mute stdin to hide input
-      stdin.on("data", (char) => {
-        // Don't write to output (hides the input)
-      });
+      stdin.on("data", onData);
     });
   }
 

package/interfaces/cli/lib/base.js

@@ -23,6 +23,7 @@ async function openBrowser(url) {
     await open(url, {
       // Wait for the app to open
       wait: false,
+      background: true
     });
   } catch (error) {
     console.error("Failed to open browser automatically:", error);
@@ -131,9 +132,32 @@ class BaseCommand extends Command {
     }
 
     this.agent.emitter.on("exit", (exitCode) => {
+      // Ensure sandbox is closed before exiting
+      if (this.agent?.sandbox) {
+        try {
+          this.agent.sandbox.close();
+        } catch (err) {
+          // Ignore close errors
+        }
+      }
       process.exit(exitCode);
     });
 
+    // Handle process signals to ensure clean disconnection
+    const cleanupAndExit = () => {
+      if (this.agent?.sandbox) {
+        try {
+          this.agent.sandbox.close();
+        } catch (err) {
+          // Ignore close errors
+        }
+      }
+      process.exit(1);
+    };
+
+    process.on('SIGINT', cleanupAndExit);
+    process.on('SIGTERM', cleanupAndExit);
+
     // Handle unhandled promise rejections to prevent them from interfering with the exit flow
     // This is particularly important when JavaScript execution in VM contexts leaves dangling promises
     process.on("unhandledRejection", (reason) => {

package/interfaces/cli.js

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
 
 const { run } = require("@oclif/core");
+const sentry = require("../lib/sentry");
 
 // Run oclif (with default command handling built-in)
 run()
   .then(() => {
     // Success
   })
-  .catch((error) => {
+  .catch(async (error) => {
+    // Capture error in Sentry
+    sentry.captureException(error, {
+      tags: { component: "cli-init" },
+    });
+    await sentry.flush();
+
     console.error("Failed to start TestDriver.ai agent:", error);
     process.exit(1);
   });

package/interfaces/logger.js

@@ -300,6 +300,9 @@ marked.use(
 );
 
 const createMarkdownLogger = (emitter) => {
+  // Indent prefix for streaming AI thoughts - makes it visually distinct and scoped
+  const streamIndent = "";
+
   const markedParsePartial = (markdown, start = 0, end = 0) => {
     let result = markdown.trimEnd().split("\n").slice(start, end);
     if (end <= 0) {
@@ -307,7 +310,8 @@ const createMarkdownLogger = (emitter) => {
     }
     result = result.join("\n");
 
-    return marked.parse(result).replace(/^/gm, spaceChar).trimEnd();
+    // Use streamIndent for streaming output to make it visually scoped
+    return marked.parse(result).replace(/^/gm, streamIndent).trimEnd();
   };
 
   // Event-based markdown streaming with buffering
@@ -360,7 +364,8 @@ const createMarkdownLogger = (emitter) => {
       diff = censorSensitiveDataDeep(diff);
       process.stdout.write(diff);
     }
-    process.stdout.write("\n\n");
+    // Use console.log for the final newlines so it gets captured by vitest
+    console.log("");
 
     // Clean up the stream
     activeStreams.delete(streamId);
@@ -384,7 +389,7 @@ const createMarkdownLogger = (emitter) => {
   });
 };
 
-const spaceChar = "    ";
+const spaceChar = "   ";
 
 module.exports = {
   logger,