@testdriverai/agent 7.8.0-canary.10

package/docs/v7/copilot/setup.mdx

@@ -0,0 +1,143 @@
+---
+title: "GitHub Copilot Setup"
+sidebarTitle: "IDE Setup"
+description: "Install the TestDriver extension and configure MCP for GitHub Copilot"
+icon: "wrench"
+---
+
+TestDriver integrates with GitHub Copilot through the VS Code extension and MCP server. This guide walks you through the complete setup.
+
+## Prerequisites
+
+Before you begin, you'll need:
+
+- **GitHub Copilot** — A subscription with MCP access. A [free tier](https://github.com/features/copilot/plans) is available.
+- **TestDriver Account** — Create a free account at [console.testdriver.ai](https://console.testdriver.ai/team) to get your API key. 60 free device minutes, no credit card required.
+- **VS Code** — The TestDriver extension provides the best experience with live preview and integrated test running.
+
+## Setup Steps
+
+<Steps>
+  <Step title="Install the TestDriver Extension">
+    <Card
+      horizontal
+      title="Install TestDriver for VS Code"
+      arrow
+      href="vscode:extension/testdriver.testdriver"
+      icon="/images/content/extension/vscode.svg"
+    ></Card>
+
+    The extension provides:
+    - One-click sign-in and project initialization
+    - Live preview panel for watching tests execute
+    - MCP server configuration
+  </Step>
+
+  <Step title="Sign Into TestDriver">
+    Sign in to connect your account and API key.
+
+    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+    2. Run **TestDriver: Login**
+    3. Your browser will open to the TestDriver sign-in page
+    4. Sign in (or create an account)
+    5. You'll be redirected back to VS Code, now signed in
+
+    <Tip>
+      The extension automatically saves your API key to VS Code's secure storage and your workspace `.env` file.
+    </Tip>
+  </Step>
+
+  <Step title="Initialize Your Project">
+    Set up TestDriver in your project with a single command.
+
+    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+    2. Run **TestDriver: Init Project**
+
+    This command:
+    - Creates a `package.json` with TestDriver and Vitest dependencies
+    - Generates a `vitest.config.mjs` with proper timeout settings
+    - Creates example test files in `tests/`
+    - Sets up `.env` with your API key
+    - Creates the TestDriver agent file at `.github/agents/testdriver.agent.md`
+    - Configures the MCP server
+
+    <Note>
+      If you already have a `package.json`, the command will add the necessary dependencies to it.
+    </Note>
+  </Step>
+
+  <Step title="Start the MCP Server">
+    The MCP server enables GitHub Copilot to control TestDriver sandboxes.
+
+    After initialization, the MCP configuration is created at `.vscode/mcp.json`:
+
+    ```json .vscode/mcp.json
+    {
+      "servers": {
+        "testdriver": {
+          "command": "npx",
+          "args": ["-p", "testdriverai", "testdriverai-mcp"],
+          "env": {
+            "TD_PREVIEW": "ide",
+            "TD_API_KEY": "your-api-key"
+          }
+        }
+      }
+    }
+    ```
+
+    **To start the MCP server:**
+
+    1. Open the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+    2. Run **MCP: List Servers**
+    3. Click on the **testdriver** server
+    4. Select **Start Server**
+
+    You can also click the MCP icon in the status bar to manage servers.
+
+    <Tip>
+      See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details on managing MCP servers.
+    </Tip>
+
+    <Warning>
+      Make sure your API key is set. The extension uses the key from your sign-in, but you can also set it via the `TD_API_KEY` environment variable.
+    </Warning>
+  </Step>
+
+  <Step title="Install Vitest Extension (Recommended)">
+    For the best experience running tests, install the Vitest extension:
+
+    <Card
+      horizontal
+      title="Vitest Extension"
+      arrow
+      href="vscode:extension/vitest.explorer"
+      icon="flask-vial"
+    >
+      Run tests with GUI mode from the Test Explorer
+    </Card>
+
+    After installation, you'll see a beaker icon in the sidebar for accessing the Test Explorer.
+  </Step>
+</Steps>
+
+## Verify Your Setup
+
+To verify everything is configured correctly:
+
+1. Open the command palette and run **TestDriver: Check Status**
+2. You should see:
+   - ✅ Signed in
+   - ✅ MCP server configured
+   - ✅ Project initialized
+
+## The Agent File
+
+During initialization, TestDriver creates an agent file at `.github/agents/testdriver.agent.md`. This file tells GitHub Copilot how to use TestDriver's MCP tools.
+
+The agent has access to tools like:
+- `session_start` — Launch a sandbox with Chrome or other apps
+- `find` / `click` / `type` — Interact with elements on screen
+- `assert` — Verify conditions using AI vision
+- `screenshot` — Capture the current screen state
+

package/docs/v7/customizing-devices.mdx

@@ -0,0 +1,319 @@
+---
+title: "Customizing Devices"
+description: "Configure TestDriver sandbox options and environment settings"
+icon: "computer"
+---
+
+## TestDriver Options
+
+Configure TestDriver behavior with options passed to the `TestDriver()` function:
+
+```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: true)
+
+  // === 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
+});
+```
+
+### Preview Mode
+
+Control how test execution is visualized. The `preview` option determines where the live debugger view opens:
+
+```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:
+
+```javascript
+const testdriver = TestDriver(context, {
+  preview: "ide",  // Opens preview in IDE panel
+});
+```
+
+**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,
+});
+```
+
+### IP Target
+
+If self-hosting TestDriver, use `ip` to specify the device IP. See [Self-Hosting TestDriver](../self-hosting.md) 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:
+
+```bash
+# Run tests on Windows
+TD_OS=windows vitest run
+
+# Run tests on Linux (default)
+TD_OS=linux vitest run
+```
+
+This pattern is useful for running the same test suite across multiple operating systems in CI/CD:
+
+```yaml
+# Example GitHub Actions matrix
+strategy:
+  matrix:
+    os: [linux, windows]
+steps:
+  - run: TD_OS=${{ matrix.os }} vitest run
+```
+
+### Dashcam Recording
+
+Dashcam video recording is enabled by default. Disable it to skip recording:
+
+```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:
+
+```javascript
+const testdriver = TestDriver(context, {
+  autoScreenshots: false,
+});
+```
+
+### Caching
+
+Element caching speeds up repeated `find()` and `assert()` calls. Enabled by default.
+
+```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
+
+Redraw detection waits for the screen to stabilize before taking actions. Enabled by default.
+
+```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,
+    },
+  },
+});
+```
+
+### AI Configuration
+
+Control how the AI model generates responses for `find()` verification and `assert()` calls:
+
+```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:
+
+```javascript
+const testdriver = TestDriver(context, {
+  environment: {
+    MY_VAR: "value",
+    DEBUG: "true",
+  },
+});
+```
+
+## Keepalive
+
+By default, sandboxes stay alive for 60 seconds after disconnect. Customize this with `keepAlive`:
+
+```javascript
+const testdriver = TestDriver(context, {
+  keepAlive: 300000,  // Keep sandbox alive for 5 minutes after test
+});
+```
+
+Set to `0` to terminate immediately:
+
+```javascript
+const testdriver = TestDriver(context, {
+  keepAlive: 0,  // Terminate sandbox immediately on disconnect
+});
+```
+
+### Reconnecting to Existing Sandbox
+
+Speed up test development by reconnecting 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.
+
+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.
+
+```javascript known-good.test.mjs
+const testdriver = TestDriver(context, {
+  keepAlive: 60000,  // Keep sandbox alive for 60 seconds after test
+});
+```
+
+```javascript work-in-progress.test.mjs
+// Second test file: experiment.test.mjs (run within keepAlive window)
+const testdriver = TestDriver(context, {
+  reconnect: true,  // Reconnect to existing sandbox
+});
+```
+
+Then, you can run both tests in sequence:
+
+```bash
+vitest run -t known-good.test.mjs -t work-in-progress.test.mjs
+```
+
+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.
+
+```bash
+vitest run work-in-progress.test.mjs
+```
+
+<Warning>
+  Reconnect only works if run within the `keepAlive` window of the previous test.
+</Warning>