Options

Every option you can pass to a TestDriver client, with its default.

Options control the sandbox, the live preview, the AI, the cache, and redraw detection. A quick reference table at the end lists every option and its default.

Where to set options

Pass options in any of three places:

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

// 2. The client constructor
const testdriver = new TestDriver({ os: 'windows' });

vitest.config.mjs

// 3. The Vitest plugin, for every test in the project
import { defineConfig } from 'vitest/config';
import TestDriver from 'testdriverai/vitest';

export default defineConfig({
  test: {
    reporters: ['default', TestDriver({ os: 'windows' })],
    setupFiles: ['testdriverai/vitest/setup'],
  },
});

When the same option is set in more than one place, the most specific wins:

1. Options you pass to the hook or the constructor
2. Plugin options in vitest.config
3. Environment variables: TD_OS, TD_API_ROOT, and TD_E2B_TEMPLATE_ID
4. Defaults

Options you pass to connect() override the client’s values for that connection only.

Sandbox

These options control the virtual machine that runs your test.

os · 'linux' | 'windows' · default: "linux"

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

Enterprise 'windows' is available on Enterprise plans.

resolution · string · default: "1366x768"

The screen resolution of the sandbox, such as '1920x1080'.

Enterprise Custom resolutions are available on Enterprise plans.

newSandbox · boolean · default: "true"

Create a new sandbox for this run. Set to false to reuse a recent sandbox when one is available. Defaults to false when you set sandboxId or reconnect.

reconnect · boolean · default: "false"

Reattach to the last sandbox this project used. The SDK records it in .testdriver/last-sandbox on every successful connect.

While reconnect is true, provision methods such as chrome() and installer() are skipped, because the app is already running. The sandbox must still be alive. See keepAlive and Reuse a sandbox while you iterate.

sandboxId · string

Attach to a specific sandbox by its id, for example to pin a chain of tests to one machine. This sets newSandbox to false.

Unlike reconnect, sandboxId alone doesn’t skip provision calls. Set reconnect: true as well if the app is already running.

keepAlive · number · default: "60000"

The number of milliseconds to keep the sandbox running after disconnect(), so you can reconnect to the same sandbox for debugging. Values above 30 minutes are capped at 30 minutes, and 0 uses the default.

debugOnFailure · boolean · default: "false"

Keep the sandbox running when a test fails, and print its id so you can reconnect with sandboxId and debug. Available only in the Vitest hook.

environment · object

Extra TD_* settings for the SDK itself, as key-value pairs. These configure TestDriver on your machine, not environment variables inside the sandbox. To set variables in the sandbox, run a command with exec().

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.

preview · '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 an editor panel. This needs the TestDriver extension for VS Code or Cursor.
• "none" runs without a visual preview. Use this in CI.

headless · boolean · default: "false"

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

dashcam · boolean · default: "true"

Record a Dashcam video of the test. See Dashcam.

autoScreenshots · boolean · default: "false"

Save a screenshot before and after each testdriver method call and each find(), and when one fails, to .testdriver/screenshots/<test file>/. Actions on an element, like element.click(), aren’t captured. Files are named like 001-find-before-L42-submit-button.png. See Screenshots.

logging · boolean · default: "true"

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

analytics · 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.

verify · boolean · default: "false"

Double-check every find() result with a second AI call. Off by default, because it makes each call slower.

When on, after the AI locates an element:

1. A second AI looks at that spot and confirms it’s the element you described.
2. If it isn’t, TestDriver locates the element again with a hint about what was wrong, then checks once more.
3. If that check also fails, find() returns an element whose found() is false.

Results that fail the check are never cached. Results served from the cache aren’t re-checked.

Override it for one call with find(description, { verify: true }). See find().

ai · object

Global AI sampling configuration. These values apply to find() verification and to assert(). You can override them for one assert() call with its ai option. find() ignores a per-call ai option, so set it here.

Show properties

temperature · 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.

top · object

Nucleus and top-k sampling parameters.

Show properties

p · 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.

k · 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, which reuses element positions from a passing run when the screen hasn’t changed. See Caching.

cache · boolean | object · default: "true"

Pass false to turn the cache off, or an object to set the match thresholds.

cache: { enabled: false } does not turn the cache off. Use cache: false or TD_NO_CACHE=true.

Show advanced config

thresholds · object

Fine-tune the cache matching.

Show properties

find · object

Thresholds for find() operations.

Show properties

screen · number · default: "0.05"

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

element · number · default: "0.8"

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

assert · number · default: "0.05"

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

cacheKey · string

The key the cache is stored under. By default, the SDK uses a hash of the test file, so editing the file starts a fresh cache. Set your own key to keep the cache across edits, or to share it between files.

cacheThreshold · object

Deprecated. Use cache.thresholds instead.

Example

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

Redraw detection

These options make the SDK wait for the screen to settle after each action. Redraw detection is off by default. See Redraw.

redraw · boolean | object · default: "false"

Turn on screen-change detection with true, or pass an object to set the thresholds.

Show advanced config

enabled · boolean · default: "true"

Whether redraw detection is on when you pass an object.

thresholds · object

Threshold configuration.

Show properties

screen · number | false · default: "0.05"

Set to false to turn off screen-change detection and wait only for the network. Any number keeps it on; the number itself isn’t used, because the change threshold is fixed.

network · boolean · default: "false"

Wait for network activity to stop.

redrawThreshold · number | object

Deprecated. Use redraw instead.

Example

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

Self-hosted and infrastructure

Most projects don’t need these. They’re for self-hosted or custom deployments.

apiRoot · string

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

ip · string

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

Enterprise Connecting to your own machines is available on Enterprise plans.

sandboxAmi · string

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

sandboxInstance · string

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

e2bTemplateId · 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	false
apiRoot	string	channel default
ip	string	—
sandboxAmi	string	—
sandboxInstance	string	—
e2bTemplateId	string	—