Testdriver:Client

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

javascriptCopy code
const testdriver = new TestDriver(apiKey, options)

Parameters

Example

javascriptCopy code
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.

javascriptCopy code
await testdriver.auth()

Returns: Promise<string> - Authentication token

Example:

javascriptCopy code
await testdriver.auth();

Connection Management

connect()

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

javascriptCopy code
await testdriver.connect(options)

Parameters

Copy code
<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:

javascriptCopy code
await testdriver.connect();

Reconnect to existing sandbox:

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

Self-hosted sandbox:

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

disconnect()

Disconnect from the sandbox and clean up resources.

javascriptCopy code
await testdriver.disconnect()

Returns: Promise<void>

Example:

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

Instance Information

getInstance()

Get the current sandbox instance details.

javascriptCopy code
const instance = testdriver.getInstance()

Returns: Object | null - Sandbox instance information

Example:

javascriptCopy code
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.

javascriptCopy code
const sessionId = testdriver.getSessionId()

Returns: string | null - Session ID

Example:

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

Logging & Events

setLogging()

Enable or disable console logging at runtime.

javascriptCopy code
testdriver.setLogging(enabled)

Parameters:

• enabled (boolean) - Whether to enable logging

Example:

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

getEmitter()

Get the event emitter for custom event handling.

javascriptCopy code
const emitter = testdriver.getEmitter()

Returns: EventEmitter2 - Event emitter instance

Example:

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

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

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

Copy code
```bash .env
TD_API_KEY=your_api_key_here
```

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