@testdriverai/mcp 7.11.136-test → 7.11.138-test

package/docs/client.mdx

@@ -0,0 +1,323 @@
+---
+title: "Client & Connection"
+sidebarTitle: "Client & Connection"
+description: "Create the TestDriver client, authenticate, and connect to a sandbox"
+icon: "plug"
+---
+
+## Overview
+
+The `TestDriver` client is the main entry point for the SDK. It does the authentication and the sandbox connection. It gives access to all test methods.
+
+## Constructor
+
+```javascript
+const testdriver = new TestDriver(apiKey, options)
+```
+
+### Parameters
+
+<ParamField path="apiKey" type="string" required>
+  Your TestDriver API key from the [dashboard](https://console.testdriver.ai/settings)
+</ParamField>
+
+<ParamField path="options" type="object">
+  The configuration options for the client. See [SDK Options](/options) for the full list, with defaults and examples for each option.
+</ParamField>
+
+### Example
+
+```javascript
+import TestDriver from 'testdriverai';
+
+// API key is automatically loaded from TD_API_KEY in .env
+const testdriver = new TestDriver({
+  os: 'windows',
+  resolution: '1920x1080',
+  logging: true,
+  analytics: true
+});
+
+// With AI config for stricter verification
+const testdriver = new TestDriver({
+  ai: { temperature: 0, top: { p: 0.9, k: 40 } }
+});
+
+// Or pass API key explicitly
+const testdriver = new TestDriver('your-api-key', {
+  os: 'windows'
+});
+```
+
+## Authentication
+
+### auth()
+
+Authenticate with the TestDriver API.
+
+```javascript
+await testdriver.auth()
+```
+
+**Returns:** `Promise<string>` - Authentication token
+
+**Example:**
+```javascript
+await testdriver.auth();
+```
+
+<Note>
+  You must call `auth()` before `connect()`. Most examples call both sequentially.
+</Note>
+
+## Connection Management
+
+### connect()
+
+Connect to a sandbox environment. This creates or reconnects to a virtual machine where your tests will run.
+
+```javascript
+await testdriver.connect(options)
+```
+
+#### Parameters
+
+<ParamField path="options" type="object">
+  Connection options
+  
+  <Expandable title="properties">
+    <ParamField path="newSandbox" type="boolean" default="false">
+      Force creation of a new sandbox instead of reusing an existing one
+    </ParamField>
+    
+    <ParamField path="sandboxId" type="string">
+      Existing sandbox ID to reconnect to
+    </ParamField>
+    
+    <ParamField path="ip" type="string">
+      Direct IP address to connect to (for self-hosted sandboxes)
+    </ParamField>
+    
+    <ParamField path="sandboxAmi" type="string">
+      AMI to use for the sandbox (AWS deployments)
+    </ParamField>
+    
+    <ParamField path="sandboxInstance" type="string">
+      Instance type for the sandbox (AWS deployments)
+    </ParamField>
+    
+    <ParamField path="preview" type="string" default="browser">
+      Preview mode for live test visualization:
+      - `"browser"` - Opens debugger in default browser (default)
+      - `"ide"` - Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension)
+      - `"none"` - Headless mode, no visual preview
+    </ParamField>
+    
+    <ParamField path="headless" type="boolean" default="false">
+      **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
+    </ParamField>
+    
+    <ParamField path="keepAlive" type="number" default="60000">
+      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+**Returns:** `Promise&lt;Object&gt;` - Sandbox instance details including `instanceId`, `ip`, `vncPort`, etc.
+
+#### Examples
+
+**Basic connection:**
+```javascript
+await testdriver.connect();
+```
+
+**Reconnect to existing sandbox:**
+```javascript
+const instance = await testdriver.connect({ 
+  sandboxId: 'existing-sandbox-id-123' 
+});
+```
+
+**Self-hosted sandbox:**
+```javascript
+await testdriver.connect({ 
+  ip: '192.168.1.100'
+});
+```
+
+### disconnect()
+
+Disconnect from the sandbox and clean up resources.
+
+```javascript
+await testdriver.disconnect()
+```
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+afterAll(async () => {
+  await testdriver.disconnect();
+});
+```
+
+## Instance Information
+
+### getInstance()
+
+Get the current sandbox instance details.
+
+```javascript
+const instance = testdriver.getInstance()
+```
+
+**Returns:** `Object | null` - Sandbox instance information
+
+**Example:**
+```javascript
+const instance = testdriver.getInstance();
+console.log('Instance ID:', instance.instanceId);
+console.log('IP Address:', instance.ip);
+```
+
+### getSessionId()
+
+Get the current session ID for tracking and debugging.
+
+```javascript
+const sessionId = testdriver.getSessionId()
+```
+
+**Returns:** `string | null` - Session ID
+
+**Example:**
+```javascript
+const sessionId = testdriver.getSessionId();
+console.log('Session:', sessionId);
+```
+
+## Logging & Events
+
+### setLogging()
+
+Enable or disable console logging at runtime.
+
+```javascript
+testdriver.setLogging(enabled)
+```
+
+**Parameters:**
+- `enabled` (boolean) - Whether to enable logging
+
+**Example:**
+```javascript
+// Disable logging for cleanup operations
+testdriver.setLogging(false);
+await testdriver.disconnect();
+testdriver.setLogging(true);
+```
+
+### getEmitter()
+
+Get the event emitter for custom event handling.
+
+```javascript
+const emitter = testdriver.getEmitter()
+```
+
+**Returns:** `EventEmitter2` - Event emitter instance
+
+**Example:**
+```javascript
+const emitter = testdriver.getEmitter();
+
+emitter.on('command:start', (data) => {
+  console.log('Command started:', data);
+});
+
+emitter.on('command:success', (data) => {
+  console.log('Command succeeded:', data);
+});
+
+emitter.on('command:error', (error) => {
+  console.error('Command failed:', error);
+});
+```
+
+## Complete Example
+
+```javascript
+import { beforeAll, afterAll, describe, it } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('My Test Suite', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    // Initialize client - API key loaded automatically from .env
+    testdriver = new TestDriver({
+      os: 'windows',
+      resolution: '1366x768',
+      logging: true
+    });
+    
+    // Set up event listeners
+    const emitter = testdriver.getEmitter();
+    emitter.on('log:info', (msg) => console.log('[INFO]', msg));
+    
+    // Authenticate and connect
+    await testdriver.auth();
+    const instance = await testdriver.connect();
+    
+    console.log('Connected to sandbox:', instance.instanceId);
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('runs a test', async () => {
+    // Your test code here
+  });
+});
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Reuse sandboxes across tests">
+    Use `beforeAll`/`afterAll` to create one sandbox per test suite rather than per test. This significantly reduces execution time.
+  </Accordion>
+  
+  <Accordion title="Handle connection errors gracefully">
+    Wrap `connect()` in a try-catch block to handle network issues or quota limits:
+    
+    ```javascript
+    try {
+      await testdriver.connect();
+    } catch (error) {
+      console.error('Failed to connect:', error.message);
+      throw error;
+    }
+    ```
+  </Accordion>
+  
+  <Accordion title="Always disconnect">
+    Use `afterAll` or try-finally blocks to ensure `disconnect()` is called even if tests fail. This prevents orphaned sandboxes.
+  </Accordion>
+  
+  <Accordion title="Use environment variables for API keys">
+    Never hardcode API keys. The SDK automatically loads `TD_API_KEY` from your `.env` file:
+    
+    ```bash .env
+    TD_API_KEY=your_api_key_here
+    ```
+    
+    ```javascript
+    // API key is loaded automatically - no need to pass it!
+    const testdriver = new TestDriver();
+    ```
+  </Accordion>
+</AccordionGroup>

package/docs/{v7/copilot → copilot}/auto-healing.mdx

@@ -5,7 +5,7 @@ description: "Catch regressions automatically with CI, auto-healing, and GitHub
 icon: "shield-check"
 ---
 
-Prevent regressions by letting TestDriver run and repair itself on every change. Once you've [explored](/v7/generating-tests), [taught it your app](/v7/caching), [run it](/v7/copilot/running-tests), [validated outcomes](/v7/making-assertions), [adapted to your UI](/v7/performing-actions), and learned to [debug with screenshots](/v7/debugging-with-screenshots), the last step is closing the loop: wire TestDriver into your pull requests so regressions never reach production.
+Prevent regressions by letting TestDriver run and repair itself on every change. Once you've [explored](/generating-tests), [taught it your app](/caching), [run it](/copilot/running-tests), [validated outcomes](/making-assertions), [adapted to your UI](/performing-actions), and learned to [debug with screenshots](/debugging-with-screenshots), the last step is closing the loop: wire TestDriver into your pull requests so regressions never reach production.
 
 Your AI agent can run tests on every PR, investigate failures, and propose fixes — and you can drive all of it from GitHub itself, whether you're at your desk or on your phone.
 
@@ -407,7 +407,7 @@ It may struggle with:
 - New features requiring new assertions
 - Complex multi-step interactions
 
-For significant changes, create new tests by going back to [Explore](/v7/generating-tests) and generating them with the TestDriver agent.
+For significant changes, create new tests by going back to [Explore](/generating-tests) and generating them with the TestDriver agent.
 
 <Card title="View Your Runs" icon="chart-line" href="https://console.testdriver.ai">
   Open the TestDriver console to monitor test runs, healing PRs, and CI results across your projects.

package/docs/{v7/copilot → copilot}/running-tests.mdx

@@ -1,13 +1,13 @@
 ---
-title: "Run"
-sidebarTitle: "Run"
+title: "Running Tests"
+sidebarTitle: "Running Tests"
 description: "Set up your environment and run TestDriver tests locally and in CI"
 icon: "play"
 ---
 
 Run the tests you've explored and learned, anywhere. TestDriver tests are plain [Vitest](https://vitest.dev) files, so they run the same way on your machine and in CI — across web, desktop, and extensions on real VMs. This page walks through getting set up, configuring **where** and **how** your tests run (the device and app under test, and the sandbox machine), and actually running them locally and in CI.
 
-If you haven't written tests yet, start with [Explore](/v7/generating-tests) to generate your first tests and [Learn](/v7/caching) to make them fast and reliable.
+If you haven't written tests yet, start with [Explore](/generating-tests) to generate your first tests and [Learn](/caching) to make them fast and reliable.
 
 ## Setup
 
@@ -483,7 +483,7 @@ describe("My Test", () => {
 |--------|------|---------|-------------|
 | `os` | string | `"linux"` | Operating system |
 | `resolution` | string | `"1366x768"` | Screen resolution (Enterprise only) |
-| `e2bTemplateId` | string | — | Custom E2B template ID (see [Self-Hosted](/v7/self-hosted)) |
+| `e2bTemplateId` | string | — | Custom E2B template ID (see [Self-Hosted](/self-hosted)) |
 | `keepAlive` | number | `60000` | Ms to keep VM alive after disconnect |
 | `reconnect` | boolean | `false` | Reconnect to last used sandbox |
 
@@ -662,7 +662,7 @@ Provision scripts let you run arbitrary setup steps before your test starts —
 <Card
   title="exec() Reference"
   icon="terminal"
-  href="/v7/exec"
+  href="/exec"
 >
   Full reference for running shell and PowerShell commands in the sandbox.
 </Card>
@@ -764,7 +764,7 @@ With the **Self-Hosted Enterprise plan** you get access to our golden VM base im
 <Card
   title="Self-Hosted Enterprise"
   icon="server"
-  href="/v7/self-hosted"
+  href="/self-hosted"
 >
   Preload software, configure custom hardware, and run unlimited tests with a flat license fee. Our team assists with deployment and setup.
 </Card>
@@ -996,7 +996,7 @@ This is faster for:
 - Fixing typos
 
 <Tip>
-  When a test fails because the UI shifted, let TestDriver fix it for you automatically. See [Prevent](/v7/copilot/auto-healing) for auto-healing, and [Debug](/v7/debugging-with-screenshots) for inspecting screenshots when a run goes wrong.
+  When a test fails because the UI shifted, let TestDriver fix it for you automatically. See [Prevent](/copilot/auto-healing) for auto-healing, and [Debug](/debugging-with-screenshots) for inspecting screenshots when a run goes wrong.
 </Tip>
 
 ## Next
@@ -1004,7 +1004,7 @@ This is faster for:
 <Card
   title="Validate"
   icon="circle-check"
-  href="/v7/making-assertions"
+  href="/making-assertions"
 >
   Now that your tests run anywhere, learn how to make strong assertions that catch real bugs.
 </Card>

package/docs/{v7/customizing-devices.mdx → customizing-devices.mdx}

@@ -6,7 +6,7 @@ icon: "computer"
 
 ## TestDriver Options
 
-Configure TestDriver behavior with options passed to the `TestDriver()` function:
+Configure the TestDriver behavior with options that you give to the `TestDriver()` function:
 
 ```javascript
 const testdriver = TestDriver(context, {

package/docs/{v7/dashcam.mdx → dashcam.mdx}

@@ -7,13 +7,13 @@ icon: "video"
 
 ## Overview
 
-Dashcam provides automatic video recording and log aggregation for your tests. It captures screen recordings, application logs, and test execution details that can be reviewed later.
+Dashcam makes automatic video recordings. It also collects the logs for your tests. It captures screen recordings, application logs, and test details. You can review them later.
 
 ## Basic Usage
 
 ### With Presets
 
-Most presets automatically include Dashcam:
+Most presets include Dashcam automatically:
 
 ```javascript
 import { test } from 'vitest';
@@ -34,7 +34,7 @@ test('my test', async (context) => {
 
 ### Manual Setup
 
-For more control, create a Dashcam instance directly:
+For more control, make a Dashcam instance directly:
 
 ```javascript
 import TestDriver from 'testdriverai';

package/docs/{v7/debugging-with-screenshots.mdx → debugging-with-screenshots.mdx}

@@ -1,16 +1,16 @@
 ---
-title: "Debug"
-sidebarTitle: "Debug"
+title: "Debugging Tests"
+sidebarTitle: "Debugging Tests"
 description: "Diagnose failing tests with screenshots, replays, and logs"
 icon: "bug"
 ---
 
 ## Overview
 
-When a test fails, debug it by seeing exactly what happened — don't guess. TestDriver captures screenshots, video replays, and logs as your test runs, so you can replay the moment of failure instead of squinting at a stack trace. TestDriver MCP provides powerful commands to view and analyze the screenshots saved during test execution, enabling rapid debugging, test development, and comparison workflows without manually opening image files.
+When a test fails, debug it. Look at what happened. Do not guess. TestDriver captures screenshots, video replays, and logs while your test runs. Thus you can replay the moment of the failure. You do not need to look at a stack trace. TestDriver MCP gives commands to view and examine the screenshots that TestDriver saved during the test. This lets you debug quickly, develop tests, and compare, without a manual open of image files.
 
 <Note>
-  **Automatic Screenshots (Default: Enabled)**: TestDriver automatically captures screenshots before and after every command. Screenshots are named with the line number and action, making it easy to trace exactly which line of code produced each screenshot. For example: `001-click-before-L42-submit-button.png`
+  **Automatic Screenshots (Default: Enabled)**: TestDriver captures screenshots automatically before and after each command. The screenshot name has the line number and the action. Thus it is easy to see which line of code made each screenshot. For example: `001-click-before-L42-submit-button.png`
 </Note>
 
 ## MCP Commands
@@ -26,15 +26,15 @@ list_local_screenshots()
 **Filter Parameters:**
 
 <ParamField path="directory" type="string" optional>
-  Filter screenshots by test file or subdirectory (e.g., "login.test", "mcp-screenshots"). If omitted, lists all screenshots.
+  Filter the screenshots by test file or subdirectory (for example, "login.test", "mcp-screenshots"). If you do not give this, the tool lists all screenshots.
 </ParamField>
 
 <ParamField path="line" type="number" optional>
-  Filter by exact line number from test file (e.g., 42 matches L42 in filename).
+  Filter by the exact line number from the test file (for example, 42 matches L42 in the filename).
 </ParamField>
 
 <ParamField path="lineRange" type="object" optional>
-  Filter by line number range. Example: `{ start: 10, end: 20 }` matches screenshots from lines 10-20.
+  Filter by a line number range. Example: `{ start: 10, end: 20 }` matches screenshots from lines 10-20.
 </ParamField>
 
 <ParamField path="action" type="string" optional>
@@ -411,16 +411,16 @@ When tests fail or behave unexpectedly, replay what happened step by step:
 
 ## Where this fits in the Guide
 
-Debugging is what you reach for when a [Run](/v7/copilot/running-tests) goes sideways or a [Validate](/v7/making-assertions) assertion fails — the screenshots show you precisely what the AI saw before it acted. Once you've diagnosed the failure, the next step is to stop it from recurring.
+Debugging is what you reach for when a [Run](/copilot/running-tests) goes sideways or a [Validate](/making-assertions) assertion fails — the screenshots show you precisely what the AI saw before it acted. Once you've diagnosed the failure, the next step is to stop it from recurring.
 
 ## Related
 
-- [screenshot()](/v7/screenshot) - Capture screenshots during test execution
-- [Dashcam](/v7/dashcam) - Record full test sessions with video and logs
-- [assert()](/v7/assert) - Make AI-powered assertions that benefit from screenshot context
+- [screenshot()](/screenshot) - Capture screenshots during test execution
+- [Dashcam](/dashcam) - Record full test sessions with video and logs
+- [assert()](/assert) - Make AI-powered assertions that benefit from screenshot context
 
 ## Next
 
-<Card title="Prevent" icon="shield-check" href="/v7/copilot/auto-healing">
+<Card title="Prevent" icon="shield-check" href="/copilot/auto-healing">
   You've seen what went wrong — now keep it from happening again. Let auto-healing repair flaky tests automatically before they fail your suite.
 </Card>