testdriverai 7.1.0 → 7.1.2

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/playwright.mdx

@@ -47,15 +47,15 @@ test.describe("get started link", () => {
 
 <Steps>
   <Step title="Create a TestDriver Account">
-    You will need a [Free TestDriver Account](https://app.testdriver.ai/team) to get an API key.
+    You will need a [Free TestDriver Account](https://console.testdriver.ai/team) to get an API key.
 
-    <Card title="Sign Up for TestDriver" icon="user-plus" horizontal href="https://app.testdriver.ai/team">
+    <Card title="Sign Up for TestDriver" icon="user-plus" horizontal href="https://console.testdriver.ai/team">
 
     </Card>
 
   </Step>
   <Step title="Set up your environment">
-    Copy your API key from [the TestDriver dashboard](https://app.testdriver.ai/team), and set it as an environment variable.
+    Copy your API key from [the TestDriver dashboard](https://console.testdriver.ai/team), and set it as an environment variable.
 
     <Tabs>
       <Tab title="macOS / Linux">

package/docs/v7/presets/chrome.mdx

@@ -9,6 +9,22 @@ icon: "chrome"
 
 The `chrome()` preset automatically sets up a Chrome browser with TestDriver and Dashcam recording. It's the easiest way to test web applications.
 
+<Note>
+  **Recommended Pattern (v7.1+):** Use `TestDriver()` hook + `provision.chrome()` for more flexibility:
+  
+  ```javascript
+  import { TestDriver } from 'testdriverai/vitest/hooks';
+  
+  test('my test', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://example.com' });
+    // ...
+  });
+  ```
+  
+  The `chrome()` preset is still supported but the direct API provides better control and clearer lifecycle management.
+</Note>
+
 ## Quick Start
 
 ```javascript

package/docs/v7/presets/electron.mdx

@@ -9,6 +9,24 @@ icon: "atom"
 
 The `electron()` preset automatically sets up an Electron application with TestDriver and Dashcam recording. Perfect for testing desktop apps built with Electron.
 
+<Note>
+  **Recommended Pattern (v7.1+):** Use `TestDriver()` hook + `provision.electron()` for more flexibility:
+  
+  ```javascript
+  import { TestDriver } from 'testdriverai/vitest/hooks';
+  
+  test('my test', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.electron({ 
+      appPath: './dist/my-app'
+    });
+    // ...
+  });
+  ```
+  
+  The `electron()` preset is still supported but the direct API provides better control and clearer lifecycle management.
+</Note>
+
 ## Quick Start
 
 ```javascript

package/docs/v7/presets/vscode.mdx

@@ -9,6 +9,25 @@ icon: "code"
 
 The `vscode()` preset automatically sets up Visual Studio Code with TestDriver and Dashcam recording. Perfect for testing VS Code extensions and IDE workflows.
 
+<Note>
+  **Recommended Pattern (v7.1+):** Use `TestDriver()` hook + `provision.vscode()` for more flexibility:
+  
+  ```javascript
+  import { TestDriver } from 'testdriverai/vitest/hooks';
+  
+  test('my test', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.vscode({ 
+      workspace: '/tmp/project',
+      extensions: ['ms-python.python']
+    });
+    // ...
+  });
+  ```
+  
+  The `vscode()` preset is still supported but the direct API provides better control and clearer lifecycle management.
+</Note>
+
 ## Quick Start
 
 ```javascript

package/examples/run-tests-with-recording.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+
+# Example script showing how to run tests with TestDriver + Dashcam integration
+# This script demonstrates the complete flow:
+# 1. Start dashcam
+# 2. Run tests with Vitest reporter
+# 3. Stop and publish dashcam recording
+# 4. View results in TestDriver dashboard
+
+set -e
+
+echo "======================================"
+echo "TestDriver + Dashcam Test Recording"
+echo "======================================"
+echo ""
+
+# Check for required environment variables
+if [ -z "$TD_API_KEY" ]; then
+  echo "Error: TD_API_KEY environment variable is required"
+  echo "Get your API key from: https://console.testdriver.ai/settings/api-keys"
+  exit 1
+fi
+
+if [ -z "$DASHCAM_PROJECT_ID" ]; then
+  echo "Warning: DASHCAM_PROJECT_ID not set, replays won't be published"
+fi
+
+# Start Dashcam recording
+echo "📹 Starting Dashcam..."
+dashcam start
+
+# Track test logs
+echo "📝 Tracking test output..."
+dashcam track --name="TestDriver Tests" --type=application --pattern="*.log"
+
+echo ""
+
+# Run tests with Vitest and TestDriver reporter
+echo "🧪 Running tests..."
+npx vitest run --config vitest.config.example.js
+
+# Capture exit code
+TEST_EXIT_CODE=$?
+
+# Stop dashcam
+echo ""
+echo "🛑 Stopping Dashcam..."
+dashcam stop
+
+# Publish to dashcam project if configured
+if [ -n "$DASHCAM_PROJECT_ID" ]; then
+  echo "📤 Publishing replay to project: $DASHCAM_PROJECT_ID"
+  REPLAY_URL=$(dashcam publish -p "$DASHCAM_PROJECT_ID" --json | jq -r '.replayUrl')
+  echo "✅ Replay URL: $REPLAY_URL"
+  echo ""
+  echo "View your test recording at:"
+  echo "$REPLAY_URL"
+else
+  echo "⚠️  Skipping publish (DASHCAM_PROJECT_ID not set)"
+fi
+
+echo ""
+echo "======================================"
+echo "📊 View Results"
+echo "======================================"
+echo "Dashboard: https://console.testdriver.ai/dashboard/test-runs"
+echo ""
+
+# Exit with the same code as tests
+exit $TEST_EXIT_CODE

package/examples/screenshot-example.js

@@ -0,0 +1,63 @@
+/**
+ * TestDriver SDK - Screenshot Example
+ *
+ * This example demonstrates how to use the screenshot() method
+ * to capture screenshots of the sandbox environment.
+ */
+
+const TestDriver = require("../sdk.js");
+const fs = require("fs");
+const path = require("path");
+
+async function main() {
+  // Initialize TestDriver SDK
+  const client = new TestDriver(process.env.TD_API_KEY);
+
+  try {
+    // Connect to sandbox
+    console.log("Connecting to sandbox...");
+    await client.connect();
+
+    // Navigate to a website
+    console.log("Opening Chrome and navigating to example.com...");
+    await client.focusApplication("Google Chrome");
+    const urlBar = await client.find("URL bar in Chrome");
+    await urlBar.click();
+    await client.type("https://example.com");
+    await client.pressKeys(["enter"]);
+
+    // Wait a moment for page to load
+    await client.wait(2000);
+
+    // Capture a screenshot
+    console.log("Capturing screenshot...");
+    const screenshot = await client.screenshot();
+
+    // Save screenshot to file
+    const outputPath = path.join(__dirname, "example-screenshot.png");
+    fs.writeFileSync(outputPath, Buffer.from(screenshot, "base64"));
+    console.log(`Screenshot saved to: ${outputPath}`);
+
+    // You can also capture with the mouse cursor visible
+    console.log("Capturing screenshot with mouse cursor...");
+    await client.hover(400, 300);
+    const screenshotWithMouse = await client.screenshot(1, false, true);
+
+    const outputPathWithMouse = path.join(
+      __dirname,
+      "example-screenshot-with-mouse.png",
+    );
+    fs.writeFileSync(
+      outputPathWithMouse,
+      Buffer.from(screenshotWithMouse, "base64"),
+    );
+    console.log(`Screenshot with mouse saved to: ${outputPathWithMouse}`);
+  } catch (error) {
+    console.error("Error:", error);
+  } finally {
+    // Clean up
+    await client.disconnect();
+  }
+}
+
+main();