Testdriver Options

---
name: testdriver:options
description: Every option you can pass to the TestDriver client, with defaults and examples
---
<!-- Generated from options.mdx. DO NOT EDIT. -->

## Overview

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

```javascript
// 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()`](/client#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`](#keepalive) and the [Run guide](/copilot/running-tests#keeping-machines-alive-between-runs).
</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

```javascript
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](/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

```javascript
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](/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

```javascript
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](/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

```javascript
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](/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

```javascript
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` | — |