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

# Client & Connection

> Create the TestDriver client, authenticate, and connect to a sandbox

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

```javascript theme={null}
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">
  The configuration options for the client. See [SDK Options](/options) for the full list, with defaults and examples for each option.
</ParamField>

### Example

```javascript theme={null}
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 theme={null}
await testdriver.auth()
```

**Returns:** `Promise<string>` - Authentication token

**Example:**

```javascript theme={null}
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 theme={null}
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 theme={null}
await testdriver.connect();
```

**Reconnect to existing sandbox:**

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

**Self-hosted sandbox:**

```javascript theme={null}
await testdriver.connect({ 
  ip: '192.168.1.100'
});
```

### disconnect()

Disconnect from the sandbox and clean up resources.

```javascript theme={null}
await testdriver.disconnect()
```

**Returns:** `Promise<void>`

**Example:**

```javascript theme={null}
afterAll(async () => {
  await testdriver.disconnect();
});
```

## Instance Information

### getInstance()

Get the current sandbox instance details.

```javascript theme={null}
const instance = testdriver.getInstance()
```

**Returns:** `Object | null` - Sandbox instance information

**Example:**

```javascript theme={null}
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 theme={null}
const sessionId = testdriver.getSessionId()
```

**Returns:** `string | null` - Session ID

**Example:**

```javascript theme={null}
const sessionId = testdriver.getSessionId();
console.log('Session:', sessionId);
```

## Logging & Events

### setLogging()

Enable or disable console logging at runtime.

```javascript theme={null}
testdriver.setLogging(enabled)
```

**Parameters:**

* `enabled` (boolean) - Whether to enable logging

**Example:**

```javascript theme={null}
// Disable logging for cleanup operations
testdriver.setLogging(false);
await testdriver.disconnect();
testdriver.setLogging(true);
```

### getEmitter()

Get the event emitter for custom event handling.

```javascript theme={null}
const emitter = testdriver.getEmitter()
```

**Returns:** `EventEmitter2` - Event emitter instance

**Example:**

```javascript theme={null}
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 theme={null}
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 theme={null}
    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 theme={null}
    TD_API_KEY=your_api_key_here
    ```

    ```javascript theme={null}
    // API key is loaded automatically - no need to pass it!
    const testdriver = new TestDriver();
    ```
  </Accordion>
</AccordionGroup>