@testdriverai/agent 7.11.150-test → 7.11.151-canary

package/ai/skills/testdriver-options/SKILL.md

@@ -0,0 +1,319 @@
+---
+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` | — |

package/ai/skills/testdriver-parse/SKILL.md

@@ -6,17 +6,17 @@ description: Detect all UI elements on screen using OmniParser
 
 ## Overview
 
-Parse the current screen using OmniParser v2 to detect all visible UI elements. Returns structured data including element types, text content, interactivity levels, and bounding box coordinates.
+Parse the screen with OmniParser v2 to find all visible UI elements. TestDriver returns structured data. This includes element types, text content, interactivity levels, and bounding box coordinates.
 
-This method analyzes the entire screen and returns every detected element. It's useful for:
-- Understanding the full UI layout of a screen
-- Finding all clickable or interactive elements
-- Building custom element-based logic
-- Debugging what elements TestDriver can detect
-- Accessibility auditing
+This method examines all of the screen and returns each element that it finds. Use it for these:
+- To understand the full UI layout of a screen
+- To find all clickable or interactive elements
+- To build custom element logic
+- To debug which elements TestDriver can find
+- To do an accessibility audit
 
 <Note>
-  **Availability**: `parse()` requires an enterprise or self-hosted plan. It uses OmniParser v2 server-side for element detection.
+  **Availability**: `parse()` needs an enterprise plan or a self-hosted plan. It uses OmniParser v2 on the server for element detection.
 </Note>
 
 ## Syntax

package/ai/skills/testdriver-performing-actions/SKILL.md

@@ -4,13 +4,13 @@ description: Perform actions and handle dynamic, async UI so tests adapt to chan
 ---
 <!-- Generated from performing-actions.mdx. DO NOT EDIT. -->
 
-Real apps move, load, and change. Adapt your tests to handle it.
+Real apps move, load, and change. Adapt your tests to these conditions.
 
-Once you've [generated](/generating-tests) and [learned](/caching) your tests and gotten them [running](/copilot/running-tests), the next challenge is the real world: buttons appear after a spinner, pages navigate, animations play, and content streams in over the network. To keep tests reliable, you need to perform the right actions and handle timing so your tests adapt to how the UI actually behaves instead of breaking.
+You [generated](/generating-tests) and [learned](/caching) your tests. Then you got them to [run](/copilot/running-tests). Now the challenge is the real world: buttons show after a spinner, pages navigate, animations play, and content comes in over the network. To keep the tests reliable, do the correct actions and control the timing. Then your tests adapt to the true behavior of the UI. They do not break.
 
 ## Performing Actions
 
-TestDriver provides a variety of actions you can perform, like [clicking](/click), [typing](/type), [hovering](/hover), and [scrolling](/scroll). For a full list, see the [API Reference](/click).
+TestDriver gives you many actions. You can [click](/click), [type](/type), [hover](/hover), and [scroll](/scroll). For a full list, read the [API Reference](/click).
 
 ```javascript
 // Clicking
@@ -42,14 +42,14 @@ const orderNumber = await testdriver.extract('the order confirmation number');
 
 ### Chaining Actions
 
-TestDriver supports method chaining for cleaner code:
+TestDriver lets you chain methods for cleaner code:
 
 ```javascript
 // Chain find() with actions
 const button = await testdriver.find('submit button').click();
 ```
 
-Or save element reference for later use:
+Or keep the element reference for later use:
 
 ```javascript
 const button = await testdriver.find('submit button');
@@ -58,9 +58,9 @@ await button.click();
 
 ## Waiting for Dynamic Content
 
-By default, `find()` automatically polls for up to 10 seconds, retrying every 5 seconds until the element is found. This means most elements that appear after short async operations will be found without any extra configuration.
+By default, `find()` polls automatically for a maximum of 10 seconds. It tries again each 5 seconds until it finds the element. Thus TestDriver finds most elements that show after short async operations. You do not need more configuration.
 
-For longer operations, increase the `timeout`:
+For longer operations, make the `timeout` larger:
 
 ```javascript
 // Default behavior - polls for up to 10 seconds automatically

package/ai/skills/testdriver-provision/SKILL.md

@@ -6,9 +6,9 @@ description: Launch browsers, desktop apps, and extensions in your sandbox
 
 ## Overview
 
-The Provision API sets up applications in your sandbox before tests run. It handles downloading, installing, and launching browsers, desktop apps, VS Code, Chrome extensions, and more.
+The Provision API sets up applications in your sandbox before the tests run. It downloads, installs, and starts browsers, desktop apps, VS Code, Chrome extensions, and more.
 
-Access provision methods via `testdriver.provision.*`:
+Use the provision methods through `testdriver.provision.*`:
 
 ```javascript
 await testdriver.provision.chrome({ url: 'https://example.com' });
@@ -18,7 +18,7 @@ await testdriver.provision.chrome({ url: 'https://example.com' });
 
 ### chrome()
 
-Launch Google Chrome with an optional URL.
+Start Google Chrome with an optional URL.
 
 ```javascript
 await testdriver.provision.chrome(options?)
@@ -27,15 +27,15 @@ await testdriver.provision.chrome(options?)
 <ParamField path="options" type="ProvisionChromeOptions">
   <Expandable title="properties">
     <ParamField path="url" type="string" default="http://testdriver-sandbox.vercel.app/">
-      URL to navigate to after launch.
+      The URL to go to after Chrome starts.
     </ParamField>
     
     <ParamField path="maximized" type="boolean" default={true}>
-      Launch Chrome in maximized window mode.
+      Start Chrome with the window at the maximum size.
     </ParamField>
     
     <ParamField path="guest" type="boolean" default={false}>
-      Launch Chrome in guest profile mode.
+      Start Chrome in the guest profile mode.
     </ParamField>
   </Expandable>
 </ParamField>
@@ -54,7 +54,7 @@ await testdriver.provision.chrome({
 
 ### chromeExtension()
 
-Install and launch a Chrome extension. You can install from a local unpacked directory or from the Chrome Web Store by extension ID.
+Install and start a Chrome extension. You can install it from a local unpacked directory. Or you can install it from the Chrome Web Store by the extension ID.
 
 ```javascript
 await testdriver.provision.chromeExtension(options)