npm - @testdriverai/mcp - Versions diffs - 7.11.136-test → 7.11.138-test - Mend

@testdriverai/mcp 7.11.136-test → 7.11.138-test

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (174) hide show

package/docs/v7/client.mdx DELETED Viewed

@@ -1,486 +0,0 @@
----
-title: "TestDriver Client"
-sidebarTitle: "Client"
-description: "Initialize and configure the TestDriver SDK client"
-icon: "plug"
----
-## Overview
-The `TestDriver` client is the main entry point for the SDK. It handles authentication, sandbox connection, and provides access to all testing 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">
-  Configuration options for the client
-  <Expandable title="properties">
-    <ParamField path="os" type="string" default="linux">
-      Operating system for the sandbox: `'windows'` or `'linux'`
-    </ParamField>
-    <ParamField path="resolution" type="string" default="1366x768">
-      Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`). Custom resolutions are only available on Enterprise plans.
-    </ParamField>
-    <ParamField path="apiRoot" type="string">
-      API endpoint URL (typically only changed for self-hosted deployments)
-    </ParamField>
-    <ParamField path="analytics" type="boolean" default="true">
-      Enable or disable usage analytics
-    </ParamField>
-    <ParamField path="logging" type="boolean" default="true">
-      Enable or disable console logging
-    </ParamField>
-    <ParamField path="autoScreenshots" type="boolean" default="false">
-      Automatically capture screenshots before and after each command. Screenshots are saved to `.testdriver/screenshots/<test>/` with descriptive filenames that include the line number and action name. Format: `<seq>-<action>-<phase>-L<line>-<description>.png`
-    </ParamField>
-    <ParamField path="newSandbox" type="boolean" default="true">
-      Force creation of a new sandbox instead of reusing an existing one
-    </ParamField>
-    <ParamField path="reconnect" type="boolean" default="false">
-      Reattach to the last used sandbox instead of creating a new one. When `true`, the SDK reads the sandbox id from `.testdriver/last-sandbox` (written automatically on every successful connect) and rejoins that VM. Provision methods (`chrome`, `vscode`, `installer`, etc.) are skipped because the application is already running. The previous sandbox must still be alive — see [`keepAlive`](#keepalive) and the [Run guide](/v7/copilot/running-tests#keeping-machines-alive-between-runs).
-    </ParamField>
-    <ParamField path="sandboxId" type="string">
-      Reattach to a specific sandbox id instead of the one recorded in `.testdriver/last-sandbox`. Use this for CI matrices or to pin a chain of tests to a known VM. Implies `reconnect: true` behavior (provision calls are skipped).
-    </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="debugOnFailure" type="boolean" default="false">
-      Keep the sandbox alive when a test fails so you can reconnect and debug interactively. The sandbox ID is printed to the console.
-    </ParamField>
-    <ParamField path="ip" type="string">
-      Direct IP address to connect to a running sandbox instance (for self-hosted deployments)
-    </ParamField>
-    <ParamField path="sandboxAmi" type="string">
-      Custom AMI ID for the sandbox instance (AWS deployments, e.g., `'ami-1234'`)
-    </ParamField>
-    <ParamField path="sandboxInstance" type="string">
-      EC2 instance type for the sandbox (AWS deployments, e.g., `'i3.metal'`)
-    </ParamField>
-    <ParamField path="cache" type="boolean | object" default="true">
-      Enable or disable element caching, or provide advanced threshold configuration.
-      <Expandable title="advanced config">
-        <ParamField path="enabled" type="boolean" default="true">
-          Enable or disable caching
-        </ParamField>
-        <ParamField path="thresholds" type="object">
-          Fine-tune cache matching
-          <Expandable title="properties">
-            <ParamField path="find" type="object">
-              Thresholds for `find()` operations
-              <Expandable title="properties">
-                <ParamField path="screen" type="number" default="0.05">
-                  Pixel diff threshold for screen comparison (0-1). `0.05` = 5% diff allowed.
-                </ParamField>
-                <ParamField path="element" type="number" default="0.8">
-                  OpenCV template match threshold for element matching (0-1). `0.8` = 80% correlation.
-                </ParamField>
-              </Expandable>
-            </ParamField>
-            <ParamField path="assert" type="number" default="0.05">
-              Pixel diff threshold for `assert()` operations (0-1). `0.05` = 5% diff allowed.
-            </ParamField>
-          </Expandable>
-        </ParamField>
-      </Expandable>
-    </ParamField>
-    <ParamField path="cacheKey" type="string">
-      Cache key for element finding operations. If provided, enables caching tied to this key.
-    </ParamField>
-    <ParamField path="verify" type="boolean" default="false">
-      Global default for AI verification of located elements. When `true`, every `find()` runs a second AI check to confirm the returned coordinates actually match the requested element (catching hallucinated or incorrect positions), at the cost of extra latency. Can be overridden per call via `find(description, { verify: true | false })`.
-    </ParamField>
-    <ParamField path="dashcam" type="boolean" default="true">
-      Enable or disable Dashcam video recording
-    </ParamField>
-    <ParamField path="redraw" type="boolean | object" default="true">
-      Enable or disable screen-change (redraw) detection, or provide advanced configuration.
-      <Expandable title="advanced config">
-        <ParamField path="enabled" type="boolean" default="true">
-          Enable or disable redraw detection
-        </ParamField>
-        <ParamField path="thresholds" type="object">
-          Threshold configuration
-          <Expandable title="properties">
-            <ParamField path="screen" type="number | false" default="0.05">
-              Pixel diff threshold (0-1). Set to `false` to disable screen redraw detection.
-            </ParamField>
-            <ParamField path="network" type="boolean" default="false">
-              Enable or disable network activity monitoring
-            </ParamField>
-          </Expandable>
-        </ParamField>
-      </Expandable>
-    </ParamField>
-    <ParamField path="environment" type="object">
-      Additional environment variables to pass to the sandbox
-    </ParamField>
-    <ParamField path="ai" type="object">
-      Global AI sampling configuration. Controls how the AI model generates responses for `find()` verification and `assert()` calls. Can be overridden per call.
-      <Expandable title="properties">
-        <ParamField path="temperature" type="number">
-          Controls randomness in AI responses. `0` = deterministic (best for verification), higher values = more creative. Default: `0` for find verification, model default for assert.
-        </ParamField>
-        <ParamField path="top" type="object">
-          Nucleus and top-k sampling parameters
-          <Expandable title="properties">
-            <ParamField path="p" type="number">
-              Top-P (nucleus sampling). Limits token choices to the smallest set whose cumulative probability exceeds P. Lower values = more focused responses. Range: 0-1.
-            </ParamField>
-            <ParamField path="k" type="number">
-              Top-K sampling. Limits token choices to the top K most likely tokens. `1` = always pick the most likely token. `0` = disabled (consider all tokens).
-            </ParamField>
-          </Expandable>
-        </ParamField>
-      </Expandable>
-    </ParamField>
-  </Expandable>
-</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>