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

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

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

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 probab