Testdriver:Options

Overview

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

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

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

javascriptCopy code
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.

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

javascriptCopy code
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.

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

javascriptCopy code
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.

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

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