How do I install the Testdriver:client skill?

Run npx skillmds@latest add testdriverai/testdriver-client in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Testdriver:client skill do?

Initialize and configure the TestDriver SDK client It is listed under Coding & Dev Tools on SkillMD.

Is Testdriver:client safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Testdriver:client?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Testdriver:client free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Testdriver:client?

testdriverai (@testdriverai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Testdriver:client by testdriverai — Agent Skill

Name: Testdriver:client
Author: testdriverai

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

const testdriver = new TestDriver(apiKey, options)

Parameters

<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](/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>

Example

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.

await testdriver.auth()

Returns: Promise<string> - Authentication token

Example:

await testdriver.auth();

Connection Management

connect()

Connect to a sandbox environment. This creates or reconnects to a virtual machine where your tests will run.

await testdriver.connect(options)

Parameters

<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>

Returns: Promise<Object> - Sandbox instance details including instanceId, ip, vncPort, etc.

Examples

Basic connection:

await testdriver.connect();

Reconnect to existing sandbox:

const instance = await testdriver.connect({ 
  sandboxId: 'existing-sandbox-id-123' 
});

Self-hosted sandbox:

await testdriver.connect({ 
  ip: '192.168.1.100'
});

disconnect()

Disconnect from the sandbox and clean up resources.

await testdriver.disconnect()

Returns: Promise<void>

Example:

afterAll(async () => {
  await testdriver.disconnect();
});

Instance Information

getInstance()

Get the current sandbox instance details.

const instance = testdriver.getInstance()

Returns: Object | null - Sandbox instance information

Example:

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.

const sessionId = testdriver.getSessionId()

Returns: string | null - Session ID

Example:

const sessionId = testdriver.getSessionId();
console.log('Session:', sessionId);

Logging & Events

setLogging()

Enable or disable console logging at runtime.

testdriver.setLogging(enabled)

Parameters:

enabled (boolean) - Whether to enable logging

Example:

// Disable logging for cleanup operations
testdriver.setLogging(false);
await testdriver.disconnect();
testdriver.setLogging(true);

getEmitter()

Get the event emitter for custom event handling.

const emitter = testdriver.getEmitter()

Returns: EventEmitter2 - Event emitter instance

Example:

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

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

```javascript
try {
  await testdriver.connect();
} catch (error) {
  console.error('Failed to connect:', error.message);
  throw error;
}
```

```bash .env
TD_API_KEY=your_api_key_here
```

```javascript
// API key is loaded automatically - no need to pass it!
const testdriver = new TestDriver();
```

Testdriver:client

File contents

Overview

Constructor

Parameters

Example

Authentication

auth()

Connection Management

connect()

Parameters

Examples

disconnect()

Instance Information

getInstance()

getSessionId()

Logging & Events

setLogging()

getEmitter()

Complete Example

Best Practices

Frequently asked questions

Testdriver:client

File contents

Overview

Constructor

Parameters

Example

Authentication

auth()

Connection Management

connect()

Parameters

Examples

disconnect()

Instance Information

getInstance()

getSessionId()

Logging & Events

setLogging()

getEmitter()

Complete Example

Best Practices

Related skills

Frequently asked questions

How do I install the Testdriver:client skill?

What does the Testdriver:client skill do?

Is Testdriver:client safe to use?

Which AI agents work with Testdriver:client?

Is Testdriver:client free to use?

Who published Testdriver:client?