testdriverai 7.8.0-test.7 → 7.8.0-test.71

package/docs/v7/copilot/setup.mdx

@@ -0,0 +1,143 @@
+---
+title: "GitHub Copilot Setup"
+sidebarTitle: "IDE Setup"
+description: "Install the TestDriver extension and configure MCP for GitHub Copilot"
+icon: "wrench"
+---
+
+TestDriver integrates with GitHub Copilot through the VS Code extension and MCP server. This guide walks you through the complete setup.
+
+## Prerequisites
+
+Before you begin, you'll need:
+
+- **GitHub Copilot** — A subscription with MCP access. A [free tier](https://github.com/features/copilot/plans) is available.
+- **TestDriver Account** — Create a free account at [console.testdriver.ai](https://console.testdriver.ai/team) to get your API key. 60 free device minutes, no credit card required.
+- **VS Code** — The TestDriver extension provides the best experience with live preview and integrated test running.
+
+## Setup Steps
+
+<Steps>
+  <Step title="Install the TestDriver Extension">
+    <Card
+      horizontal
+      title="Install TestDriver for VS Code"
+      arrow
+      href="vscode:extension/testdriver.testdriver"
+      icon="/images/content/extension/vscode.svg"
+    ></Card>
+
+    The extension provides:
+    - One-click sign-in and project initialization
+    - Live preview panel for watching tests execute
+    - MCP server configuration
+  </Step>
+
+  <Step title="Sign Into TestDriver">
+    Sign in to connect your account and API key.
+
+    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+    2. Run **TestDriver: Login**
+    3. Your browser will open to the TestDriver sign-in page
+    4. Sign in (or create an account)
+    5. You'll be redirected back to VS Code, now signed in
+
+    <Tip>
+      The extension automatically saves your API key to VS Code's secure storage and your workspace `.env` file.
+    </Tip>
+  </Step>
+
+  <Step title="Initialize Your Project">
+    Set up TestDriver in your project with a single command.
+
+    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+    2. Run **TestDriver: Init Project**
+
+    This command:
+    - Creates a `package.json` with TestDriver and Vitest dependencies
+    - Generates a `vitest.config.mjs` with proper timeout settings
+    - Creates example test files in `tests/`
+    - Sets up `.env` with your API key
+    - Creates the TestDriver agent file at `.github/agents/testdriver.agent.md`
+    - Configures the MCP server
+
+    <Note>
+      If you already have a `package.json`, the command will add the necessary dependencies to it.
+    </Note>
+  </Step>
+
+  <Step title="Start the MCP Server">
+    The MCP server enables GitHub Copilot to control TestDriver sandboxes.
+
+    After initialization, the MCP configuration is created at `.vscode/mcp.json`:
+
+    ```json .vscode/mcp.json
+    {
+      "servers": {
+        "testdriver": {
+          "command": "npx",
+          "args": ["-p", "testdriverai", "testdriverai-mcp"],
+          "env": {
+            "TD_PREVIEW": "ide",
+            "TD_API_KEY": "your-api-key"
+          }
+        }
+      }
+    }
+    ```
+
+    **To start the MCP server:**
+
+    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+    2. Run **MCP: List Servers**
+    3. Click on the **testdriver** server
+    4. Select **Start Server**
+
+    You can also click the MCP icon in the status bar to manage servers.
+
+    <Tip>
+      See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details on managing MCP servers.
+    </Tip>
+
+    <Warning>
+      Make sure your API key is set. The extension uses the key from your sign-in, but you can also set it via the `TD_API_KEY` environment variable.
+    </Warning>
+  </Step>
+
+  <Step title="Install Vitest Extension (Recommended)">
+    For the best experience running tests, install the Vitest extension:
+
+    <Card
+      horizontal
+      title="Vitest Extension"
+      arrow
+      href="vscode:extension/vitest.explorer"
+      icon="flask-vial"
+    >
+      Run tests with GUI mode from the Test Explorer
+    </Card>
+
+    After installation, you'll see a beaker icon in the sidebar for accessing the Test Explorer.
+  </Step>
+</Steps>
+
+## Verify Your Setup
+
+To verify everything is configured correctly:
+
+1. Open the command palette and run **TestDriver: Check Status**
+2. You should see:
+   - ✅ Signed in
+   - ✅ MCP server configured
+   - ✅ Project initialized
+
+## The Agent File
+
+During initialization, TestDriver creates an agent file at `.github/agents/testdriver.agent.md`. This file tells GitHub Copilot how to use TestDriver's MCP tools.
+
+The agent has access to tools like:
+- `session_start` — Launch a sandbox with Chrome or other apps
+- `find` / `click` / `type` — Interact with elements on screen
+- `assert` — Verify conditions using AI vision
+- `screenshot` — Capture the current screen state
+

package/docs/v7/enterprise.mdx

@@ -1,116 +1,9 @@
 ---
 title: "Enterprise"
 sidebarTitle: "Enterprise"
-description: "Air-gapped security and full customization for demanding environments"
+description: "Self-hosted enterprise deployments with assisted setup and dedicated support"
 icon: "building"
+redirect: "/v7/self-hosted"
 ---
 
-
-## Why Enterprise?
-
-<CardGroup cols={2}>
-  <Card title="Air-Gapped Security" icon="shield-check">
-    Deploy everything in your environment. No data leaves your network. Complete isolation from external services.
-  </Card>
-  <Card title="Full Customization" icon="gear">
-    Custom integrations, dedicated infrastructure, and tailored solutions for your unique requirements.
-  </Card>
-  <Card title="Self-Hosted Dashboard & API" icon="server">
-    Run the entire TestDriver stack — dashboard, API, and test infrastructure — within your own environment.
-  </Card>
-  <Card title="Dedicated Support" icon="headset">
-    Direct access to our engineering team for implementation, customization, and ongoing support.
-  </Card>
-</CardGroup>
-
-## Who Needs Enterprise?
-
-Enterprise is designed for organizations that:
-
-- **Require air-gapped deployments** — Regulated industries, government, defense, or strict compliance requirements
-- **Cannot use external APIs** — Data must never leave your network perimeter
-- **Need custom integrations** — Unique CI/CD systems, internal tools, or specialized workflows
-- **Want dedicated support** — Direct engineering support for complex implementations
-
-## What's Included
-
-### Fully Self-Hosted Stack
-
-Unlike [Self-Hosted](/v7/self-hosted) (which uses TestDriver's hosted dashboard and API), Enterprise deploys everything in your environment:
-
-| Component | Self-Hosted | Enterprise |
-|-----------|-------------|------------|
-| Test Sandboxes | Your infrastructure | Your infrastructure |
-| Dashboard | TestDriver hosted | Your infrastructure |
-| API | TestDriver hosted | Your infrastructure |
-| AI Processing | Your API keys | Your infrastructure |
-| Data Storage | Your AWS account | Your infrastructure |
-
-### Custom Contract Terms
-
-- Volume-based pricing
-- Custom SLAs
-- Dedicated support channels
-- Professional services for implementation
-- Training for your team
-
-## Implementation Process
-
-<Steps>
-  <Step title="Discovery Call">
-    Discuss your requirements, security constraints, and integration needs with our team.
-  </Step>
-  
-  <Step title="Architecture Review">
-    Our engineers design a deployment architecture that meets your security and compliance requirements.
-  </Step>
-  
-  <Step title="Deployment">
-    We work with your team to deploy TestDriver within your environment, including dashboard, API, and test infrastructure.
-  </Step>
-  
-  <Step title="Integration">
-    Connect TestDriver to your CI/CD pipelines, internal tools, and workflows.
-  </Step>
-  
-  <Step title="Training & Handoff">
-    Comprehensive training for your team on operating and maintaining the deployment.
-  </Step>
-</Steps>
-
-## Security & Compliance
-
-Enterprise deployments support:
-
-- **SOC 2** compliance requirements
-- **HIPAA** for healthcare applications
-- **FedRAMP** for government deployments
-- **PCI DSS** for payment processing
-- **Custom compliance frameworks** as needed
-
-<Note>
-  All data remains within your network perimeter. TestDriver has no access to your test results, application data, or infrastructure.
-</Note>
-
-## Comparison: Self-Hosted vs Enterprise
-
-| Feature | Self-Hosted | Enterprise |
-|---------|-------------|------------|
-| **Test Infrastructure** | Your AWS | Your infrastructure (any) |
-| **Dashboard** | TestDriver cloud | Your infrastructure |
-| **API** | TestDriver cloud | Your infrastructure |
-| **Data Location** | Your AWS + TestDriver | 100% your infrastructure |
-| **Network Requirements** | Internet access | Can be fully air-gapped |
-| **Cloud Providers** | AWS only | Any (AWS, Azure, GCP, on-prem) |
-| **Support** | Standard | Dedicated engineering |
-| **Contract** | Standard licensing | Custom terms |
-
-## Get Started
-
-<Card
-  title="Schedule a Consultation"
-  icon="calendar"
-  href="https://calendly.com/d/cq23-qyn-3v6/testdriver-ai-demo"
->
-  Discuss your requirements with our team and get a custom proposal for your Enterprise deployment.
-</Card>
+This page has moved to [Self-Hosted](/v7/self-hosted).

package/docs/v7/errors.mdx

@@ -0,0 +1,248 @@
+---
+title: "Errors"
+sidebarTitle: "Errors"
+description: "Custom error classes and error handling"
+icon: "triangle-exclamation"
+mode: "wide"
+---
+
+## Overview
+
+TestDriver provides custom error classes with rich debugging information. These are exported from the SDK and can be used for `instanceof` checks in your tests.
+
+```javascript
+import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
+```
+
+## ElementNotFoundError
+
+Thrown when `find()` cannot locate an element on screen, or when calling `click()`/`hover()` on an unfound element.
+
+```javascript
+try {
+  await testdriver.find('nonexistent button').click();
+} catch (error) {
+  if (error instanceof ElementNotFoundError) {
+    console.log(error.description);       // "nonexistent button"
+    console.log(error.screenshotPath);    // path to debug screenshot
+    console.log(error.pixelDiffPath);     // path to pixel diff image
+  }
+}
+```
+
+### Properties
+
+<ParamField path="name" type="string">
+  Always `"ElementNotFoundError"`.
+</ParamField>
+
+<ParamField path="message" type="string">
+  Enhanced message with a debug block containing element description, cache status, similarity scores, and AI response details.
+</ParamField>
+
+<ParamField path="description" type="string">
+  The original element description passed to `find()`.
+</ParamField>
+
+<ParamField path="screenshotPath" type="string | null">
+  Absolute path to a debug screenshot saved at the time of failure. Written to `<os.tmpdir>/testdriver-debug/screenshot-<timestamp>.png`.
+</ParamField>
+
+<ParamField path="pixelDiffPath" type="string | null">
+  Absolute path to a pixel diff image showing the comparison between the cached and current screenshots. Written to `<os.tmpdir>/testdriver-debug/pixel-diff-error-<timestamp>.png`. Only present when cache was involved.
+</ParamField>
+
+<ParamField path="cachedImagePath" type="string | null">
+  URL to the cached image that was compared against.
+</ParamField>
+
+<ParamField path="aiResponse" type="object | null">
+  Sanitized AI response object. Large binary fields (`croppedImage`, `screenshot`, `pixelDiffImage`) are removed. Contains cache metadata like `similarity`, `cacheHit`, `cacheStrategy`, `cacheDiffPercent`, and `threshold`.
+</ParamField>
+
+<ParamField path="timestamp" type="string">
+  ISO 8601 timestamp of when the error was created.
+</ParamField>
+
+### Enhanced Message
+
+The error message is automatically enhanced with debugging information:
+
+```
+Element not found: "submit button"
+
+=== Element Debug Info ===
+Element: submit button
+Cache Hit: false
+Similarity: 0.23
+Cache Strategy: pixel-diff
+Threshold: 0.05
+AI Response Element: null
+```
+
+### Stack Trace Cleaning
+
+Stack traces are automatically cleaned to remove internal SDK frames (`Element.*`, `sdk.js` internals), showing only your test code for easier debugging.
+
+## AIError
+
+Thrown when `act()` exhausts all retry attempts.
+
+```javascript
+try {
+  await testdriver.act('perform complex workflow', { tries: 3 });
+} catch (error) {
+  if (error instanceof AIError) {
+    console.log(error.task);       // "perform complex workflow"
+    console.log(error.tries);     // 3
+    console.log(error.duration);  // 15234 (ms)
+    console.log(error.cause);     // underlying Error
+  }
+}
+```
+
+### Properties
+
+<ParamField path="name" type="string">
+  Always `"AIError"`.
+</ParamField>
+
+<ParamField path="message" type="string">
+  Enhanced message with execution details block.
+</ParamField>
+
+<ParamField path="task" type="string">
+  The task description passed to `act()`.
+</ParamField>
+
+<ParamField path="tries" type="number">
+  Number of attempts that were made.
+</ParamField>
+
+<ParamField path="maxTries" type="number">
+  Maximum number of attempts configured.
+</ParamField>
+
+<ParamField path="duration" type="number">
+  Total execution time in milliseconds.
+</ParamField>
+
+<ParamField path="cause" type="Error | undefined">
+  The underlying error that caused the final failure.
+</ParamField>
+
+<ParamField path="timestamp" type="string">
+  ISO 8601 timestamp of when the error was created.
+</ParamField>
+
+### Enhanced Message
+
+```
+AI failed: Element not found after 3 attempts
+
+=== AI Execution Details ===
+Task: perform complex workflow
+Tries: 3 / 3
+Duration: 15234ms
+Cause: ElementNotFoundError: Element not found: "submit button"
+```
+
+## Internal Error Classes
+
+These errors are used internally by the agent and are not exported, but may appear as the `cause` of an `AIError`:
+
+### MatchError
+
+Thrown when element matching fails (text, image, or assertion).
+
+| Property | Type | Description |
+|---|---|---|
+| `fatal` | `boolean` | If `true`, cannot be healed. Default: `false` |
+| `attachScreenshot` | `boolean` | Always `true` — a screenshot is attached to the error |
+
+### CommandError
+
+Thrown for invalid arguments or unsupported operations.
+
+| Property | Type | Description |
+|---|---|---|
+| `fatal` | `boolean` | Always `true` |
+| `attachScreenshot` | `boolean` | Always `false` |
+
+## Soft Assert Mode
+
+Inside `act()`, assertions run in **soft assert mode**. When an assertion fails, it returns the failure result instead of throwing, allowing the AI to process the failure and adjust its approach.
+
+```javascript
+// Inside act(), assertion failures don't throw
+await testdriver.act('verify the dashboard shows correct data', {
+  tries: 3,
+});
+// The AI can see assertion results and self-correct
+```
+
+This is automatic — you don't need to configure it. Regular `assert()` calls outside of `act()` will throw normally on failure.
+
+## Error Handling Patterns
+
+### Catching Specific Errors
+
+```javascript
+import TestDriver, { ElementNotFoundError, AIError } from 'testdriverai';
+
+try {
+  await testdriver.find('submit button').click();
+} catch (error) {
+  if (error instanceof ElementNotFoundError) {
+    // Element wasn't found — check screenshot for debugging
+    console.log('Debug screenshot:', error.screenshotPath);
+  } else if (error instanceof AIError) {
+    // AI exhausted retries
+    console.log(`Failed after ${error.tries} tries in ${error.duration}ms`);
+  } else {
+    throw error; // Unexpected error
+  }
+}
+```
+
+### Using Debug Screenshots
+
+```javascript
+try {
+  const el = await testdriver.find('checkout button');
+  await el.click();
+} catch (error) {
+  if (error instanceof ElementNotFoundError) {
+    // Screenshot of what the screen looked like
+    console.log('Screen:', error.screenshotPath);
+    // Pixel diff showing cache comparison
+    console.log('Diff:', error.pixelDiffPath);
+    // Full AI response metadata
+    console.log('AI:', JSON.stringify(error.aiResponse, null, 2));
+  }
+}
+```
+
+## Types
+
+```typescript
+class ElementNotFoundError extends Error {
+  name: 'ElementNotFoundError';
+  description: string;
+  screenshotPath: string | null;
+  pixelDiffPath: string | null;
+  cachedImagePath: string | null;
+  aiResponse: Record<string, any> | null;
+  timestamp: string;
+}
+
+class AIError extends Error {
+  name: 'AIError';
+  task: string;
+  tries: number;
+  maxTries: number;
+  duration: number;
+  cause?: Error;
+  timestamp: string;
+}
+```