@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/customizing-devices.mdx

@@ -1,321 +1,144 @@
 ---
-title: "Customizing Devices"
-description: "Configure TestDriver sandbox options and environment settings"
+title: "Customize the sandbox"
+sidebarTitle: "Customizing devices"
+description: "Choose the sandbox OS and resolution, preview mode, recording, and how long it stays alive."
 icon: "computer"
 ---
 
-## TestDriver Options
+import { EnterpriseBadge, EnterpriseCta } from '/snippets/enterprise.mdx';
 
-Configure the TestDriver behavior with options that you give to the `TestDriver()` function:
+Every test runs in a sandbox: a fresh virtual machine. Pass options to `TestDriver(context, options)` to change it.
 
 ```javascript
 const testdriver = TestDriver(context, {
-  // === Sandbox & Connection ===
-  newSandbox: true,          // Force creation of a new sandbox (default: true)
-  reconnect: false,          // Reconnect to last sandbox (default: false)
-  keepAlive: 60000,          // Keep sandbox alive after disconnect in ms (default: 60000)
-  os: "linux",               // 'linux' | 'windows' (default: 'linux')
-  resolution: "1366x768",    // Sandbox resolution (e.g., '1920x1080')
-  ip: "203.0.113.42",        // Direct IP for self-hosted sandbox
-  sandboxAmi: "ami-1234",    // Custom AMI ID (AWS deployments)
-  sandboxInstance: "i3.metal", // EC2 instance type (AWS deployments)
-
-  // === Preview & Debugging ===
-  preview: "browser",        // "browser" | "ide" | "none" (default: "browser")
-  headless: false,           // @deprecated - use preview: "none" instead
-  debugOnFailure: false,     // Keep sandbox alive on test failure for debugging
-
-  // === Caching ===
-  cache: true,               // Enable element caching (default: true)
-  // Or use advanced caching config:
-  // cache: {
-  //   enabled: true,
-  //   thresholds: {
-  //     find: { screen: 0.05, element: 0.8 },
-  //     assert: 0.05
-  //   }
-  // },
-  cacheKey: "my-test",       // Cache key for element finding operations
-
-  // === Recording & Screenshots ===
-  dashcam: true,             // Enable/disable Dashcam video recording (default: true)
-  autoScreenshots: true,     // Capture screenshots before/after each command (default: false)
-
-  // === AI Configuration ===
-  ai: {                      // Global AI sampling configuration
-    temperature: 0,          // 0 = deterministic, higher = more creative
-    top: {
-      p: 0.9,               // Top-P nucleus sampling (0-1)
-      k: 40,                // Top-K sampling (1 = most likely, 0 = disabled)
-    },
-  },
-
-  // === Screen Change Detection ===
-  redraw: true,              // Enable redraw detection (default: true)
-  // Or use advanced redraw config:
-  // redraw: {
-  //   enabled: true,
-  //   thresholds: {
-  //     screen: 0.05,       // Pixel diff threshold (0-1), false to disable
-  //     network: false,     // Monitor network activity (default: false)
-  //   }
-  // },
-
-  // === Logging & Analytics ===
-  logging: true,             // Enable console logging output (default: true)
-  analytics: true,           // Enable analytics tracking (default: true)
-
-  // === Advanced ===
-  apiRoot: "https://...",    // API endpoint URL (for self-hosted deployments)
-  environment: {},           // Additional environment variables for the sandbox
+  os: 'windows',
+  preview: 'none',
+  keepAlive: 300000,
 });
 ```
 
-### Preview Mode
+This page covers the common changes. For every option and its default, see [Options](/options).
 
-Control how test execution is visualized. The `preview` option determines where the live debugger view opens:
+## Choose the operating system
 
-```javascript
-const testdriver = TestDriver(context, {
-  preview: "browser",  // Opens in default browser (default)
-});
-```
-
-| Value | Description |
-|-------|-------------|
-| `"browser"` | Opens debugger in default browser (default) |
-| `"ide"` | Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension) |
-| `"none"` | Headless mode, no visual preview |
-
-**IDE Preview**
-
-For the best development experience, use `preview: "ide"` with the TestDriver extension for VSCode or Cursor:
+Sandboxes run Linux by default. Set `os` to run on Windows:
 
 ```javascript
-const testdriver = TestDriver(context, {
-  preview: "ide",  // Opens preview in IDE panel
-});
+const testdriver = TestDriver(context, { os: 'windows' });
 ```
 
-**Headless Mode**
-
-Run tests without any visual preview. Useful for CI/CD pipelines:
-
-```javascript
-const testdriver = TestDriver(context, {
-  preview: "none",  // No visual preview (headless)
-});
-```
-
-<Note>
-  The legacy `headless: true` option still works for backward compatibility and maps to `preview: "none"`.
-</Note>
-
-### Debug on Failure
-
-Keep the sandbox alive when a test fails so you can reconnect and debug interactively. The sandbox ID is printed to the console along with instructions for reconnecting via MCP.
-
-```javascript
-const testdriver = TestDriver(context, {
-  debugOnFailure: true,
-});
-```
+<EnterpriseCta feature="Windows sandboxes" plural />
 
-### IP Target
-
-If self-hosting TestDriver, use `ip` to specify the device IP. See [Run on Your Own Machine](/bring-your-own-machine) for details.
-
-```javascript
-const testdriver = TestDriver(context, {
-  ip: "203.0.113.42",  // Your allowlisted IP
-});
-```
-
-### Operating System
-
-Set the `os` property to run tests on a specific operating system. Available options are `linux` (default) and `windows`.
-
-```javascript
-const testdriver = TestDriver(context, {
-  os: "windows",  // Run on Windows sandbox
-});
-```
-
-#### Using Environment Variables
-
-You can make the operating system configurable via environment variables. This requires adding code to read from `process.env` in your test:
-
-```javascript
-const testdriver = TestDriver(context, {
-  os: process.env.TD_OS || "linux",  // Read from env, default to Linux
-});
-```
-
-Then pass the variable when running tests:
+The `TestDriver()` hook also reads the `TD_OS` environment variable when you don't pass `os`. That lets you run one suite on both systems without changing code:
 
 ```bash
-# Run tests on Windows
-TD_OS=windows vitest run
-
-# Run tests on Linux (default)
-TD_OS=linux vitest run
+TD_OS=windows npx vitest run
 ```
 
-This pattern is useful for running the same test suite across multiple operating systems in CI/CD:
+In GitHub Actions, run the suite once per OS with a matrix:
 
-```yaml
-# Example GitHub Actions matrix
+```yaml .github/workflows/testdriver.yml
 strategy:
   matrix:
-    os: [linux, windows]
+    td-os: [linux, windows]
 steps:
-  - run: TD_OS=${{ matrix.os }} vitest run
+  # ...checkout, install, and authenticate steps
+  - name: Run tests on ${{ matrix.td-os }}
+    run: npx vitest run
+    env:
+      TD_OS: ${{ matrix.td-os }}
 ```
 
-### Dashcam Recording
+See [Run in CI/CD](/ci-cd) for the full workflow.
 
-Dashcam video recording is enabled by default. Disable it to skip recording:
+## Set the screen resolution
 
-```javascript
-const testdriver = TestDriver(context, {
-  dashcam: false,
-});
-```
-
-### Automatic Screenshots
-
-Screenshots are automatically captured before and after every command (click, type, find, assert, etc.) by default. Each screenshot filename includes the line number from your test file.
-
-Disable automatic screenshots:
+The default resolution is `1366x768`. Set `resolution` to change it:
 
 ```javascript
-const testdriver = TestDriver(context, {
-  autoScreenshots: false,
-});
+const testdriver = TestDriver(context, { resolution: '1920x1080' });
 ```
 
-### Caching
+<EnterpriseCta feature="Custom screen resolution" />
 
-Element caching speeds up repeated `find()` and `assert()` calls. Enabled by default.
+## Choose how to watch the run
 
-```javascript
-// Disable caching
-const testdriver = TestDriver(context, {
-  cache: false,
-});
-
-// Advanced: custom thresholds
-const testdriver = TestDriver(context, {
-  cache: {
-    enabled: true,
-    thresholds: {
-      find: { screen: 0.05, element: 0.8 },
-      assert: 0.05,
-    },
-  },
-  cacheKey: "my-test",
-});
-```
-
-### Redraw Detection
+`preview` sets where the live view of the sandbox opens:
 
-Redraw detection waits for the screen to stabilize before taking actions. Enabled by default.
+- `"browser"` opens it in your default browser. This is the default.
+- `"ide"` opens it in an editor panel. This needs the [TestDriver extension](/quickstart-vscode) for VS Code or Cursor.
+- `"none"` turns the live view off. Use this in CI.
 
 ```javascript
-// Disable redraw detection
 const testdriver = TestDriver(context, {
-  redraw: false,
-});
-
-// Advanced: custom thresholds with network monitoring
-const testdriver = TestDriver(context, {
-  redraw: {
-    enabled: true,
-    thresholds: {
-      screen: 0.05,
-      network: true,
-    },
-  },
+  preview: process.env.CI ? 'none' : 'browser',
 });
 ```
 
-### AI Configuration
+`headless: true` is deprecated. Use `preview: "none"` instead.
 
-Control how the AI model generates responses for `find()` verification and `assert()` calls:
+## Record the run
 
-```javascript
-const testdriver = TestDriver(context, {
-  ai: {
-    temperature: 0,       // 0 = deterministic
-    top: { p: 0.9, k: 40 },
-  },
-});
-```
-
-### Environment Variables
-
-Pass additional environment variables to the sandbox:
+- **Video.** [Dashcam](/dashcam) records every test by default. Set `dashcam: false` to turn it off.
+- **Screenshots.** Set `autoScreenshots: true` to save a screenshot before and after each command. They're off by default. See [Debug a failing test](/debugging-with-screenshots).
 
 ```javascript
 const testdriver = TestDriver(context, {
-  environment: {
-    MY_VAR: "value",
-    DEBUG: "true",
-  },
+  dashcam: false,
+  autoScreenshots: true,
 });
 ```
 
-## Keepalive
+## Keep a sandbox alive
 
-By default, sandboxes stay alive for 60 seconds after disconnect. Customize this with `keepAlive`:
+After a test ends, its sandbox keeps running for `keepAlive` milliseconds, so you can reconnect to it:
 
-```javascript
-const testdriver = TestDriver(context, {
-  keepAlive: 300000,  // Keep sandbox alive for 5 minutes after test
-});
-```
-
-Set to `0` to terminate immediately:
+- The default is `60000` (60 seconds).
+- Values above 30 minutes are capped at 30 minutes.
+- `0` uses the default. There's no value that ends the sandbox immediately.
+- A sandbox never runs longer than 2 hours in total.
 
 ```javascript
 const testdriver = TestDriver(context, {
-  keepAlive: 0,  // Terminate sandbox immediately on disconnect
+  keepAlive: 10 * 60 * 1000, // 10 minutes
 });
 ```
 
-### Connecting to an Existing Sandbox
-
-Speed up test development by connecting to an existing sandbox instead of starting fresh each time. This lets you iterate quickly on failing steps without re-running the entire test from the beginning.
+To reconnect from another test file, set `reconnect: true`. TestDriver reattaches to the last sandbox it used and skips `provision` calls, because the app is already open. See [Reuse a sandbox while you iterate](/copilot/running-tests#reuse-a-sandbox-while-you-iterate).
 
-Split your test into two files: one for known-good steps that set up the desired state, and another for work-in-progress steps you want to debug.
+To attach to a specific sandbox, pass its id as `sandboxId`. Unlike `reconnect`, `sandboxId` alone still runs `provision` calls.
 
-```javascript known-good.test.mjs
-const testdriver = TestDriver(context, {
-  keepAlive: 60000,  // Keep sandbox alive for 60 seconds after test
-});
-```
+### Keep the sandbox when a test fails
 
-```javascript work-in-progress.test.mjs
-// Second test file: experiment.test.mjs (run within keepAlive window)
-const testdriver = TestDriver(context, {
-  keepAlive: 60000,
-});
+Set `debugOnFailure: true` to keep the sandbox running when a test fails. TestDriver prints the sandbox id so you can connect to it and look around.
 
-await testdriver.connect({ sandboxId: "sandbox-abc123" });
+```javascript
+const testdriver = TestDriver(context, { debugOnFailure: true });
 ```
 
-Then, you can run both tests in sequence:
+## Run on your own machine
 
-```bash
-vitest run -t known-good.test.mjs -t work-in-progress.test.mjs
-```
+To run tests on a machine you manage, set `ip` to its address. See [Run on your own machine](/bring-your-own-machine).
 
-And as you make changes to `work-in-progress.test.mjs`, you can re-run just that file to quickly iterate on the failing steps.
+<EnterpriseCta feature="Connecting to your own machines" />
 
-```bash
-vitest run work-in-progress.test.mjs
+```javascript
+const testdriver = TestDriver(context, { ip: '203.0.113.42' });
 ```
 
-<Warning>
-  Connecting to the same machine only works if run within the `keepAlive` window of the previous test.
-</Warning>
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Options" icon="sliders" href="/options">
+    Every client option, with its default.
+  </Card>
+  <Card title="Client & connection" icon="plug" href="/client">
+    Create, connect, and disconnect a client.
+  </Card>
+  <Card title="Run tests" icon="play" href="/copilot/running-tests">
+    Run tests locally and reuse a sandbox.
+  </Card>
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Run tests on every pull request.
+  </Card>
+</CardGroup>