@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/copilot/running-tests.mdx

@@ -1,1010 +1,201 @@
 ---
-title: "Running Tests"
-sidebarTitle: "Running Tests"
-description: "Set up your environment and run TestDriver tests locally and in CI"
+title: "Run tests"
+sidebarTitle: "Running tests"
+description: "Run tests from the terminal or VS Code, in parallel, and watch them live."
 icon: "play"
 ---
 
-Run the tests you've explored and learned, anywhere. TestDriver tests are plain [Vitest](https://vitest.dev) files, so they run the same way on your machine and in CI — across web, desktop, and extensions on real VMs. This page walks through getting set up, configuring **where** and **how** your tests run (the device and app under test, and the sandbox machine), and actually running them locally and in CI.
-
-If you haven't written tests yet, start with [Explore](/generating-tests) to generate your first tests and [Learn](/caching) to make them fast and reliable.
-
-## Setup
-
-TestDriver integrates with AI coding assistants through the VS Code extension and MCP server. The same MCP server works with GitHub Copilot, Cursor, Claude Desktop, and any other MCP-capable assistant. This section walks you through the complete setup.
-
-### Prerequisites
-
-Before you begin, you'll need:
-
-- **An MCP-capable AI assistant** — Such as GitHub Copilot, Cursor, or Claude Desktop. For Copilot, 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/settings) 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 your AI assistant 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>
+TestDriver tests are ordinary [Vitest](https://vitest.dev) files. You run them with Vitest, on your machine and in CI.
 
-    After installation, you'll see a beaker icon in the sidebar for accessing the Test Explorer.
-  </Step>
-</Steps>
+Each test:
 
-### Verify Your Setup
+- Starts its own cloud sandbox.
+- Runs its steps.
+- Prints a link to a full report with a recording of the run.
 
-To verify everything is configured correctly:
+## Before you begin
 
-1. Open the command palette and run **TestDriver: Check Status**
-2. You should see:
-   - ✅ Signed in
-   - ✅ MCP server configured
-   - ✅ Project initialized
+- **A project with TestDriver installed**, with your API key in `.env` as `TD_API_KEY`. See [Set up a project](/quickstart-manual).
+- **At least one test**, which you can [generate with AI](/generating-tests) or write by hand.
 
-### The Agent File
+## Run tests from the terminal
 
-During initialization, TestDriver creates an agent file at `.github/agents/testdriver.agent.md`. This file tells your AI assistant 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
-
-## Configuring the Device
-
-Provision methods are the starting point for most tests. They launch applications in your sandbox and prepare the environment for testing — a browser, a desktop app, a Chrome extension, or VS Code.
-
-### Chrome Browser
-
-The most common starting point for web testing. Launches Chrome browser and navigates to a URL.
-
-```javascript
-await testdriver.provision.chrome({
-  url: 'https://example.com',
-});
-```
+Run every test in the project:
 
-#### Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `url` | string | `'http://testdriver-sandbox.vercel.app/'` | URL to navigate to |
-| `maximized` | boolean | `true` | Start browser maximized |
-| `guest` | boolean | `false` | Use guest mode (no profile) |
-
-#### Example: Basic Web Test
-
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-
-describe("Login Flow", () => {
-  it("should log in successfully", async (context) => {
-    const testdriver = TestDriver(context);
-    
-    await testdriver.provision.chrome({
-      url: 'https://myapp.com/login',
-    });
-
-    await testdriver.find("Email input").click();
-    await testdriver.type("user@example.com");
-    
-    await testdriver.find("Password input").click();
-    await testdriver.type("password123");
-    
-    await testdriver.find("Sign In button").click();
-    
-    const result = await testdriver.assert("the dashboard is visible");
-    expect(result).toBeTruthy();
-  });
-});
+```bash
+npx vitest run
 ```
 
-<Info>
-  `provision.chrome()` automatically starts Dashcam recording and waits for Chrome to be ready before returning.
-</Info>
-
-### Chrome Extensions
+Vitest finds files whose names end in `.test` or `.spec` plus a JavaScript or TypeScript extension, such as `tests/login.test.mjs`.
 
-Launch Chrome with a custom extension loaded. Supports both local extensions and Chrome Web Store extensions.
+To run part of your suite, pass files, folders, or a name filter:
 
-#### Load from Local Path
-
-Clone or create an extension locally, then load it:
-
-```javascript
-// First, get the extension onto the sandbox
-await testdriver.exec(
-  'sh',
-  'git clone https://github.com/user/my-extension.git /tmp/my-extension',
-  60000
-);
-
-// Launch Chrome with the extension
-await testdriver.provision.chromeExtension({
-  extensionPath: '/tmp/my-extension',
-  url: 'https://example.com'
-});
-```
-
-#### Load from Chrome Web Store
+```bash
+# One file
+npx vitest run tests/login.test.mjs
 
-Load any published extension by its Chrome Web Store ID:
+# Every test in a folder
+npx vitest run tests/checkout/
 
-```javascript
-await testdriver.provision.chromeExtension({
-  extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm', // uBlock Origin
-  url: 'https://example.com'
-});
+# Only tests whose name matches
+npx vitest run -t "login"
 ```
 
-<Tip>
-  Find the extension ID in the Chrome Web Store URL. For example, `https://chrome.google.com/webstore/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm` → ID is `cjpalhdlnbpafiamejdnhcphjbkeiagm`
-</Tip>
+Use `npx vitest` (without `run`) for watch mode. It reruns tests when you save a file.
 
-#### Options
+## Run tests from VS Code
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `extensionPath` | string | - | Local path to unpacked extension directory |
-| `extensionId` | string | - | Chrome Web Store extension ID |
-| `url` | string | - | URL to navigate to after launch |
-| `maximized` | boolean | `true` | Start browser maximized |
+Install the [Vitest extension](https://marketplace.visualstudio.com/items?itemName=vitest.explorer) to run tests from the **Testing** view. Click the run button next to a file or test. The result appears inline next to the code.
 
-<Warning>
-  You must provide either `extensionPath` or `extensionId`, but not both.
-</Warning>
-
-#### Example: Testing a Chrome Extension
-
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-
-describe("Chrome Extension Test", () => {
-  it("should load and interact with extension", async (context) => {
-    const testdriver = TestDriver(context);
-
-    // Clone extension from GitHub
-    await testdriver.exec(
-      'sh',
-      'git clone https://github.com/user/my-extension.git /tmp/my-extension',
-      60000,
-      true
-    );
-
-    // Launch Chrome with extension loaded
-    await testdriver.provision.chromeExtension({
-      extensionPath: '/tmp/my-extension',
-      url: 'https://testdriver.ai'
-    });
-
-    // Click extensions puzzle icon
-    const extensionsButton = await testdriver.find("puzzle-shaped icon in Chrome toolbar");
-    await extensionsButton.click();
-
-    // Interact with your extension
-    const myExtension = await testdriver.find("My Extension in the dropdown");
-    await myExtension.click();
+To watch the sandbox in a panel beside your code, install the [TestDriver extension](/quickstart-vscode) and use the `ide` preview mode below.
 
-    const result = await testdriver.assert("extension popup is visible");
-    expect(result).toBeTruthy();
-  });
-});
-```
+## Watch a test run
 
-### Desktop Apps
+TestDriver shows each run live. Choose where with the `preview` option or the `TD_PREVIEW` environment variable:
 
-Download and install desktop applications. Supports `.deb`, `.rpm`, `.msi`, `.exe`, `.AppImage`, `.dmg`, `.pkg`, and shell scripts.
+| Mode | Where the run appears |
+| --- | --- |
+| `"browser"` (default) | A live view in your web browser |
+| `"ide"` | A panel in VS Code or Cursor (requires the TestDriver extension) |
+| `"none"` | Nowhere, for CI and other headless runs |
 
 ```javascript
-const filePath = await testdriver.provision.installer({
-  url: 'https://example.com/app.deb',
-  appName: 'MyApp',  // Focus this app after install
-  launch: true,      // Auto-launch after install
-});
+const testdriver = TestDriver(context, { preview: 'ide' });
 ```
 
-#### Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `url` | string | **required** | URL to download the installer from |
-| `filename` | string | auto-detected | Filename to save as |
-| `appName` | string | - | Application name to focus after install |
-| `launch` | boolean | `true` | Launch the app after installation |
-
-#### Supported File Types
-
-| Extension | OS | Install Method |
-|-----------|-----|----------------|
-| `.deb` | Linux | `dpkg -i` + `apt-get install -f` |
-| `.rpm` | Linux | `rpm -i` |
-| `.AppImage` | Linux | `chmod +x` |
-| `.sh` | Linux | `chmod +x` + execute |
-| `.msi` | Windows | `msiexec /i /quiet` |
-| `.exe` | Windows | Silent install (`/S`) |
-| `.dmg` | macOS | Mount + copy to Applications |
-| `.pkg` | macOS | `installer -pkg` |
+## Open the test report
 
-#### Example: Install and Test a Desktop App
+When a test finishes, TestDriver prints a link to its report:
 
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-
-describe("Desktop App Test", () => {
-  it("should install and launch app", async (context) => {
-    const testdriver = TestDriver(context);
-
-    // Download and install
-    const installerPath = await testdriver.provision.installer({
-      url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
-    });
-
-    // Verify installation
-    const output = await testdriver.exec('sh', 'bat --version', 5000);
-    expect(output).toContain('bat');
-  });
-});
+```text
+TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/abc123
 ```
 
-#### Example: Windows Installer
-
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+The report includes the run's recording, screenshots, and logs. Every past run is in the [TestDriver console](https://console.testdriver.ai).
 
-describe("Windows App Test", () => {
-  it("should install on Windows", async (context) => {
-    const testdriver = TestDriver(context, { 
-      os: 'windows'
-    });
+## Run tests in parallel
 
-    // Download MSI installer
-    const installerPath = await testdriver.provision.installer({
-      url: 'https://example.com/app.msi',
-      launch: false,  // Don't auto-launch
-    });
+Vitest runs test files in parallel, and each running test gets its own sandbox. Your plan sets how many sandboxes can run at once.
 
-    // Custom installation if needed
-    await testdriver.exec(
-      'pwsh',
-      `Start-Process msiexec.exe -ArgumentList "/i", "${installerPath}", "/qn" -Wait`,
-      120000
-    );
-
-    // Verify installation
-    const result = await testdriver.assert("application is installed");
-    expect(result).toBeTruthy();
-  });
-});
-```
+At the limit, a new test waits for a free slot instead of failing. By default, the SDK retries every 10 seconds for up to 60 seconds.
 
-#### Manual Installation
+Set `TD_CONCURRENCY_MAX_WAIT` (in seconds) to wait longer, or to `0` to fail immediately.
 
-Set `launch: false` to download without auto-installing:
+To cap how many test files run at once on your machine, limit Vitest's workers:
 
-```javascript
-const filePath = await testdriver.provision.installer({
-  url: 'https://example.com/custom-script.sh',
-  launch: false,
-});
-
-// Run custom install commands
-await testdriver.exec('sh', `chmod +x "${filePath}"`, 5000);
-await testdriver.exec('sh', `"${filePath}" --custom-flag`, 60000);
-```
-
-### VS Code
-
-Launch Visual Studio Code with optional workspace and extensions.
-
-```javascript
-await testdriver.provision.vscode({
-  workspace: '/home/testdriver/my-project',
-  extensions: ['ms-python.python', 'esbenp.prettier-vscode'],
-});
+```bash
+npx vitest run --maxWorkers=5
 ```
 
-#### Options
+For CI setups and parallel job matrices, see [Run tests in CI/CD](/ci-cd#concurrency-limits).
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `workspace` | string | - | Workspace folder to open |
-| `extensions` | string[] | `[]` | Extensions to install (by ID) |
+## Reuse a sandbox while you iterate
 
-#### Example: VS Code Extension Test
+Each test normally starts a fresh sandbox, which takes time to boot, especially on Windows.
 
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+While you work on a long flow, keep the sandbox running between runs and reconnect to it. Then you only rerun the steps you're changing.
 
-describe("VS Code Test", () => {
-  it("should open workspace with extensions", async (context) => {
-    const testdriver = TestDriver(context);
+1. Run the steps that already work with a longer `keepAlive`. It keeps the sandbox running for that many milliseconds after the test ends (60 seconds by default, up to 30 minutes):
 
-    // Create a test project
-    await testdriver.exec('sh', 'mkdir -p /tmp/test-project && echo "print(1)" > /tmp/test-project/test.py', 10000);
-
-    // Launch VS Code
-    await testdriver.provision.vscode({
-      workspace: '/tmp/test-project',
-      extensions: ['ms-python.python'],
+    ```javascript tests/setup-cart.test.mjs
+    const testdriver = TestDriver(context, {
+      keepAlive: 10 * 60 * 1000, // 10 minutes
     });
 
-    // Verify VS Code is ready
-    const result = await testdriver.assert("VS Code is open with the project");
-    expect(result).toBeTruthy();
-
-    // Open the Python file
-    await testdriver.find("test.py in the explorer").click();
-  });
-});
-```
-
-### Choosing the Right Provision Method
-
-| Use Case | Method |
-|----------|--------|
-| Testing a website | `provision.chrome` |
-| Testing a Chrome extension | `provision.chromeExtension` |
-| Testing a desktop app (needs installation) | `provision.installer` |
-| Testing VS Code or VS Code extensions | `provision.vscode` |
-
-<Tip>
-  All provision methods automatically start Dashcam recording and wait for the application to be ready before returning. You don't need to call `dashcam.start()` manually.
-</Tip>
-
-## Configuring the Machine
-
-TestDriver provisions a fresh cloud VM for every test by default. This section covers how to configure Linux and Windows machines, reduce startup time by keeping machines alive between runs, use provision scripts for repeatable setup, and install custom software on the fly.
-
-### Linux Machines
-
-Linux is the default operating system. No extra configuration is required.
-
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-
-describe("My Test", () => {
-  it("runs on Linux", async (context) => {
-    const testdriver = TestDriver(context);
-
-    await testdriver.provision.chrome({ url: "https://example.com" });
-
-    const result = await testdriver.assert("the page loaded successfully");
-    expect(result).toBeTruthy();
-  });
-});
-```
-
-#### Common Linux Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `os` | string | `"linux"` | Operating system |
-| `resolution` | string | `"1366x768"` | Screen resolution (Enterprise only) |
-| `e2bTemplateId` | string | — | Custom E2B template ID (see [Self-Hosted](/self-hosted)) |
-| `keepAlive` | number | `60000` | Ms to keep VM alive after disconnect |
-| `reconnect` | boolean | `false` | Reconnect to last used sandbox |
-
-```javascript
-const testdriver = TestDriver(context, {
-  os: "linux",
-  resolution: "1920x1080",
-  keepAlive: 5 * 60 * 1000, // keep alive 5 minutes
-});
-```
-
-### Windows Machines
-
-Set `os: "windows"` to provision a Windows VM instead. Everything else works the same way.
-
-```javascript
-const testdriver = TestDriver(context, {
-  os: "windows",
-});
-
-await testdriver.provision.chrome({ url: "https://example.com" });
-```
-
-Windows sandboxes use EC2 instances and take longer to boot than Linux (E2B) sandboxes — typically 1–3 minutes for a cold start. See [Keeping Machines Alive](#keeping-machines-alive-between-runs) below to avoid this cost on repeated runs.
-
-#### Common Windows Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `os` | string | — | Set to `"windows"` |
-| `resolution` | string | `"1366x768"` | Screen resolution (Enterprise only) |
-| `sandboxAmi` | string | — | Custom AMI ID (self-hosted) |
-| `sandboxInstance` | string | — | EC2 instance type (self-hosted) |
-| `keepAlive` | number | `60000` | Ms to keep VM alive after disconnect |
-| `reconnect` | boolean | `false` | Reconnect to last used sandbox |
-
-```javascript
-const testdriver = TestDriver(context, {
-  os: "windows",
-  resolution: "1920x1080",
-  keepAlive: 10 * 60 * 1000, // keep alive 10 minutes
-});
-```
-
-### Keeping Machines Alive Between Runs
-
-Windows (and Linux) cold starts can be expensive if you're iterating quickly. Use `keepAlive` + `reconnect` to reuse the same VM across multiple test runs.
-
-#### How it works
-
-Every time the SDK successfully connects to a sandbox, it records the sandbox id in `.testdriver/last-sandbox` inside your project directory. The next test that opts in with `reconnect: true` reads that file and reattaches automatically — no manual id tracking required.
-
-Provision calls (`testdriver.provision.chrome(...)`, `vscode(...)`, etc.) are **skipped** when reconnecting, because the application is already running inside the sandbox from the previous run.
-
-<Note>
-  `.testdriver/last-sandbox` is already covered by the default TestDriver `.gitignore`. Don't commit it.
-</Note>
-
-#### Step 1 — Start the machine with a long `keepAlive`
-
-```javascript
-// first.test.mjs
-const testdriver = TestDriver(context, {
-  os: "windows",
-  keepAlive: 30 * 60 * 1000, // keep alive 30 minutes after this test ends
-});
-
-await testdriver.provision.chrome({ url: "https://example.com" });
-// ... your test steps
-```
-
-When this test finishes, the sandbox stays running for 30 minutes instead of being terminated immediately.
-
-#### Step 2 — Reattach automatically with `reconnect: true`
-
-```javascript
-// second.test.mjs
-const testdriver = TestDriver(context, {
-  os: "windows",
-  reconnect: true,            // ← reads .testdriver/last-sandbox
-  keepAlive: 30 * 60 * 1000,
-});
-
-// No provision call — Chrome is already open from the previous run.
-await testdriver.find("Sign In button").click();
-```
-
-#### Step 2 (alternative) — Reattach to an explicit id
-
-If you need to pin to a specific sandbox (CI matrix, multiple chains in parallel, etc.) pass the id directly:
-
-```javascript
-await testdriver.connect({ sandboxId: "sandbox-abc123" });
-```
-
-When reattaching to a sandbox:
-- You reuse a specific running machine directly
-- You continue from the app state created in the earlier run
-- You must run within the previous test's `keepAlive` window
-
-<Tip>
-  Use `testdriver.getLastSandboxId()` to read the recorded sandbox id (and optional metadata) for scripting purposes.
-</Tip>
-
-#### Chaining describe blocks within one test file
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
+    // ...steps that log in and fill the cart
+    ```
 
-A common pattern is to break a long flow into focused `describe` blocks that share one sandbox — the first block provisions and signs in, later blocks reconnect and continue:
+2. In the file you're working on, set `reconnect: true`. TestDriver reattaches to the last sandbox it used, recorded in `.testdriver/last-sandbox`. It skips `provision` calls because the app is already open:
 
-```javascript
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
-
-const KEEP_ALIVE_MS = 5 * 60 * 1000;
-
-describe("step 1 — log in", () => {
-  it("signs in and lands on the dashboard", async (context) => {
-    const testdriver = TestDriver(context, { keepAlive: KEEP_ALIVE_MS });
-    await testdriver.provision.chrome({ url: "https://example.com/login" });
-    await testdriver.find("username input").click();
-    await testdriver.type("standard_user");
-    await testdriver.pressKeys(["tab"]);
-    await testdriver.type("secret_sauce", { secret: true });
-    await testdriver.pressKeys(["enter"]);
-    expect(await testdriver.assert("the dashboard is visible")).toBeTruthy();
-  });
-});
-
-describe("step 2 — add to cart", () => {
-  it("reuses the logged-in sandbox", async (context) => {
+    ```javascript tests/checkout.test.mjs
     const testdriver = TestDriver(context, {
-      reconnect: true,           // ← skip provisioning, reattach
-      keepAlive: KEEP_ALIVE_MS,
+      reconnect: true,
+      keepAlive: 10 * 60 * 1000,
     });
-    await testdriver.find("Add to cart").click();
-    await testdriver.find("cart icon").click();
-    expect(await testdriver.assert("the cart has an item")).toBeTruthy();
-  });
-});
-
-describe("step 3 — check out", () => {
-  it("continues from the cart state", async (context) => {
-    const testdriver = TestDriver(context, { reconnect: true, keepAlive: 30_000 });
-    await testdriver.find("Checkout").click();
-    expect(await testdriver.assert("the checkout form is visible")).toBeTruthy();
-  });
-});
-```
-
-A runnable copy of this pattern lives at [`examples/reconnect-sequential.test.mjs`](https://github.com/testdriverai/mono/blob/main/sdk/examples/reconnect-sequential.test.mjs).
 
-<Warning>
-  Vitest runs **test files** in parallel by default. Within a single file, `describe`/`it` blocks run in source order, so reconnect chaining works as written. To chain across multiple files, run them sequentially (e.g. `vitest run --sequence.concurrent=false` or place them in a single project pool with workers set to 1).
-</Warning>
-
-#### How `keepAlive` works
-
-`keepAlive` is a duration in milliseconds. After the SDK disconnects, the server keeps the VM running for that long before terminating it. The default is `60000` (1 minute). Note: `keepAlive: 0` currently falls back to the default disconnect grace period rather than terminating immediately, so use a positive duration when you want to control the grace window explicitly.
-
-```javascript
-const testdriver = TestDriver(context, {
-  keepAlive: 0,           // currently uses the default 1 minute grace period
-  // keepAlive: 60000,    // default — 1 minute
-  // keepAlive: 600000,   // 10 minutes
-  // keepAlive: 3600000,  // 1 hour
-});
-```
-
-<Warning>
-  Machines kept alive beyond your test session continue to consume credits. Always set a `keepAlive` value appropriate for your workflow.
-</Warning>
-
-### Using Provision Scripts
-
-Provision scripts let you run arbitrary setup steps before your test starts — downloading fixtures, seeding a database, configuring environment variables, and more. Use `testdriver.exec()` to run shell or PowerShell commands directly in the sandbox.
-
-<Card
-  title="exec() Reference"
-  icon="terminal"
-  href="/exec"
->
-  Full reference for running shell and PowerShell commands in the sandbox.
-</Card>
-
-#### Linux setup script
-
-```javascript
-await testdriver.provision.chrome({ url: "https://myapp.com" });
-
-// Run a setup script from your repo
-await testdriver.exec("sh", `
-  curl -s https://myapp.com/api/reset-test-db -X POST
-  echo "Test DB reset"
-`, 30000);
-```
-
-#### Windows setup script (PowerShell)
-
-```javascript
-await testdriver.provision.chrome({ url: "https://myapp.com" });
-
-await testdriver.exec("pwsh", `
-  $env:API_URL = "https://staging.myapp.com"
-  Write-Host "Environment configured"
-`, 15000);
-```
-
-#### Clone a repo and run a script
-
-```javascript
-await testdriver.exec("sh", `
-  git clone https://github.com/myorg/test-fixtures.git /tmp/fixtures
-  bash /tmp/fixtures/seed.sh
-`, 120000);
-```
-
-### Installing Custom Software
-
-You can install software at the start of a test using `exec()`. This works for any package available via `apt`, `brew`, `choco`, `winget`, npm, pip, or direct download.
-
-#### Linux — apt packages
-
-```javascript
-await testdriver.exec("sh", `
-  sudo apt-get update -qq
-  sudo apt-get install -y ffmpeg imagemagick
-`, 120000);
-```
-
-#### Linux — Node.js tools
-
-```javascript
-await testdriver.exec("sh", "npm install -g @playwright/test", 60000);
-```
-
-#### Windows — winget
-
-```javascript
-await testdriver.exec("pwsh", `
-  winget install --id=7zip.7zip -e --silent
-`, 120000);
-```
-
-#### Windows — Chocolatey
-
-```javascript
-await testdriver.exec("pwsh", `
-  choco install googlechrome --yes --no-progress
-`, 180000);
-```
-
-#### Download and run an installer
-
-```javascript
-// Linux
-await testdriver.exec("sh", `
-  curl -L https://example.com/installer.sh -o /tmp/installer.sh
-  chmod +x /tmp/installer.sh
-  /tmp/installer.sh --silent
-`, 300000);
-
-// Windows
-await testdriver.exec("pwsh", `
-  Invoke-WebRequest -Uri "https://example.com/installer.exe" -OutFile "$env:TEMP\\installer.exe"
-  Start-Process "$env:TEMP\\installer.exe" -ArgumentList "/S" -Wait
-`, 300000);
-```
-
-<Note>
-  Installing software at test start adds to your test duration. For software you use in every test, consider preloading it into a custom VM image via the Enterprise self-hosted plan.
-</Note>
-
-#### Want Software Pre-Installed on Every Machine?
-
-Installing packages at runtime works well for occasional or lightweight dependencies. But if you're installing the same 5-minute setup on every test run, you're wasting time and credits.
-
-With the **Self-Hosted Enterprise plan** you get access to our golden VM base image and Packer scripts, so you can bake your applications, dependencies, and configuration directly into a custom AMI. Tests spin up with everything already installed — zero setup time.
-
-<Card
-  title="Self-Hosted Enterprise"
-  icon="server"
-  href="/self-hosted"
->
-  Preload software, configure custom hardware, and run unlimited tests with a flat license fee. Our team assists with deployment and setup.
-</Card>
-
-## Running Tests
-
-After creating tests with the TestDriver agent, you can re-run them without starting a new MCP session. Tests are saved as standard Vitest files that run independently — the same way on your machine and in CI.
-
-### Running from Terminal
-
-TestDriver works with [Vitest's](https://vitest.dev) test runner. Use Vitest to run your tests from the command line to see full output:
-
-```bash
-# Run all tests
-vitest run
-
-# Run a specific test file
-vitest run tests/login.test.mjs
-
-# Run in watch mode (re-runs on file changes)
-vitest
-```
-
-<Info>
-  Install Vitest globally for best results: `npm install vitest -g`
-</Info>
-
-Vitest automatically discovers files matching patterns like `*.test.js`, `*.test.mjs`, or `*.spec.js`.
-
-#### Common CLI options
-
-```bash
-# Run multiple specific files
-vitest run login.test.mjs checkout.test.mjs
-
-# Run every test in a folder
-vitest run tests/e2e/
-
-# Filter tests by name (supports regex)
-vitest run --grep "login"
-
-# Generate a coverage report
-vitest run --coverage
-```
-
-<Info>
-  Coverage requires the `@vitest/coverage-v8` package. Install it with `npm install -D @vitest/coverage-v8`.
-</Info>
-
-#### Vitest UI
-
-For interactive debugging, launch the web-based UI (starts in watch mode):
-
-```bash
-vitest --ui
-```
-
-Open http://localhost:51204 to browse your test tree, see pass/fail states and timing, view inline console output, and re-run individual tests.
-
-<Tip>
-  Combine with `--open` to open the UI in your browser automatically: `vitest --ui --open`
-</Tip>
-
-### Running from VS Code (GUI Mode)
-
-For a visual testing experience, use the **Vitest extension**:
-
-<Steps>
-  <Step title="Open Test Explorer">
-    Click the **beaker icon** in the VS Code sidebar to open the Test Explorer. This shows all your test files and test cases.
-  </Step>
-
-  <Step title="Run Tests">
-    Click the **play button** next to any test file or individual test to run it. You can also:
-    - Run all tests with the "Run All" button
-    - Debug tests with the "Debug" button
-  </Step>
-
-  <Step title="View Results">
-    Test results appear inline:
-    - ✅ Green checkmark for passing tests
-    - ❌ Red X for failing tests
-    - Click on a failing test to see error details
-  </Step>
-</Steps>
-
-<Warning>
-  VS Code's Test Explorer only shows output for **failing tests**. To see output from passing tests (including screenshots and console logs), run tests from the terminal instead.
-</Warning>
-
-### Test Configuration
-
-#### Timeouts
-
-TestDriver tests require longer timeouts than typical unit tests. Your `vitest.config.mjs` should have:
-
-```javascript vitest.config.mjs
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    testTimeout: 900000,  // 15 minutes
-    hookTimeout: 900000,  // 15 minutes for setup/teardown
-  },
-});
-```
-
-#### Environment Variables
-
-Tests use the `TD_API_KEY` environment variable. Set it in your `.env` file:
-
-```env .env
-TD_API_KEY=your-api-key-here
-```
-
-Or pass it when running tests:
-
-```bash
-TD_API_KEY=your-key vitest run
-```
-
-### Parallel Execution
-
-TestDriver runs each test in its own cloud sandbox, enabling true parallel execution. Run your entire test suite in minutes instead of hours.
-
-Your TestDriver plan includes a set number of **license slots** that determine how many tests can run simultaneously. Each running test occupies one slot — when the test completes and the sandbox is destroyed, the slot is immediately freed for the next test.
-
-Set `maxConcurrency` in your Vitest config to match your license slot limit:
-
-```javascript vitest.config.mjs
-import { defineConfig } from 'vitest/config';
-import TestDriver from 'testdriverai/vitest';
-
-export default defineConfig({
-  test: {
-    testTimeout: 900000,
-    hookTimeout: 900000,
-    maxConcurrency: 5, // Match your license slot limit
-    reporters: ['default', TestDriver()],
-    setupFiles: ['testdriverai/vitest/setup'],
-  },
-});
-```
-
-You can also cap concurrency from the CLI:
+    // No provision call: Chrome is still open from the previous run
+    const checkoutButton = await testdriver.find('Checkout button');
+    await checkoutButton.click();
+    ```
 
-```bash
-vitest run --maxConcurrency=5
-```
+Run the second file within the first file's `keepAlive` window. Reconnecting fails if the sandbox has already shut down.
 
 <Warning>
-  Setting `maxConcurrency` higher than your license slots will cause tests to fail when slots are exhausted. Always match this value to your plan's limit.
+  A kept-alive sandbox uses your plan's testing minutes until it shuts down. Use a `keepAlive` no longer than you need.
 </Warning>
 
-| Test Suite | Sequential (1 slot) | Parallel (5 slots) | Parallel (10 slots) |
-|------------|--------------------|--------------------|---------------------|
-| 10 tests @ 2min each | 20 min | 4 min | 2 min |
-| 50 tests @ 2min each | 100 min | 20 min | 10 min |
-| 100 tests @ 2min each | 200 min | 40 min | 20 min |
-
-<Info>
-  View your available slots at [console.testdriver.ai](https://console.testdriver.ai). Upgrade anytime to increase parallelization.
-</Info>
+To connect to a specific sandbox instead, or for more sandbox options, see [Customize devices](/customizing-devices#keep-a-sandbox-alive).
 
-### Viewing Test Reports
+## Fix a failing test
 
-After each test run, TestDriver provides a link to the full test report:
+When the app changes and a test no longer matches it, ask the TestDriver agent to update the test. It reruns the flow in a sandbox and sees the current screen:
 
-```
-TESTDRIVER_RUN_URL=https://console.testdriver.ai/runs/abc123
+```text
+The login test is failing because the form layout changed. Update tests/login.test.mjs to match the new design.
 ```
 
-The report includes:
-- Video recording of the test
-- Screenshots at each step
-- Network logs and performance metrics
-- Console output and errors
+For small changes, such as an updated `find()` description or assertion, edit the test file directly.
 
-<Card
-  title="View Test Reports"
-  icon="chart-line"
-  href="https://console.testdriver.ai"
->
-  Access all your test runs and recordings in the TestDriver console
-</Card>
+To dig into what went wrong in a run, see [Debug with screenshots](/debugging-with-screenshots).
 
-### Iterating on Tests
+## Troubleshooting
 
-When tests fail or need updates, you have two options:
+<AccordionGroup>
+  <Accordion title="Tests fail with a Vitest timeout">
 
-#### Option 1: Ask the AI Assistant (Recommended)
+    Tests that drive a real machine take longer than Vitest's 5-second default. Set `testTimeout` and `hookTimeout` in `vitest.config.mjs`.
 
-For discovering updated element descriptions or debugging failures, chat with the TestDriver agent through your AI assistant:
+    `npx testdriverai init` sets both to 5 minutes:
 
-```
-The login test is failing because the form layout changed.
-Update tests/login.test.mjs to work with the new design.
-```
+    ```javascript vitest.config.mjs
+    import { defineConfig } from 'vitest/config';
+    import TestDriver from 'testdriverai/vitest';
 
-The agent will:
-1. Start a new session
-2. Navigate to the page
-3. Analyze the current state
-4. Update the test code
+    export default defineConfig({
+      test: {
+        testTimeout: 300000,
+        hookTimeout: 300000,
+        reporters: ['default', TestDriver()],
+        setupFiles: ['testdriverai/vitest/setup'],
+      },
+    });
+    ```
 
-This is the best approach when:
-- Element text or layout has changed
-- You need to see what's currently on screen
-- The failure reason isn't obvious from the error message
+  </Accordion>
+  <Accordion title="TestDriver can't find my API key">
 
-#### Option 2: Edit the Code Directly
+    The SDK reads `TD_API_KEY` from the environment. It loads `.env` in your project root automatically.
 
-For simple changes, edit the test files directly:
+    Check that `.env` contains `TD_API_KEY=...`, or set the variable for one run:
 
-```javascript
-// Change the element description
-const button = await testdriver.find("Submit Order button");
+    ```bash
+    TD_API_KEY=your_api_key npx vitest run
+    ```
 
-// Add a wait
-await testdriver.wait(2000);
+  </Accordion>
+  <Accordion title="Tests wait a long time before starting">
 
-// Update assertions
-const result = await testdriver.assert("order confirmation shows order ID");
-```
+    You're probably at your plan's sandbox limit, and tests are waiting for a free slot.
 
-This is faster for:
-- Updating text strings
-- Adjusting timeouts
-- Fixing typos
+    Run fewer files at once with `--maxWorkers`, or check your plan in the [TestDriver console](https://console.testdriver.ai).
 
-<Tip>
-  When a test fails because the UI shifted, let TestDriver fix it for you automatically. See [Prevent](/copilot/auto-healing) for auto-healing, and [Debug](/debugging-with-screenshots) for inspecting screenshots when a run goes wrong.
-</Tip>
+  </Accordion>
+</AccordionGroup>
 
-## Next
+## Next steps
 
-<Card
-  title="Validate"
-  icon="circle-check"
-  href="/making-assertions"
->
-  Now that your tests run anywhere, learn how to make strong assertions that catch real bugs.
-</Card>
+<CardGroup cols={2}>
+  <Card title="Make assertions" icon="circle-check" href="/making-assertions">
+    Write checks that catch the regressions you care about.
+  </Card>
+  <Card title="Debug with screenshots" icon="bug" href="/debugging-with-screenshots">
+    See what the sandbox showed at each step of a run.
+  </Card>
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Run your tests on every push and pull request.
+  </Card>
+  <Card title="Launch apps" icon="rocket" href="/provision">
+    Start Chrome, extensions, VS Code, or desktop apps in the sandbox.
+  </Card>
+</CardGroup>