testdriver:options

<!-- Generated from options.mdx. DO NOT EDIT. -->

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:

1. Default values
2. Environment variables (TD_OS, TD_API_ROOT, TD_E2B_TEMPLATE_ID)
3. Global plugin options
4. 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.

<ParamField path="os" type="'linux' | 'windows'" default="linux"> The operating system of the sandbox. You can also set this with the `TD_OS` environment variable. </ParamField> <ParamField path="resolution" type="string" default="1366x768"> The screen resolution of the sandbox. Example: `'1920x1080'`. Custom resolutions are available only on Enterprise plans. </ParamField> <ParamField path="newSandbox" type="boolean" default="true"> Create a new sandbox for this run. Set to `false` to reuse a recent sandbox when one is available. </ParamField> <ParamField path="reconnect" type="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. </ParamField>

<ParamField path="sandboxId" type="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. </ParamField> <ParamField path="keepAlive" type="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. </ParamField> <ParamField path="debugOnFailure" type="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. </ParamField> <ParamField path="environment" type="object"> Additional environment variables to pass to the sandbox. </ParamField>

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.

<ParamField path="preview" type="'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. </ParamField>

<ParamField path="headless" type="boolean" default="false"> **Deprecated.** Use `preview: "none"` instead. `headless: true` maps to `preview: "none"`. </ParamField> <ParamField path="dashcam" type="boolean" default="true"> Record a Dashcam video of the test. See [Dashcam](/dashcam). </ParamField> <ParamField path="autoScreenshots" type="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. </ParamField>

<ParamField path="logging" type="boolean" default="true"> Write SDK logs to the console. You can change this at runtime with [`setLogging()`](/client#setlogging). </ParamField> <ParamField path="analytics" type="boolean" default="true"> Send usage analytics to TestDriver. </ParamField>

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.

<ParamField path="verify" type="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. </ParamField>

<ParamField path="ai" type="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. <Expandable title="properties"> <ParamField path="temperature" type="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. </ParamField>

<ParamField path="top" type="object">
  Nucleus and top-k sampling parameters.

  <Expandable title="properties">
    <ParamField path="p" type="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.
    </ParamField>

    <ParamField path="k" type="number">
      Top-K sampling. Limits token choices to the K most likely tokens. `1` always picks the most likely token. `0` disables the limit.
    </ParamField>
  </Expandable>
</ParamField>

</Expandable> </ParamField>

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.

<ParamField path="cache" type="boolean | object" default="true"> Enable or disable the cache. Pass an object to set the match thresholds. <Expandable title="advanced config"> <ParamField path="enabled" type="boolean" default="true"> Enable or disable the cache. </ParamField>

<ParamField path="thresholds" type="object">
  Fine-tune the cache matching.

  <Expandable title="properties">
    <ParamField path="find" type="object">
      Thresholds for `find()` operations.

      <Expandable title="properties">
        <ParamField path="screen" type="number" default="0.05">
          The pixel diff threshold for the screen comparison (0 to 1). `0.05` allows a 5% difference.
        </ParamField>

        <ParamField path="element" type="number" default="0.8">
          The OpenCV template match threshold for the element (0 to 1). `0.8` requires an 80% correlation.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="assert" type="number" default="0.05">
      The pixel diff threshold for `assert()` operations (0 to 1). `0.05` allows a 5% difference.
    </ParamField>
  </Expandable>
</ParamField>

</Expandable> </ParamField> <ParamField path="cacheKey" type="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. </ParamField> <ParamField path="cacheThreshold" type="object"> **Deprecated.** Use `cache.thresholds` instead. </ParamField>

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.

<ParamField path="redraw" type="boolean | object" default="true"> Enable or disable screen-change detection. Pass an object to set the thresholds. <Expandable title="advanced config"> <ParamField path="enabled" type="boolean" default="true"> Enable or disable redraw detection. </ParamField>

<ParamField path="thresholds" type="object">
  Threshold configuration.

  <Expandable title="properties">
    <ParamField path="screen" type="number | false" default="0.05">
      The pixel diff threshold (0 to 1). Set to `false` to disable screen redraw detection.
    </ParamField>

    <ParamField path="network" type="boolean" default="false">
      Wait for network activity to stop.
    </ParamField>
  </Expandable>
</ParamField>

</Expandable> </ParamField> <ParamField path="redrawThreshold" type="number | object"> **Deprecated.** Use `redraw` instead. </ParamField>

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.

<ParamField path="apiRoot" type="string"> The API endpoint URL. The default depends on the release channel. You can also set this with the `TD_API_ROOT` environment variable. </ParamField> <ParamField path="ip" type="string"> The IP address of a running sandbox. The SDK connects to this address directly. </ParamField> <ParamField path="sandboxAmi" type="string"> A custom AMI id for the sandbox instance (AWS deployments). Example: `'ami-1234'`. </ParamField> <ParamField path="sandboxInstance" type="string"> The EC2 instance type for the sandbox (AWS deployments). Example: `'i3.metal'`. </ParamField> <ParamField path="e2bTemplateId" type="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. </ParamField>

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	—