testdriverai 7.0.0 → 7.1.1

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

@@ -0,0 +1,398 @@
+---
+title: "What is TestDriver?"
+description: "AI-powered end-to-end testing for web, desktop, and mobile applications"
+icon: "circle-info"
+---
+
+TestDriver is an AI-native testing platform that lets you write tests in natural language. It uses computer vision and AI to understand your application like a human would, eliminating brittle selectors and making tests easy to write and maintain.
+
+## The Problem with Traditional Testing
+
+Traditional E2E testing tools require:
+
+<CardGroup cols={2}>
+  <Card title="Brittle Selectors" icon="triangle-exclamation">
+    ```javascript
+    // ❌ Breaks when DOM changes
+    await page.click('#root > div > form > div:nth-child(2) > button')
+    ```
+  </Card>
+
+  <Card title="Complex Setup" icon="wrench">
+    ```javascript
+    // ❌ Manual lifecycle management
+    await browser.launch()
+    await page.goto(url)
+    try {
+      // Test code
+    } finally {
+      await browser.close()
+    }
+    ```
+  </Card>
+
+  <Card title="Flaky Tests" icon="shuffle">
+    ```javascript
+    // ❌ Arbitrary waits
+    await page.click('button')
+    await page.waitForTimeout(1000)
+    await page.click('.dropdown-item')
+    ```
+  </Card>
+
+  <Card title="Limited Scope" icon="ban">
+    Most tools only work for web browsers. Testing desktop apps, extensions, or IDEs requires completely different frameworks.
+  </Card>
+</CardGroup>
+
+## The TestDriver Solution
+
+TestDriver solves these problems with AI-powered testing:
+
+<CodeGroup>
+```javascript TestDriver - Natural & Simple
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('user can 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('secret', { secret: true });
+  await testdriver.find('Login button').click();
+
+  await testdriver.assert('Dashboard is visible');
+});
+```
+
+```javascript Traditional - Complex & Brittle
+import puppeteer from 'puppeteer';
+
+test('user can login', async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+
+  try {
+    await page.goto('https://myapp.com/login');
+
+    const email = await page.waitForSelector(
+      'input[type="email"][name="email"]',
+      { state: 'visible', timeout: 30000 }
+    );
+    await email.type('user@example.com');
+
+    const password = await page.waitForSelector(
+      'input[type="password"][name="password"]',
+      { state: 'visible', timeout: 30000 }
+    );
+    await password.type('secret');
+
+    const button = await page.waitForSelector(
+      'button[type="submit"]',
+      { state: 'visible', timeout: 30000 }
+    );
+    await button.click();
+
+    await page.waitForSelector('.dashboard', {
+      state: 'visible',
+      timeout: 30000
+    });
+  } finally {
+    await browser.close();
+  }
+});
+```
+</CodeGroup>
+
+## How It Works
+
+TestDriver uses Claude AI's computer vision to understand your application:
+
+<Steps>
+  <Step title="Natural Language">
+    Describe what you want to interact with in plain English:
+
+    ```javascript
+    await testdriver.find('submit button in the login form')
+    ```
+  </Step>
+
+  <Step title="AI Vision Analysis">
+    TestDriver captures a screenshot and asks Claude AI to locate the element using computer vision - just like a human would.
+  </Step>
+
+  <Step title="Smart Caching">
+    Element locations are cached for 1.7x faster subsequent runs. The cache automatically invalidates when your UI changes.
+  </Step>
+
+  <Step title="Automatic Stability">
+    TestDriver waits for animations, network requests, and DOM changes to complete before acting - no manual waits needed.
+  </Step>
+</Steps>
+
+## Key Features
+
+<CardGroup cols={2}>
+  <Card title="Easy to Write" icon="feather" href="/v7/features/easy-to-write">
+    Natural language selectors, chainable API, full TypeScript support
+  </Card>
+
+  <Card title="Fast Performance" icon="bolt" href="/v7/features/fast">
+    1.7x faster with intelligent caching
+  </Card>
+
+  <Card title="Stable & Reliable" icon="shield-check" href="/v7/features/stable">
+    Anti-flake technology eliminates timing issues
+  </Card>
+
+  <Card title="Scalable" icon="arrow-up-right-dots" href="/v7/features/scalable">
+    From 1 test to 10,000+ with Vitest integration
+  </Card>
+
+  <Card title="AI-Native" icon="robot" href="/v7/features/ai-native">
+    Built for AI agents and autonomous testing
+  </Card>
+
+  <Card title="Powerful" icon="wand-magic-sparkles" href="/v7/features/powerful">
+    Test web, desktop, mobile, extensions, and more
+  </Card>
+
+  <Card title="Observable" icon="microscope" href="/v7/features/observable">
+    Video replays, logs, and complete debugging tools
+  </Card>
+
+  <Card title="Enterprise Ready" icon="building" href="/v7/features/enterprise">
+    Security, compliance, and on-premise deployment
+  </Card>
+</CardGroup>
+
+## What Can You Test?
+
+TestDriver is the only platform that lets you test everything with one SDK:
+
+<Tabs>
+  <Tab title="Web Applications">
+    ```javascript
+    import { chrome } from 'testdriverai/presets';
+
+    test('web app', async (context) => {
+      const { testdriver } = await chrome(context, {
+        url: 'https://myapp.com'
+      });
+      // Test any website
+    });
+    ```
+  </Tab>
+
+  <Tab title="Desktop Apps">
+    ```javascript
+    import { desktop } from 'testdriverai/presets';
+
+    test('desktop app', async (context) => {
+      const { testdriver } = await desktop(context, {
+        appPath: '/Applications/MyApp.app'
+      });
+      // Test Windows, macOS, Linux apps
+    });
+    ```
+  </Tab>
+
+  <Tab title="Chrome Extensions">
+    ```javascript
+    import { chromeExtension } from 'testdriverai/presets';
+
+    test('extension', async (context) => {
+      const { testdriver } = await chromeExtension(context, {
+        extensionPath: './my-extension'
+      });
+      // Test browser extensions
+    });
+    ```
+  </Tab>
+
+  <Tab title="VS Code Extensions">
+    ```javascript
+    import { vscode } from 'testdriverai/presets';
+
+    test('vscode', async (context) => {
+      const { testdriver } = await vscode(context, {
+        workspace: '/tmp/project'
+      });
+      // Test IDE extensions
+    });
+    ```
+  </Tab>
+
+  <Tab title="Electron Apps">
+    ```javascript
+    import { electron } from 'testdriverai/presets';
+
+    test('electron', async (context) => {
+      const { app } = await electron(context, {
+        appPath: './dist/my-app'
+      });
+      // Test Electron applications
+    });
+    ```
+  </Tab>
+</Tabs>
+
+## How TestDriver Compares
+
+<AccordionGroup>
+  <Accordion title="vs. Playwright / Selenium">
+    **TestDriver Advantages:**
+    - 🎯 Natural language selectors (no CSS/XPath)
+    - 🤖 AI-powered assertions
+    - 🛡️ Built-in anti-flake technology
+    - 💻 Desktop app support
+    - ☁️ Hosted infrastructure included
+    - 📹 Automatic video recording
+
+    **When to use Playwright/Selenium:**
+    - You need low-level browser control
+    - You're testing extremely complex DOM structures
+    - You require specific browser APIs
+  </Accordion>
+
+  <Accordion title="vs. Cypress">
+    **TestDriver Advantages:**
+    - 🖥️ Cross-platform (Windows, macOS, Linux)
+    - 📱 Desktop application support
+    - 🤖 AI-powered element location
+    - ☁️ Hosted sandboxes included
+    - ⚡ No flake from timing issues
+    - 🌐 Multi-application testing
+
+    **When to use Cypress:**
+    - You only test web applications
+    - You need real-time debugging in browser
+    - You want to run tests in-browser only
+  </Accordion>
+
+  <Accordion title="vs. Manual QA">
+    **TestDriver Advantages:**
+    - ⚡ 100x faster execution
+    - 🎯 Perfect consistency
+    - 🔄 Run thousands of tests in parallel
+    - 🚫 Zero human error
+    - 🌙 24/7 execution capability
+    - 🐛 Instant regression detection
+
+    **When to use Manual QA:**
+    - Exploratory testing
+    - UX/design feedback
+    - Edge cases not worth automating
+  </Accordion>
+</AccordionGroup>
+
+## Architecture
+
+TestDriver consists of three main components:
+
+```mermaid
+graph LR
+    A[Your Test Code] --> B[TestDriver SDK]
+    B --> C[TestDriver API]
+    C --> D[Claude AI Vision]
+    C --> E[Sandbox VM]
+    E --> F[Your Application]
+
+    style A fill:#b3d334
+    style B fill:#152a65,color:#fff
+    style C fill:#152a65,color:#fff
+    style D fill:#b3d334
+    style E fill:#152a65,color:#fff
+```
+
+1. **TestDriver SDK** - The JavaScript/TypeScript library you use in your tests
+2. **TestDriver API** - Cloud service that orchestrates sandboxes and AI
+3. **Sandbox VMs** - Isolated virtual machines where your application runs
+
+[Learn more about architecture](/v7/api/sandbox)
+
+## Pricing Model
+
+TestDriver uses usage-based pricing:
+
+<Card title="Pay-per-use" icon="dollar-sign">
+  **What you pay for:**
+  - AI vision analysis calls
+  - Sandbox VM time (per minute)
+  - Dashcam video storage
+
+  **What's included:**
+  - Intelligent caching (reduces costs by 90%+)
+  - Shared team cache
+  - Unlimited team members
+  - Unlimited test executions
+
+  **Typical costs:**
+  - Single test: $0.04 - $0.12
+  - 100-test suite: $4 - $12 (first run)
+  - Cached suite: $0.50 - $2 (subsequent runs)
+</Card>
+
+Enterprise plans available with unlimited usage, on-premise deployment, and custom SLA.
+
+[View pricing details](https://testdriver.ai/pricing)
+
+## Getting Started
+
+Ready to write your first test?
+
+<CardGroup cols={3}>
+  <Card
+    title="Quick Start"
+    icon="rocket"
+    href="/v7/getting-started/installation"
+  >
+    Install and run your first test in 2 minutes
+  </Card>
+
+  <Card
+    title="View Examples"
+    icon="code"
+    href="/v7/presets/chrome"
+  >
+    See TestDriver in action
+  </Card>
+
+  <Card
+    title="Watch Demo"
+    icon="play"
+    href="https://testdriver.ai/demo"
+  >
+    Schedule a live demo
+  </Card>
+</CardGroup>
+
+## Community & Support
+
+<CardGroup cols={3}>
+  <Card
+    title="Discord Community"
+    icon="discord"
+    href="https://discord.com/invite/cWDFW8DzPm"
+  >
+    Join 1,000+ developers
+  </Card>
+
+  <Card
+    title="GitHub"
+    icon="github"
+    href="https://github.com/testdriverai"
+  >
+    View examples and contribute
+  </Card>
+
+  <Card
+    title="Documentation"
+    icon="book"
+    href="/v7/getting-started/installation"
+  >
+    Complete guides and API reference
+  </Card>
+</CardGroup>

package/docs/v7/platforms/linux.mdx

@@ -0,0 +1,308 @@
+---
+title: "Linux"
+description: "Run TestDriver tests on Linux sandboxes (default platform)"
+icon: "linux"
+---
+
+## Overview
+
+Linux is the **default platform** for TestDriver sandboxes. All tests run on Ubuntu 22.04 unless otherwise specified.
+
+Linux sandboxes provide:
+- Fast startup times (20-60s)
+- Full desktop environment (XFCE)
+- Chrome, Firefox, and other browsers pre-installed
+- Support for all TestDriver commands
+- VNC access for debugging
+
+## Usage
+
+Linux is used automatically when you create a TestDriver instance:
+
+```javascript
+import { TestDriver } from '@testdriverai/testdriver';
+
+// Linux is the default - no os parameter needed
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY
+});
+```
+
+Or explicitly specify Linux:
+
+```javascript
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'linux'  // Optional - this is the default
+});
+```
+
+## System Details
+
+### Operating System
+- **Distribution**: Ubuntu 22.04 LTS
+- **Desktop Environment**: XFCE
+- **Architecture**: x86_64 (amd64)
+
+### Pre-installed Software
+- **Browsers**: Chrome, Firefox ESR, Chrome for Testing
+- **Languages**: Node.js 20, Python 3, build-essential (C/C++)
+- **Development**: VS Code, Git, vim, nano
+- **Office**: LibreOffice, Gnumeric
+- **Graphics**: ImageMagick, xpaint, scrot, gnome-screenshot
+- **Utilities**: xterm, xdotool, gedit, xpdf, pcmanfm (file manager), galculator
+- **Desktop**: XFCE4 desktop environment, tint2 panel
+- **Tools**: curl, wget, unzip, net-tools, netcat, jumpapp
+- **Multimedia**: FFmpeg
+- **TestDriver**: Dashcam (v1.4.11-beta.0), dashcam-chrome
+
+### Default Resolution
+- **1366x768** (configurable via `resolution` parameter)
+
+## Configuration
+
+### Custom Resolution
+
+Set a custom screen resolution:
+
+```javascript
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'linux',
+  resolution: '1280x720'  // HD
+});
+```
+
+Common resolutions:
+- `1366x768` - Default
+- `1920x1080` - Full HD
+- `1280x720` - HD
+- `2560x1440` - 2K
+- `3840x2160` - 4K
+
+### Environment Variables
+
+Set environment variables in the sandbox:
+
+```javascript
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: 'linux',
+  env: {
+    NODE_ENV: 'test',
+    DEBUG: 'true'
+  }
+});
+```
+
+## Common Use Cases
+
+### Web Application Testing
+
+Test web apps in Chrome or Firefox:
+
+```javascript
+import { chrome } from './setup/lifecycleHelpers.mjs';
+import { test } from 'vitest';
+
+test('login flow', async (context) => {
+  const { testdriver } = await chrome(context, { 
+    url: 'https://example.com',
+    os: 'linux'  // Optional
+  });
+  
+  await testdriver.find('email field').then(el => el.click());
+  await testdriver.type('user@example.com');
+  
+  await testdriver.find('password field').then(el => el.click());
+  await testdriver.type('password123');
+  
+  await testdriver.find('login button').then(el => el.click());
+  await testdriver.assert('dashboard loaded');
+});
+```
+
+### Desktop Application Testing
+
+Test Electron or other desktop apps:
+
+```javascript
+import { electron } from './setup/lifecycleHelpers.mjs';
+import { test } from 'vitest';
+
+test('electron app', async (context) => {
+  const { testdriver } = await electron(context, {
+    appPath: '/path/to/app',
+    os: 'linux'
+  });
+  
+  await testdriver.find('menu button').then(el => el.click());
+  await testdriver.find('settings').then(el => el.click());
+});
+```
+
+### Command-Line Tools
+
+Run shell commands in the sandbox:
+
+```javascript
+test('install and test CLI tool', async (context) => {
+  const { testdriver } = await chrome(context, { os: 'linux' });
+  
+  // Install tool
+  await testdriver.exec('sh', 'npm install -g my-cli-tool', 30000);
+  
+  // Run tool
+  const result = await testdriver.exec('sh', 'my-cli-tool --version', 5000);
+  console.log('Tool version:', result);
+});
+```
+
+## Package Management
+
+### APT (Debian/Ubuntu)
+
+Install system packages:
+
+```javascript
+// Install dependencies
+await testdriver.exec('sh', 
+  'sudo apt-get update && sudo apt-get install -y imagemagick',
+  60000
+);
+
+// Use installed package
+await testdriver.exec('sh', 
+  'convert input.png -resize 50% output.png',
+  10000
+);
+```
+
+### NPM/Node.js
+
+Install Node.js packages:
+
+```javascript
+// Install package globally
+await testdriver.exec('sh', 'npm install -g typescript', 30000);
+
+// Or in project directory
+await testdriver.exec('sh', 'cd /tmp/project && npm install', 60000);
+```
+
+### Python/Pip
+
+Install Python packages:
+
+```javascript
+await testdriver.exec('sh', 'pip3 install requests', 30000);
+```
+
+## Debugging
+
+### VNC Access
+
+Connect to sandbox desktop via VNC:
+
+```javascript
+const instance = testdriver.getInstance();
+console.log('VNC:', `vnc://${instance.ip}:${instance.vncPort}`);
+
+// Use VNC client to connect and watch tests run
+```
+
+### Screenshots
+
+Take screenshots for debugging:
+
+```javascript
+const element = await testdriver.find('error message');
+if (element.found()) {
+  console.log('Screenshot:', element.screenshot);  // base64
+}
+```
+
+### Logs
+
+Access sandbox logs:
+
+```javascript
+// Run command and capture output
+const logs = await testdriver.exec('sh', 'tail -f /var/log/syslog', 5000);
+console.log('System logs:', logs);
+```
+
+## Performance
+
+### Startup Time
+- **First test**: 20-60s (sandbox creation)
+- **Subsequent tests**: 0s (sandbox reuse)
+
+### Optimization Tips
+- Reuse sandboxes across tests (use context)
+- Enable caching for faster element finding
+- Use parallel test execution
+- Minimize package installations
+
+See [Performance Guide](/v7/guides/performance) for details.
+
+## Limitations
+
+### No Root Access
+Sandboxes run with limited privileges. Some operations requiring root may fail.
+
+**Workaround**: Use `sudo` for commands that need elevation (already configured).
+
+### Temporary Storage
+Files are not persisted between sandbox sessions unless explicitly saved.
+
+**Workaround**: Upload files at test start or use external storage.
+
+### Network Restrictions
+Some outbound ports may be blocked for security.
+
+**Workaround**: Use standard HTTP/HTTPS (80/443) ports.
+
+## Troubleshooting
+
+### Package Installation Fails
+
+```javascript
+// Update package lists first
+await testdriver.exec('sh', 'sudo apt-get update', 30000);
+await testdriver.exec('sh', 'sudo apt-get install -y package-name', 60000);
+```
+
+### Display Issues
+
+```javascript
+// Set DISPLAY variable
+await testdriver.exec('sh', 'export DISPLAY=:0', 1000);
+```
+
+### Permission Denied
+
+```javascript
+// Use sudo for system operations
+await testdriver.exec('sh', 'sudo chmod +x /path/to/file', 5000);
+```
+
+## See Also
+
+<CardGroup cols={2}>
+  <Card title="Windows" icon="windows" href="/v7/platforms/windows">
+    Windows sandboxes (Enterprise)
+  </Card>
+  
+  <Card title="macOS" icon="apple" href="/v7/platforms/macos">
+    macOS sandboxes (Beta)
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/v7/getting-started/configuration">
+    Sandbox configuration
+  </Card>
+  
+  <Card title="Self-Hosting" icon="server" href="/v7/guides/self-hosting">
+    Run your own sandboxes
+  </Card>
+</CardGroup>