@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/client.mdx

@@ -1,323 +1,269 @@
 ---
-title: "Client & Connection"
-sidebarTitle: "Client & Connection"
-description: "Create the TestDriver client, authenticate, and connect to a sandbox"
+title: "Client & connection"
+sidebarTitle: "Client & connection"
+description: "Create a TestDriver client, connect it to a sandbox, and disconnect when you're done."
 icon: "plug"
 ---
 
-## Overview
+import { EnterpriseBadge, EnterpriseCta } from '/snippets/enterprise.mdx';
 
-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.
+Every test talks to its sandbox through a TestDriver client. There are two ways to create one:
 
-## Constructor
+- **`TestDriver(context)`** from `testdriverai/vitest/hooks`. Use this in Vitest tests. It connects and disconnects for you.
+- **`new TestDriver()`** from `testdriverai`. Use this outside Vitest's per-test hooks, when you manage the connection yourself.
 
 ```javascript
-const testdriver = new TestDriver(apiKey, options)
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+test('opens the login page', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
+});
+```
+
+## TestDriver(context, options)
+
+Creates a client for the current Vitest test.
+
+```typescript
+TestDriver(context: TestContext, options?: TestDriverOptions): TestDriver
 ```
 
 ### Parameters
 
-<ParamField path="apiKey" type="string" required>
-  Your TestDriver API key from the [dashboard](https://console.testdriver.ai/settings)
+<ParamField path="context" type="TestContext" required>
+  The context Vitest passes to your test function, as in `async (context) => { ... }`. TestDriver throws if it's missing.
 </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 path="options" type="TestDriverOptions">
+  Client options, such as `os`, `preview`, `cache`, or `keepAlive`. See [Options](/options) for the full list.
+
+  <Expandable title="hook-only options">
+    <ParamField path="apiKey" type="string">
+      Your TestDriver API key. Defaults to the `TD_API_KEY` environment variable, which TestDriver also loads from `.env`.
+    </ParamField>
+    <ParamField path="debugOnFailure" type="boolean" default="false">
+      If the test fails, keep its sandbox running instead of disconnecting, and print the sandbox id so you can reconnect to it.
+    </ParamField>
+  </Expandable>
 </ParamField>
 
-### Example
+### What it does
 
-```javascript
-import TestDriver from 'testdriverai';
+- **Connects automatically.** It authenticates and connects to a sandbox in the background. Your first command waits for the connection.
+- **Disconnects automatically** when the test finishes.
+- **Returns one client per test.** Calling it again in the same test returns the same client. A retried test gets a new one.
+- **Reads `TD_OS`.** If you don't pass `os`, it uses the `TD_OS` environment variable, then Linux.
 
-// API key is automatically loaded from TD_API_KEY in .env
-const testdriver = new TestDriver({
-  os: 'windows',
-  resolution: '1920x1080',
-  logging: true,
-  analytics: true
-});
+### Returns
 
-// With AI config for stricter verification
-const testdriver = new TestDriver({
-  ai: { temperature: 0, top: { p: 0.9, k: 40 } }
-});
+A connected `TestDriver` client.
 
-// Or pass API key explicitly
-const testdriver = new TestDriver('your-api-key', {
-  os: 'windows'
-});
+## new TestDriver(apiKey, options)
+
+Creates a client that you connect and disconnect yourself.
+
+```typescript
+new TestDriver(apiKey?: string, options?: TestDriverOptions)
+new TestDriver(options?: TestDriverOptions)
 ```
 
-## Authentication
+### Parameters
 
-### auth()
+<ParamField path="apiKey" type="string">
+  Your TestDriver API key. Defaults to `TD_API_KEY`, which TestDriver loads from `.env`. Create one at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys).
+</ParamField>
 
-Authenticate with the TestDriver API.
+<ParamField path="options" type="TestDriverOptions">
+  Client options. See [Options](/options).
+</ParamField>
 
-```javascript
-await testdriver.auth()
-```
+### Example
 
-**Returns:** `Promise<string>` - Authentication token
+Share one sandbox across a test file by connecting in `beforeAll`:
 
-**Example:**
-```javascript
-await testdriver.auth();
-```
+```javascript tests/dashboard.test.mjs
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import TestDriver from 'testdriverai';
 
-<Note>
-  You must call `auth()` before `connect()`. Most examples call both sequentially.
-</Note>
+describe('Dashboard', () => {
+  let testdriver;
 
-## Connection Management
+  beforeAll(async () => {
+    testdriver = new TestDriver({ os: 'linux' });
+    await testdriver.connect();
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
+  });
 
-### connect()
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
 
-Connect to a sandbox environment. This creates or reconnects to a virtual machine where your tests will run.
+  it('shows the login form', async () => {
+    const result = await testdriver.assert('a login form is visible');
+    expect(result).toBe(true);
+  });
+});
+```
 
-```javascript
-await testdriver.connect(options)
+## connect(options)
+
+Connects the client to a sandbox. By default, it creates a new sandbox.
+
+```typescript
+testdriver.connect(options?: ConnectOptions): Promise<SandboxInstance>
 ```
 
-#### Parameters
+`connect()` authenticates first if needed. You don't need to call `auth()` yourself.
 
-<ParamField path="options" type="object">
-  Connection options
-  
+### Parameters
+
+<ParamField path="options" type="ConnectOptions">
   <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
+      Reconnect to this existing sandbox instead of creating one.
+    </ParamField>
+    <ParamField path="requireSandbox" type="boolean" default="false">
+      With `sandboxId`, throw if that sandbox is gone, instead of creating a new, empty one in its place.
+    </ParamField>
+    <ParamField path="reconnect" type="boolean">
+      Reconnect to the last sandbox this project used, recorded in `.testdriver/last-sandbox`. Provision calls are skipped, because the app is already running. Throws if there's no previous sandbox.
+    </ParamField>
+    <ParamField path="newSandbox" type="boolean" default="true">
+      Create a new sandbox. Set to `false` when you pass `sandboxId` or `reconnect`.
+    </ParamField>
+    <ParamField path="keepAlive" type="number" default="60000">
+      Milliseconds to keep the sandbox running after `disconnect()`, so you can reconnect. Capped at 30 minutes. `0` uses the default.
+    </ParamField>
+    <ParamField path="os" type="string" default="linux">
+      `"linux"` or `"windows"`. <EnterpriseBadge /> Windows is available on Enterprise plans.
+    </ParamField>
+    <ParamField path="preview" type="string" default="browser">
+      Where to show the live run: `"browser"`, `"ide"` (needs the TestDriver extension), or `"none"`.
+    </ParamField>
+    <ParamField path="reuseConnection" type="boolean" default="true">
+      Reuse a recent connection if one is available.
     </ParamField>
-    
     <ParamField path="ip" type="string">
-      Direct IP address to connect to (for self-hosted sandboxes)
+      Connect directly to a running sandbox at this IP address, for self-hosted machines. <EnterpriseBadge />
     </ParamField>
-    
     <ParamField path="sandboxAmi" type="string">
-      AMI to use for the sandbox (AWS deployments)
+      Custom AMI ID for the sandbox, for self-hosted AWS deployments. <EnterpriseBadge />
     </ParamField>
-    
     <ParamField path="sandboxInstance" type="string">
-      Instance type for the sandbox (AWS deployments)
+      EC2 instance type for the sandbox, for self-hosted AWS deployments. <EnterpriseBadge />
     </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 path="e2bTemplateId" type="string">
+      E2B template ID to create the sandbox from.
     </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.
+      Deprecated. Use `preview: "none"` instead.
     </ParamField>
   </Expandable>
 </ParamField>
 
-**Returns:** `Promise&lt;Object&gt;` - Sandbox instance details including `instanceId`, `ip`, `vncPort`, etc.
+### Returns
 
-#### Examples
-
-**Basic connection:**
-```javascript
-await testdriver.connect();
-```
-
-**Reconnect to existing sandbox:**
-```javascript
-const instance = await testdriver.connect({ 
-  sandboxId: 'existing-sandbox-id-123' 
-});
-```
+<ResponseField name="SandboxInstance" type="object">
+  <Expandable title="properties">
+    <ResponseField name="instanceId" type="string">
+      The sandbox's ID.
+    </ResponseField>
+    <ResponseField name="ip" type="string">
+      The sandbox's IP address.
+    </ResponseField>
+    <ResponseField name="vncPort" type="number">
+      The port for the sandbox's remote display.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
 
-**Self-hosted sandbox:**
-```javascript
-await testdriver.connect({ 
-  ip: '192.168.1.100'
-});
-```
+### Errors
 
-### disconnect()
+Throws `Already connected` if the client is already connected. Create a new client to connect again.
 
-Disconnect from the sandbox and clean up resources.
+### Example
 
 ```javascript
-await testdriver.disconnect()
+const testdriver = new TestDriver();
+
+// Reattach to a sandbox you kept alive earlier
+const sandbox = await testdriver.connect({ sandboxId: 'sandbox-abc123', newSandbox: false });
+console.log(sandbox.instanceId);
 ```
 
-**Returns:** `Promise<void>`
+## disconnect()
 
-**Example:**
-```javascript
-afterAll(async () => {
-  await testdriver.disconnect();
-});
+Disconnects from the sandbox. The sandbox keeps running for the `keepAlive` time, then shuts down.
+
+```typescript
+testdriver.disconnect(): Promise<void>
 ```
 
-## Instance Information
+The Vitest hook calls this for you.
 
-### getInstance()
+## auth()
 
-Get the current sandbox instance details.
+Authenticates with the TestDriver API and resolves to a session token.
 
-```javascript
-const instance = testdriver.getInstance()
+```typescript
+testdriver.auth(): Promise<string>
 ```
 
-**Returns:** `Object | null` - Sandbox instance information
+You rarely need it, because `connect()` calls it when needed.
 
-**Example:**
-```javascript
-const instance = testdriver.getInstance();
-console.log('Instance ID:', instance.instanceId);
-console.log('IP Address:', instance.ip);
-```
-
-### getSessionId()
+## getInstance()
 
-Get the current session ID for tracking and debugging.
+Returns the connected sandbox's details, or `null` if the client isn't connected.
 
-```javascript
-const sessionId = testdriver.getSessionId()
+```typescript
+testdriver.getInstance(): SandboxInstance | null
 ```
 
-**Returns:** `string | null` - Session ID
+## getSessionId()
 
-**Example:**
-```javascript
-const sessionId = testdriver.getSessionId();
-console.log('Session:', sessionId);
-```
+Returns the current session ID, or `null`. Include it when you report a problem.
 
-## Logging & Events
+```typescript
+testdriver.getSessionId(): string | null
+```
 
-### setLogging()
+## getLastSandboxId()
 
-Enable or disable console logging at runtime.
+Returns the most recent sandbox, or `null` if there isn't one. It reads from the connected client, or from `.testdriver/last-sandbox`.
 
-```javascript
-testdriver.setLogging(enabled)
+```typescript
+testdriver.getLastSandboxId(): { sandboxId: string; os?: 'windows' | 'linux'; createdAt?: number } | null
 ```
 
-**Parameters:**
-- `enabled` (boolean) - Whether to enable logging
+## setLogging(enabled)
 
-**Example:**
-```javascript
-// Disable logging for cleanup operations
-testdriver.setLogging(false);
-await testdriver.disconnect();
-testdriver.setLogging(true);
+Turns console logging on or off while the test runs.
+
+```typescript
+testdriver.setLogging(enabled: boolean): void
 ```
 
-### getEmitter()
+## getEmitter()
 
-Get the event emitter for custom event handling.
+Returns the client's event emitter, so you can react to what TestDriver does.
 
-```javascript
-const emitter = testdriver.getEmitter()
+```typescript
+testdriver.getEmitter(): EventEmitter2
 ```
 
-**Returns:** `EventEmitter2` - Event emitter instance
-
-**Example:**
 ```javascript
 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);
-});
+emitter.on('log:warn', (message) => console.warn('TestDriver warning:', message));
+emitter.on('error:sdk', (error) => console.error('TestDriver API error:', error.message));
 ```
 
-## Complete Example
-
-```javascript
-import { beforeAll, afterAll, describe, it } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('My Test Suite', () => {
-  let testdriver;
+See [Events](/events) for every event name.
 
-  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
-  });
-});
-```
+## Related
 
-## 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
-    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
-    TD_API_KEY=your_api_key_here
-    ```
-    
-    ```javascript
-    // API key is loaded automatically - no need to pass it!
-    const testdriver = new TestDriver();
-    ```
-  </Accordion>
-</AccordionGroup>
+- [Options](/options): every option you can pass to the client
+- [Launch apps](/provision): start Chrome, extensions, and desktop apps once connected
+- [Run tests](/copilot/running-tests#reuse-a-sandbox-while-you-iterate): reuse a sandbox between runs
+- [Events](/events): listen for commands, logs, and errors