Options Reference

Overview

You configure the SDK with an options object. You can pass the object in three places:

// 1. Vitest hook (most common)
const testdriver = TestDriver(context, { os: "windows" });

// 2. Constructor
const testdriver = new TestDriver(apiKey, { os: "windows" });

// 3. Global plugin options in vitest.config.mjs
testdriver({ os: "windows" })

The hook merges the options in this order. A later source replaces an earlier source:

Default values
Environment variables (TD_OS, TD_API_ROOT, TD_E2B_TEMPLATE_ID)
Global plugin options
Options that you pass to the hook or the constructor

Options that you pass to connect() replace the constructor values for that connection only.

Sandbox

These options control the virtual machine that runs your test.

'linux' | 'windows'

default:"linux"

The operating system of the sandbox. You can also set this with the TD_OS environment variable.

string

default:"1366x768"

The screen resolution of the sandbox. Example: '1920x1080'. Custom resolutions are available only on Enterprise plans.

boolean

default:"true"

Create a new sandbox for this run. Set to false to reuse a recent sandbox when one is available.

boolean

default:"false"

Reattach to the last used sandbox. The SDK reads the sandbox id from .testdriver/last-sandbox. The SDK writes this file on every successful connect.When reconnect is true, the SDK skips provision methods (chrome, vscode, installer, and others). The application is already running. The previous sandbox must still be alive. See keepAlive and the Run guide.

string

Reattach to a specific sandbox id. Use this for CI matrices or to pin a chain of tests to a known VM. This option implies reconnect: true. The SDK skips provision calls.

number

default:"60000"

The number of milliseconds to keep the sandbox alive after disconnect(). Set to 0 to end the sandbox at once. A longer value lets you reconnect to the same sandbox for debugging.

boolean

default:"false"

Keep the sandbox alive when a test fails. The SDK prints the sandbox id to the console. You can then reconnect with sandboxId and debug the failure. This option is available only in the Vitest hook.

object

Additional environment variables to pass to the sandbox.

Example

const testdriver = TestDriver(context, {
  os: "windows",
  resolution: "1920x1080",
  keepAlive: 300000,
  debugOnFailure: true,
});

Preview and recording

These options control what you see while the test runs.

'browser' | 'ide' | 'none'

default:"browser"

The preview mode for live test visualization.

"browser" opens the debugger in your default browser.
"ide" opens the preview in the IDE panel. This mode needs the TestDriver extension for VS Code or Cursor.
"none" runs without a visual preview. Use this in CI.

boolean

default:"false"

Deprecated. Use preview: "none" instead. headless: true maps to preview: "none".

boolean

default:"true"

Record a Dashcam video of the test. See Dashcam.

boolean

default:"false"

Capture a screenshot before and after each command. The SDK saves the screenshots to .testdriver/screenshots/<test>/.The file name format is <seq>-<action>-<phase>-L<line>-<description>.png. Example: 001-click-before-L42-submit-button.png. See Debugging with screenshots.

boolean

default:"true"

Write SDK logs to the console. You can change this at runtime with setLogging().

boolean

default:"true"

Send usage analytics to TestDriver.

Example

const testdriver = TestDriver(context, {
  preview: process.env.CI ? "none" : "browser",
  autoScreenshots: true,
});

AI and element location

These options control how the AI locates elements and checks assertions.

boolean

default:"false"

Run a second AI check on every find() result. The check confirms that the coordinates match the requested element. This catches incorrect positions. It adds latency to each call.You can replace this value for one call with find(description, { verify: true }). See find.

object

Global AI sampling configuration. These values apply to find() verification and to assert(). You can replace them for one call with the ai option on that call.

Show properties

number

Controls randomness in AI responses. 0 is deterministic and is best for verification. Higher values give more varied responses. The default is 0 for find verification and the model default for assert.

object

Nucleus and top-k sampling parameters.

Show properties

number

Top-P (nucleus sampling). Limits token choices to the smallest set whose total probability is more than P. Lower values give more focused responses. Range: 0 to 1.

number

Top-K sampling. Limits token choices to the K most likely tokens. 1 always picks the most likely token. 0 disables the limit.

Example

const testdriver = TestDriver(context, {
  verify: true,
  ai: { temperature: 0, top: { p: 0.9, k: 40 } },
});

Caching

These options control the element cache. The cache stores the position of an element after the first find(). Later runs reuse the position when the screen has not changed. See Caching.

boolean | object

default:"true"

Enable or disable the cache. Pass an object to set the match thresholds.

Show advanced config

boolean

default:"true"

Enable or disable the cache.

object

Fine-tune the cache matching.

Show properties

object

Thresholds for find() operations.

Show properties

number

default:"0.05"

The pixel diff threshold for the screen comparison (0 to 1). 0.05 allows a 5% difference.

number

default:"0.8"

The OpenCV template match threshold for the element (0 to 1). 0.8 requires an 80% correlation.

number

default:"0.05"

The pixel diff threshold for assert() operations (0 to 1). 0.05 allows a 5% difference.

string

The cache key for element location. When you set a key, the SDK ties the cache to that key. Use a different key for each test to keep the caches separate.

object

Deprecated. Use cache.thresholds instead.

Example

const testdriver = TestDriver(context, {
  cache: {
    enabled: true,
    thresholds: {
      find: { screen: 0.05, element: 0.8 },
      assert: 0.05,
    },
  },
  cacheKey: "login-test",
});

Redraw detection

These options control how the SDK waits for the screen to settle after an action. See Redraw.

boolean | object

default:"true"

Enable or disable screen-change detection. Pass an object to set the thresholds.

Show advanced config

boolean

default:"true"

Enable or disable redraw detection.

object

Threshold configuration.

Show properties

number | false

default:"0.05"

The pixel diff threshold (0 to 1). Set to false to disable screen redraw detection.

boolean

default:"false"

Wait for network activity to stop.

number | object

Deprecated. Use redraw instead.

Example

const testdriver = TestDriver(context, {
  redraw: {
    thresholds: { screen: 0.1, network: true },
  },
});

Self-hosted and infrastructure

Most users do not need these options. Use them for self-hosted or custom deployments.

string

The API endpoint URL. The default depends on the release channel. You can also set this with the TD_API_ROOT environment variable.

string

The IP address of a running sandbox. The SDK connects to this address directly.

string

A custom AMI id for the sandbox instance (AWS deployments). Example: 'ami-1234'.

string

The EC2 instance type for the sandbox (AWS deployments). Example: 'i3.metal'.

string

The E2B template id to use when the SDK creates the sandbox. You can also set this with the TD_E2B_TEMPLATE_ID environment variable.

Quick reference

Option	Type	Default
`os`	`'linux' \| 'windows'`	`'linux'`
`resolution`	`string`	`'1366x768'`
`newSandbox`	`boolean`	`true`
`reconnect`	`boolean`	`false`
`sandboxId`	`string`	—
`keepAlive`	`number`	`60000`
`debugOnFailure`	`boolean`	`false`
`environment`	`object`	—
`preview`	`'browser' \| 'ide' \| 'none'`	`'browser'`
`dashcam`	`boolean`	`true`
`autoScreenshots`	`boolean`	`false`
`logging`	`boolean`	`true`
`analytics`	`boolean`	`true`
`verify`	`boolean`	`false`
`ai`	`object`	—
`cache`	`boolean \| object`	`true`
`cacheKey`	`string`	—
`redraw`	`boolean \| object`	`true`
`apiRoot`	`string`	channel default
`ip`	`string`	—
`sandboxAmi`	`string`	—
`sandboxInstance`	`string`	—
`e2bTemplateId`	`string`	—

Overview

Using TestDriver

Building & Maintaining Tests

Advanced Topics

Overview

Sandbox

Example

Preview and recording

Example

AI and element location

Example

Caching

Example

Redraw detection

Example

Self-hosted and infrastructure

Quick reference

​Overview

​Sandbox

​Example

​Preview and recording

​Example

​AI and element location

​Example

​Caching

​Example

​Redraw detection

​Example

​Self-hosted and infrastructure

​Quick reference

Overview

Sandbox

Example

Preview and recording

Example

AI and element location

Example

Caching

Example

Redraw detection

Example

Self-hosted and infrastructure

Quick reference