@testdriverai/agent 7.8.0-test.38

package/docs/v7/_drafts/agents.mdx

@@ -0,0 +1,843 @@
+# TestDriver AI SDK - Agent Guide
+
+This guide is designed for AI agents to understand how to use the TestDriver SDK for automated testing.
+
+## Table of Contents
+- [Quick Setup](#quick-setup)
+- [Authentication](#authentication)
+- [Provision Methods](#provision-methods)
+- [Core API Methods](#core-api-methods)
+- [Reconnection and Debugging](#reconnection-and-debugging)
+- [Best Practices](#best-practices)
+
+---
+
+## Quick Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install --save-dev testdriverai vitest
+```
+
+### 2. Configure Vitest Project
+
+Create or update `vitest.config.mjs`:
+
+```javascript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    testTimeout: 120000, // 2 minutes (TestDriver tests can take longer)
+    hookTimeout: 120000,
+  },
+});
+```
+
+### 3. Create Test File
+
+Create a test file (e.g., `test.test.js`):
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('my first test', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com',
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  await testdriver.find('More information link').click();
+  await testdriver.assert('IANA page is visible');
+});
+```
+
+---
+
+## Authentication
+
+### Getting an API Key
+
+1. Go to [console.testdriver.ai](https://console.testdriver.ai)
+2. Sign up or log in
+3. Navigate to your account settings
+4. Generate a new API key (format: `tdai-1234567890abcdef`)
+
+### Using API Keys
+
+**Recommended: Environment Variables**
+
+Create `.env` file (add to `.gitignore`):
+```bash
+TD_API_KEY=tdai-1234567890abcdef
+```
+
+Then use in tests:
+```javascript
+const { testdriver } = await chrome(context, {
+  url: 'https://example.com'
+  // apiKey automatically read from process.env.TD_API_KEY
+});
+```
+
+**Alternative: Direct in Code (Not Recommended)**
+```javascript
+const { testdriver } = await chrome(context, {
+  url: 'https://example.com',
+  apiKey: 'tdai-1234567890abcdef' // DON'T commit to version control!
+});
+```
+
+---
+
+## Provision Methods
+
+TestDriver provides presets to automatically provision different application types.
+
+### chrome() - Web Applications
+
+Automatically launches Chrome browser and navigates to a URL.
+
+```javascript
+import { chrome } from 'testdriverai/presets';
+
+test('web app test', async (context) => {
+  const { testdriver, dashcam } = await chrome(context, {
+    url: 'https://myapp.com',
+    maximized: true,      // Start maximized (default: true)
+    guest: true,          // Use incognito mode (default: true)
+    dashcam: true,        // Enable recording (default: true)
+    os: 'linux',          // OS: 'linux', 'mac', 'windows' (default: 'linux')
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  // Your test code
+});
+```
+
+### vscode() - VS Code Extensions
+
+Automatically launches VS Code with specified workspace and extensions.
+
+```javascript
+import { vscode } from 'testdriverai/presets';
+
+test('vscode extension test', async (context) => {
+  const { testdriver, dashcam } = await vscode(context, {
+    workspace: '/tmp/test-project',
+    extensions: ['ms-python.python', 'dbaeumer.vscode-eslint'],
+    dashcam: true,
+    os: 'linux',
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  // Your test code
+});
+```
+
+### electron() - Desktop Applications
+
+Automatically launches Electron applications.
+
+```javascript
+import { electron } from 'testdriverai/presets';
+
+test('electron app test', async (context) => {
+  const { app, dashcam } = await electron(context, {
+    appPath: './dist/my-app',
+    args: ['--debug'],    // Additional CLI args (optional)
+    dashcam: true,
+    os: 'linux',
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  // Your test code (app is alias for testdriver)
+});
+```
+
+### Advanced: TestDriver() Hook + provision
+
+For more control, use the direct API (recommended for v7.1+):
+
+```javascript
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  const testdriver = TestDriver(context, {
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  // Provision Chrome
+  await testdriver.provision.chrome({ url: 'https://example.com' });
+  
+  // Or provision VS Code
+  await testdriver.provision.vscode({ 
+    workspace: '/tmp/project',
+    extensions: ['ms-python.python']
+  });
+  
+  // Or provision Electron
+  await testdriver.provision.electron({ appPath: './dist/app' });
+  
+  // Your test code
+});
+```
+
+---
+
+## Core API Methods
+
+All methods use AI-powered natural language descriptions.
+
+### find(description) - Locate Elements
+
+Find a single element using natural language.
+
+```javascript
+// Basic finding
+const button = await testdriver.find('submit button');
+const input = await testdriver.find('email input field');
+const link = await testdriver.find('Contact Us link');
+
+// With context
+const field = await testdriver.find('username input in the login form');
+const deleteBtn = await testdriver.find('delete button in the top right corner');
+
+// Chainable syntax (recommended)
+await testdriver.find('submit button').click();
+await testdriver.find('email input').type('user@example.com');
+```
+
+**Returns:** `Element` object with properties:
+- `coordinates` - Position `{x, y, centerX, centerY}`
+- `text` - Text content (if available)
+- `confidence` - AI confidence score
+- `screenshot` - Base64 screenshot (if available)
+
+### findAll(description) - Find Multiple Elements
+
+Find all matching elements.
+
+```javascript
+const items = await testdriver.findAll('product card');
+console.log(`Found ${items.length} products`);
+
+// Interact with each
+for (const item of items) {
+  await item.click();
+  // Do something
+}
+```
+
+**Returns:** `Array<Element>`
+
+### click(x?, y?, action?) - Click Elements or Coordinates
+
+```javascript
+// Element click (chainable)
+await testdriver.find('Login button').click();
+
+// Coordinate click
+await testdriver.click(500, 300);
+
+// Different click types
+await element.click();              // Regular click
+await element.click('double-click'); // Double-click
+await element.click('right-click');  // Right-click
+await element.click('mouseDown');    // Press and hold
+await element.click('mouseUp');      // Release
+
+// Or use dedicated methods
+await element.doubleClick();
+await element.rightClick();
+await element.mouseDown();
+await element.mouseUp();
+```
+
+### type(text, options) - Type Text
+
+Type text into the currently focused input.
+
+```javascript
+// Basic typing
+await testdriver.find('email input').click();
+await testdriver.type('user@example.com');
+
+// Type with delay between keystrokes
+await testdriver.type('slow typing', { delay: 500 }); // 500ms between chars
+
+// ⚠️ IMPORTANT: Always use secret: true for passwords and sensitive data
+await testdriver.find('password input').click();
+await testdriver.type('MySecureP@ssw0rd', { secret: true });
+// This prevents logging in dashcam, debug info, and console
+
+// Type numbers
+await testdriver.type(12345);
+```
+
+**Options:**
+- `delay` (number) - Delay between keystrokes in ms (default: 250)
+- `secret` (boolean) - Mark as sensitive data, won't be logged (default: false)
+
+### hover(x?, y?) - Hover Over Elements
+
+```javascript
+// Element hover
+const menu = await testdriver.find('Products menu');
+await menu.hover();
+await testdriver.find('Laptops submenu item').click();
+
+// Coordinate hover
+await testdriver.hover(500, 300);
+```
+
+### assert(assertion) - AI-Powered Assertions
+
+Verify screen state using natural language.
+
+```javascript
+// Verify elements
+await testdriver.assert('the login page is displayed');
+await testdriver.assert('submit button is visible');
+
+// Verify content
+await testdriver.assert('the page title is "Welcome"');
+await testdriver.assert('success message says "Account created"');
+
+// Verify state
+await testdriver.assert('the checkbox is checked');
+await testdriver.assert('the form is empty');
+
+// Verify visual appearance
+await testdriver.assert('the button is blue');
+await testdriver.assert('the loading spinner is displayed');
+```
+
+**Returns:** `Promise<boolean>` - `true` if passes, throws error if fails
+
+### pressKeys(keys) - Keyboard Shortcuts
+
+Press one or more keys simultaneously.
+
+```javascript
+// Navigation
+await testdriver.pressKeys(['tab']);
+await testdriver.pressKeys(['shift', 'tab']);
+await testdriver.pressKeys(['enter']);
+
+// Keyboard shortcuts
+await testdriver.pressKeys(['ctrl', 'c']);  // Copy
+await testdriver.pressKeys(['ctrl', 'v']);  // Paste
+await testdriver.pressKeys(['ctrl', 's']);  // Save
+await testdriver.pressKeys(['ctrl', 'a']);  // Select all
+
+// Arrow keys
+await testdriver.pressKeys(['up']);
+await testdriver.pressKeys(['down']);
+await testdriver.pressKeys(['left']);
+await testdriver.pressKeys(['right']);
+
+// Special keys
+await testdriver.pressKeys(['escape']);
+await testdriver.pressKeys(['backspace']);
+await testdriver.pressKeys(['delete']);
+await testdriver.pressKeys(['home']);
+await testdriver.pressKeys(['end']);
+```
+
+### scroll(direction, amount, method) - Scroll Pages
+
+```javascript
+// Scroll down (default)
+await testdriver.scroll();
+await testdriver.scroll('down', 500);
+
+// Scroll up
+await testdriver.scroll('up', 300);
+
+// Horizontal scrolling
+await testdriver.scroll('right', 300);
+await testdriver.scroll('left', 300);
+
+// Scroll methods
+await testdriver.scroll('down', 300, 'mouse');    // Mouse wheel (smooth)
+await testdriver.scroll('down', 300, 'keyboard'); // Page Down key
+
+// Scroll until text appears
+await testdriver.scrollUntilText('Contact Us');
+await testdriver.scrollUntilText('Footer', 'down', 5000);
+```
+
+### exec(language, code, timeout, silent) - Execute Code
+
+Execute shell or PowerShell in the sandbox.
+
+```javascript
+// Shell execution (Linux sandbox)
+const output = await testdriver.exec('sh', 'ls -la', 5000);
+
+// PowerShell execution (Windows sandbox)
+await testdriver.exec('pwsh', 'npm install -g http-server', 30000);
+await testdriver.exec('pwsh', 'Start-Process notepad.exe', 5000);
+```
+
+### focusApplication(appName) - Switch Applications
+
+Focus a different application window.
+
+```javascript
+await testdriver.focusApplication('Chrome');
+await testdriver.focusApplication('VS Code');
+await testdriver.focusApplication('Notepad');
+```
+
+---
+
+## Reconnection and Debugging
+
+### Reconnecting to a Sandbox
+
+If a test fails or you need to try different selectors, you can reconnect to the same sandbox instance.
+
+**Automatic Sandbox Tracking:** TestDriver automatically saves the last sandbox ID to `.testdriver/last-sandbox` in your project directory. You can use this to reconnect without manually tracking the ID.
+
+**Manual Tracking:** You can also explicitly save the `sandboxId` from the initial connection:
+
+```javascript
+import { test } from 'vitest';
+import { TestDriver } from 'testdriverai';
+
+test('initial attempt', async () => {
+  const testdriver = new TestDriver({
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  const instance = await testdriver.connect();
+  console.log('Sandbox ID:', instance.instanceId);
+  // Output: Sandbox ID: i-0abc123def456789
+  
+  // Your test code that might fail
+  try {
+    await testdriver.find('difficult selector').click();
+  } catch (error) {
+    console.error('Failed:', error);
+    // Don't disconnect yet - keep sandbox alive for debugging
+  }
+});
+
+test('reconnect to same sandbox', async () => {
+  const testdriver = new TestDriver({
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  // Option 1: Read from saved file
+  const lastSandboxId = testdriver.getLastSandboxId();
+  
+  // Option 2: Use the ID from previous test (manual tracking)
+  // const sandboxId = 'i-0abc123def456789';
+  
+  // Reconnect using the sandbox ID
+  await testdriver.connect({
+    sandboxId: lastSandboxId, // or use manually saved ID
+    newSandbox: false
+  });
+  
+  // Try different selector on the same sandbox state
+  try {
+    await testdriver.find('alternative selector description').click();
+  } catch (error) {
+    console.error('Alternative also failed:', error);
+  }
+  
+  await testdriver.disconnect();
+});
+```
+
+### Debugging Failed Finds
+
+When `find()` fails, TestDriver provides detailed debug information:
+
+```javascript
+try {
+  await testdriver.find('non-existent button').click();
+} catch (error) {
+  // error.name === 'ElementNotFoundError'
+  console.log('Element not found:', error.message);
+  console.log('Similarity score:', error.similarity); // How close the match was
+  console.log('Debug screenshot:', error.debugScreenshot); // Base64 image
+  console.log('Cache info:', error.cacheInfo); // Cache diagnostics
+  
+  // Try alternative description
+  await testdriver.find('button with different description').click();
+}
+```
+
+### Keep Sandbox Alive for Multiple Attempts
+
+```javascript
+test('iterative debugging', async (context) => {
+  const testdriver = new TestDriver({
+    apiKey: process.env.TD_API_KEY
+  });
+  
+  const instance = await testdriver.connect();
+  const sandboxId = instance.instanceId;
+  
+  // Try multiple selectors
+  const selectors = [
+    'submit button',
+    'blue submit button',
+    'submit button in bottom right',
+    'button with "Submit" text'
+  ];
+  
+  for (const selector of selectors) {
+    try {
+      console.log(`Trying: ${selector}`);
+      const element = await testdriver.find(selector);
+      console.log(`✓ Found with: ${selector}`);
+      await element.click();
+      break; // Success!
+    } catch (error) {
+      console.log(`✗ Failed with: ${selector}`);
+      console.log(`  Similarity: ${error.similarity}`);
+    }
+  }
+  
+  // Clean up
+  await testdriver.disconnect();
+});
+```
+
+### Using Vitest Hooks for Reconnection
+
+```javascript
+import { test, beforeAll, afterAll } from 'vitest';
+import { TestDriver } from 'testdriverai';
+
+let testdriver;
+let sandboxId;
+
+beforeAll(async () => {
+  testdriver = new TestDriver({
+    apiKey: process.env.TD_API_KEY
+  });
+  const instance = await testdriver.connect();
+  sandboxId = instance.instanceId;
+  console.log('Sandbox started:', sandboxId);
+});
+
+afterAll(async () => {
+  await testdriver.disconnect();
+});
+
+test('first attempt', async () => {
+  await testdriver.find('selector v1').click();
+});
+
+test('second attempt - same sandbox', async () => {
+  // Continues in same sandbox session
+  await testdriver.find('selector v2').click();
+});
+```
+
+---
+
+## Best Practices
+
+### 1. Use Descriptive Selectors
+
+```javascript
+// ❌ Too vague
+await testdriver.find('button');
+
+// ✅ Specific
+await testdriver.find('blue submit button below the login form');
+```
+
+### 2. Always Use secret: true for Sensitive Data
+
+```javascript
+// ❌ Password will be logged
+await testdriver.type('MyPassword123');
+
+// ✅ Protected from logging
+await testdriver.type('MyPassword123', { secret: true });
+```
+
+### 3. Prefer Chainable Syntax
+
+```javascript
+// ❌ More verbose
+const button = await testdriver.find('submit button');
+await button.click();
+
+// ✅ Cleaner
+await testdriver.find('submit button').click();
+```
+
+### 4. Use Environment Variables for API Keys
+
+```javascript
+// ❌ Hardcoded (security risk)
+apiKey: 'tdai-1234567890abcdef'
+
+// ✅ From environment
+apiKey: process.env.TD_API_KEY
+```
+
+### 5. Set Appropriate Timeouts
+
+```javascript
+// vitest.config.mjs
+export default defineConfig({
+  test: {
+    testTimeout: 120000, // 2 minutes for TestDriver tests
+    hookTimeout: 120000,
+  },
+});
+```
+
+### 6. Handle Errors Gracefully
+
+```javascript
+try {
+  await testdriver.find('optional element').click();
+} catch (error) {
+  console.log('Element not found, continuing...');
+  // Try alternative path
+}
+```
+
+### 7. Use Assertions for Verification
+
+```javascript
+// After action, verify result
+await testdriver.find('submit button').click();
+await testdriver.assert('success message is displayed');
+```
+
+### 8. Clean Up Resources
+
+```javascript
+// Always disconnect when done
+test('my test', async (context) => {
+  const { testdriver } = await chrome(context, { url: 'https://example.com' });
+  
+  try {
+    // Your test code
+  } finally {
+    await testdriver.disconnect();
+  }
+});
+
+// Or use presets which auto-cleanup
+```
+
+### 9. Save Sandbox IDs for Debugging
+
+```javascript
+const instance = await testdriver.connect();
+console.log('Sandbox ID for debugging:', instance.instanceId);
+// Save this ID to reconnect later if test fails
+```
+
+### 10. Use findAll() for Lists
+
+```javascript
+// ❌ Finding one at a time
+const item1 = await testdriver.find('first product card');
+const item2 = await testdriver.find('second product card');
+
+// ✅ Find all at once
+const items = await testdriver.findAll('product card');
+for (const item of items) {
+  await item.click();
+}
+```
+
+---
+
+## Common Patterns
+
+### Login Flow
+
+```javascript
+test('user login', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://myapp.com/login'
+  });
+  
+  await testdriver.find('email input').type('user@example.com');
+  await testdriver.find('password input').type('SecurePass123', { secret: true });
+  await testdriver.find('Login button').click();
+  
+  await testdriver.assert('Welcome message is visible');
+});
+```
+
+### Form Filling
+
+```javascript
+test('contact form', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com/contact'
+  });
+  
+  await testdriver.find('name input').type('John Doe');
+  await testdriver.find('email input').type('john@example.com');
+  await testdriver.find('message textarea').type('Hello, this is a test message.');
+  await testdriver.find('submit button').click();
+  
+  await testdriver.assert('Thank you message appears');
+});
+```
+
+### Navigation
+
+```javascript
+test('multi-page navigation', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com'
+  });
+  
+  await testdriver.find('About link').click();
+  await testdriver.assert('About page heading is visible');
+  
+  await testdriver.find('Contact link').click();
+  await testdriver.assert('Contact form is displayed');
+});
+```
+
+### Working with Dropdowns
+
+```javascript
+test('dropdown selection', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com/form'
+  });
+  
+  await testdriver.find('country dropdown').click();
+  await testdriver.find('United States option').click();
+  
+  await testdriver.assert('United States is selected');
+});
+```
+
+---
+
+## Environment Variables
+
+TestDriver supports these environment variables:
+
+- `TD_API_KEY` - Your TestDriver API key (recommended)
+- `TD_NO_CACHE` - Set to `"true"` to disable caching
+- `DASHCAM_API_KEY` - Dashcam API key (usually same as TD_API_KEY)
+- `TESTDRIVER_SANDBOX_ID` - Reuse an existing sandbox instance (see Sandbox Management below)
+
+---
+
+## Sandbox Management
+
+TestDriver allows you to create long-running sandbox instances that can be reused across multiple test runs.
+
+### Creating a Sandbox
+
+Use the CLI to spawn a new sandbox:
+
+```bash
+# Spawn a Linux sandbox (default)
+testdriver sandbox spawn
+
+# Spawn with a 2-hour lifetime (in milliseconds)
+testdriver sandbox spawn --timeout 7200000
+
+# Spawn a Windows sandbox
+testdriver sandbox spawn --os windows
+
+# Spawn with custom instance type (requires permission)
+testdriver sandbox spawn --instance-type c5.xlarge
+```
+
+The command will output the instance ID and instructions for using it.
+
+### Listing Sandboxes
+
+View all your team's sandboxes:
+
+```bash
+# List all sandboxes
+testdriver sandbox list
+
+# List only ready sandboxes
+testdriver sandbox list --status ready
+```
+
+### Using a Sandbox in Tests
+
+Set the `TESTDRIVER_SANDBOX_ID` environment variable to connect to an existing sandbox:
+
+```bash
+export TESTDRIVER_SANDBOX_ID=i-0abc123def456789
+vitest
+```
+
+This will:
+- Skip creating a new sandbox
+- Connect to the specified sandbox instance
+- Track which tests run on that sandbox
+- Keep the sandbox alive after tests finish
+
+### Stopping a Sandbox
+
+When you're done with a sandbox, stop it to avoid unnecessary costs:
+
+```bash
+testdriver sandbox stop i-0abc123def456789
+```
+
+This will:
+- Terminate the EC2 instance
+- Calculate the total runtime and cost
+- Send billing data to your team
+
+### Sandbox Benefits
+
+Using explicit sandboxes provides:
+- **Faster test runs** - No sandbox creation time
+- **Clear cost tracking** - Lifetime-based billing
+- **Better debugging** - Keep sandbox alive to investigate failures
+- **Team visibility** - See all active sandboxes in dashboard
+
+---
+
+## Resources
+
+- **Documentation:** [docs.testdriver.ai](https://docs.testdriver.ai)
+- **Dashboard:** [console.testdriver.ai](https://console.testdriver.ai)
+- **API Reference:** Full method documentation in `/docs/v7/api/`
+- **Examples:** See `/examples/` directory in the SDK package
+
+---
+
+## Quick Reference
+
+| Method | Purpose | Example |
+|--------|---------|---------|
+| `find(desc)` | Locate single element | `await testdriver.find('submit button')` |
+| `findAll(desc)` | Find all matching elements | `await testdriver.findAll('list item')` |
+| `click()` | Click element/coordinates | `await element.click()` |
+| `type(text, opts)` | Type text | `await testdriver.type('text', { secret: true })` |
+| `hover()` | Hover over element | `await element.hover()` |
+| `assert(text)` | Verify state | `await testdriver.assert('button is visible')` |
+| `pressKeys(keys)` | Keyboard shortcuts | `await testdriver.pressKeys(['ctrl', 'c'])` |
+| `scroll(dir, amt)` | Scroll page | `await testdriver.scroll('down', 500)` |
+| `exec(lang, code)` | Execute code | `await testdriver.exec('sh', 'ls -la', 5000)` |
+| `connect(opts)` | Connect to sandbox | `await testdriver.connect({ sandboxId: 'i-123' })` |
+| `disconnect()` | Close connection | `await testdriver.disconnect()` |
+
+---
+
+**Last Updated:** December 2, 2025