TestDriver Client

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

string

required

Your TestDriver API key from the dashboard

object

Configuration options for the client

Show properties

string

default:"linux"

Operating system for the sandbox: 'windows' or 'linux'

string

default:"1366x768"

Screen resolution for the sandbox (e.g., '1920x1080', '1366x768'). Custom resolutions are only available on Enterprise plans.

string

API endpoint URL (typically only changed for self-hosted deployments)

boolean

default:"true"

Enable or disable usage analytics

boolean

default:"true"

Enable or disable console logging

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

boolean

default:"true"

Force creation of a new sandbox instead of reusing an existing one

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 and the Run guide.

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

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

boolean

default:"false"

Deprecated: Use preview: "none" instead. Run in headless mode without opening the debugger.

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.

string

Direct IP address to connect to a running sandbox instance (for self-hosted deployments)

string

Custom AMI ID for the sandbox instance (AWS deployments, e.g., 'ami-1234')

string

EC2 instance type for the sandbox (AWS deployments, e.g., 'i3.metal')

boolean | object

default:"true"

Enable or disable element caching, or provide advanced threshold configuration.

Show advanced config

boolean

default:"true"

Enable or disable caching

object

Fine-tune cache matching

Show properties

object

Thresholds for find() operations

Show properties

number

default:"0.05"

Pixel diff threshold for screen comparison (0-1). 0.05 = 5% diff allowed.

number

default:"0.8"

OpenCV template match threshold for element matching (0-1). 0.8 = 80% correlation.

number

default:"0.05"

Pixel diff threshold for assert() operations (0-1). 0.05 = 5% diff allowed.

string

Cache key for element finding operations. If provided, enables caching tied to this key.

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 }).

boolean

default:"true"

Enable or disable Dashcam video recording

boolean | object

default:"true"

Enable or disable screen-change (redraw) detection, or provide advanced configuration.

Show advanced config

boolean

default:"true"

Enable or disable redraw detection

object

Threshold configuration

Show properties

number | false

default:"0.05"

Pixel diff threshold (0-1). Set to false to disable screen redraw detection.

boolean

default:"false"

Enable or disable network activity monitoring

object

Additional environment variables to pass to the sandbox

object

Global AI sampling configuration. Controls how the AI model generates responses for find() verification and assert() calls. Can be overridden per call.

Show properties

number

Controls randomness in AI responses. 0 = deterministic (best for verification), higher values = more creative. Default: 0 for find verification, model default for assert.

object

Nucleus and top-k sampling parameters

Show properties

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.

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

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();

You must call auth() before connect(). Most examples call both sequentially.

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

object

Connection options

Show properties

boolean

default:"false"

Force creation of a new sandbox instead of reusing an existing one

string

Existing sandbox ID to reconnect to

string

Direct IP address to connect to (for self-hosted sandboxes)

string

AMI to use for the sandbox (AWS deployments)

string

Instance type for the sandbox (AWS deployments)

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

boolean

default:"false"

Deprecated: Use preview: "none" instead. Run in headless mode without opening the debugger.

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.

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

Reuse sandboxes across tests

Use beforeAll/afterAll to create one sandbox per test suite rather than per test. This significantly reduces execution time.

Handle connection errors gracefully

Wrap connect() in a try-catch block to handle network issues or quota limits:

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

Always disconnect

Use afterAll or try-finally blocks to ensure disconnect() is called even if tests fail. This prevents orphaned sandboxes.

Use environment variables for API keys

Never hardcode API keys. The SDK automatically loads TD_API_KEY from your .env file:

.env

TD_API_KEY=your_api_key_here

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

Overview

Guide

Scaling

Actions

SDK Reference

Overview

Constructor

Parameters

Example

Authentication

auth()

Connection Management

connect()

Parameters

Examples

disconnect()

Instance Information

getInstance()

getSessionId()

Logging & Events

setLogging()

getEmitter()

Complete Example

Best Practices

​Overview

​Constructor

​Parameters

​Example

​Authentication

​auth()

​Connection Management

​connect()

​Parameters

​Examples

​disconnect()

​Instance Information

​getInstance()

​getSessionId()

​Logging & Events

​setLogging()

​getEmitter()

​Complete Example

​Best Practices

Overview

Constructor

Parameters

Example

Authentication

auth()

Connection Management

connect()

Parameters

Examples

disconnect()

Instance Information

getInstance()

getSessionId()

Logging & Events

setLogging()

getEmitter()

Complete Example

Best Practices