testdriver:options

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.

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.

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" 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.

The file name format is <seq>-<action>-<phase>-L<line>-<description>.png. Example: 001-click-before-L42-submit-button.png. See Debugging with screenshots.

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.

You can replace this value for one call with find(description, { verify: true }). See find.

<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>

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="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>

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="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>

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.

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	—