Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
apiKey
string
required
Your TestDriver API key from the dashboard
​
options
object
Configuration options for the client

​
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

​
options
object
Connection options
Returns: Promise&lt;Object&gt; - 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

Use beforeAll/afterAll to create one sandbox per test suite rather than per test. This significantly reduces execution time.
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;
}
Use afterAll or try-finally blocks to ensure disconnect() is called even if tests fail. This prevents orphaned sandboxes.
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();