---
title: "Options"
description: "Configure TestDriver SDK for your testing environment"
icon: "gear"
---
## Overview
TestDriver can be configured through constructor options, environment variables, and Vitest configuration.
## Environment Variables
Set these in your `.env` file:
```bash
# Required
TD_API_KEY=your_api_key_here
# Optional
TD_API_ROOT=https://api.testdriver.ai
TD_DEFAULT_OS=linux
TD_DEFAULT_RESOLUTION=1920x1080
TD_NO_PROMPT_CACHE=false
TD_NO_SELECTOR_CACHE=false
```
## Client Configuration
### Basic Options
```javascript
import TestDriver from 'testdriverai';
const client = await TestDriver.create({
apiKey: process.env.TD_API_KEY,
os: 'linux', // 'linux' | 'windows' | 'mac'
resolution: '1920x1080', // Any standard resolution
verbosity: 1, // 0 (silent) | 1 (normal) | 2 (debug)
});
```
### All Options
```javascript
const client = await TestDriver.create({
// Authentication
apiKey: process.env.TD_API_KEY,
// Sandbox Configuration
os: 'linux',
resolution: '1920x1080',
sandboxId: null,
// API Configuration
apiRoot: 'https://api.testdriver.ai',
// Logging
verbosity: 1,
logging: true,
// Analytics
analytics: true,
// Cache Configuration
cacheDefaults: {
threshold: 0.05, // 95% similarity
enabled: true
}
});
```
## Vitest Configuration
Create or update `vitest.config.mjs`:
```javascript
import { defineConfig } from 'vitest/config';
import testDriverPlugin from 'testdriverai/interfaces/vitest-plugin.mjs';
import { config } from 'dotenv';
config(); // Load .env file
export default defineConfig({
plugins: [
testDriverPlugin({
apiKey: process.env.TD_API_KEY,
apiRoot: process.env.TD_API_ROOT,
}),
],
test: {
// Test file patterns
include: ['**/*.test.{js,mjs,ts}'],
// Timeout settings
testTimeout: 300000, // 5 minutes per test
hookTimeout: 300000, // 5 minutes for setup/teardown
teardownTimeout: 120000, // 2 minutes for teardown
// Parallel execution
pool: 'forks',
poolOptions: {
forks: {
singleFork: false,
maxForks: 5,
minForks: 1,
},
},
// Enable parallel execution
sequence: {
concurrent: true,
shuffle: false,
},
fileParallelism: true,
maxConcurrency: 5,
// Reporters
reporters: ['verbose'],
},
});
```
## Preset Configuration
### Chrome Preset
```javascript
import { chrome } from 'testdriverai/presets';
const { testdriver, dashcam } = await chrome(context, {
url: 'https://example.com',
dashcam: true,
os: 'linux',
resolution: '1920x1080',
// Chrome-specific options
incognito: false,
});
```
### VS Code Preset
```javascript
import { vscode } from 'testdriverai/presets';
const { testdriver, dashcam } = await vscode(context, {
workspace: '/path/to/workspace',
extensions: ['ms-python.python'],
settings: {
'editor.fontSize': 14
},
dashcam: true,
});
```
### Electron Preset
```javascript
import { electron } from 'testdriverai/presets';
const { testdriver, dashcam } = await electron(context, {
appPath: './dist/my-app',
args: ['--enable-logging'],
dashcam: true,
});
```
## Operating System Settings
### Linux
```javascript
{
os: 'linux',
resolution: '1920x1080',
// Linux-specific environment
environment: {
DISPLAY: ':0',
HOME: '/home/user'
}
}
```
### Windows
```javascript
{
os: 'windows',
resolution: '1366x768',
// Windows-specific paths use backslashes
}
```
### macOS
```javascript
{
os: 'mac',
resolution: '1920x1080',
// macOS-specific settings
}
```
## Cache Configuration
### Prompt Cache
Configure AI prompt caching:
```javascript
// Disable prompt cache globally
process.env.TD_NO_PROMPT_CACHE = 'true';
// Per call
await testdriver.ai('click button', false); // bypass cache
```
### Selector Cache
Configure element location caching:
```javascript
// Disable selector cache globally
process.env.TD_NO_SELECTOR_CACHE = 'true';
// Per call with custom threshold
await testdriver.find('button', { threshold: 0.01 }); // 99% similarity
await testdriver.find('button', { threshold: 0.10 }); // 90% similarity
await testdriver.find('button', { threshold: -1 }); // disable cache
```
## Dashcam Configuration
```javascript
import Dashcam from 'testdriverai/lib/core/Dashcam.js';
const dashcam = new Dashcam(client, {
apiKey: process.env.TD_API_KEY,
autoStart: false,
logs: [
{
name: 'Application Log',
type: 'file',
path: '/tmp/app.log'
}
]
});
```
## Timeout Configuration
### Test Timeouts
```javascript
// In vitest.config.mjs
export default defineConfig({
test: {
testTimeout: 600000, // 10 minutes
hookTimeout: 600000, // 10 minutes
}
});
```
### Command Timeouts
```javascript
// exec() timeout
await client.exec('sh', 'long-running-command', 120000); // 2 minutes
// Find timeout (polling)
for (let i = 0; i < 60; i++) {
const element = await client.find('button');
if (element.found()) break;
await new Promise(r => setTimeout(r, 1000));
}
```
## Best Practices
```javascript
// ✅ Good
apiKey: process.env.TD_API_KEY
// ❌ Bad
apiKey: 'td_1234567890abcdef'
```
```javascript
// For slow operations
testTimeout: 600000, // 10 minutes
// For fast operations
testTimeout: 60000, // 1 minute
```
```javascript
// Strict caching for stable UIs
threshold: 0.01 // 99% similarity
// Lenient caching for dynamic UIs
threshold: 0.10 // 90% similarity
```
```javascript
// High-end machine
maxConcurrency: 10
// Low-end machine or resource-intensive tests
maxConcurrency: 2
```
## Example Configurations
### CI/CD Configuration
```javascript
export default defineConfig({
test: {
testTimeout: 300000,
maxConcurrency: 3, // Lower for CI
reporters: ['junit', 'json'],
},
});
```
### Local Development
```javascript
export default defineConfig({
test: {
testTimeout: 600000,
maxConcurrency: 5,
reporters: ['verbose'],
},
});
```
### Debug Mode
```javascript
const client = await TestDriver.create({
apiKey: process.env.TD_API_KEY,
verbosity: 2, // Debug logging
logging: true,
});
```
## See Also
Install TestDriver SDK
Build your first test
Configure caching
Full client reference