@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/provision.mdx

@@ -1,314 +1,269 @@
 ---
-title: "Spawning a sandbox"
-sidebarTitle: "Spawning a sandbox"
-description: "Launch browsers, desktop apps, and extensions in your sandbox"
+title: "Launch apps in the sandbox"
+sidebarTitle: "Launching apps"
+description: "Start Chrome, a Chrome extension, VS Code, an Electron app, or an installer in the sandbox."
 icon: "rocket"
 mode: "wide"
 ---
 
-## Overview
-
-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.
-
-Use the provision methods through `testdriver.provision.*`:
+Start the app you want to test with a `provision` method. Call one at the beginning of each test.
 
 ```javascript
-await testdriver.provision.chrome({ url: 'https://example.com' });
+await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 ```
 
-## Methods
+Every provision method:
 
-### chrome()
+- Launches or installs the app in the sandbox. The Chrome methods also wait until Chrome is ready.
+- Starts the [Dashcam](/dashcam) recording, unless you turned it off with `dashcam: false`.
+- Does nothing when the client was created with `reconnect: true`, because the app is already running.
 
-Start Google Chrome with an optional URL.
+| Method | Use it to test |
+| --- | --- |
+| [`chrome()`](#chrome-options) | A website |
+| [`chromeExtension()`](#chromeextension-options) | A Chrome extension |
+| [`vscode()`](#vscode-options) | VS Code or a VS Code extension |
+| [`installer()`](#installer-options) | A desktop app you download and install |
+| [`electron()`](#electron-options) | An Electron app |
+| [`dashcam()`](#dashcam-options) | Custom recording settings |
 
-```javascript
-await testdriver.provision.chrome(options?)
+## chrome(options)
+
+Opens Chrome at a URL.
+
+```typescript
+testdriver.provision.chrome(options?: ProvisionChromeOptions): Promise<void>
 ```
 
 <ParamField path="options" type="ProvisionChromeOptions">
   <Expandable title="properties">
     <ParamField path="url" type="string" default="http://testdriver-sandbox.vercel.app/">
-      The URL to go to after Chrome starts.
+      The page to open.
     </ParamField>
-    
-    <ParamField path="maximized" type="boolean" default={true}>
-      Start Chrome with the window at the maximum size.
+    <ParamField path="maximized" type="boolean" default="true">
+      Start with the window maximized.
     </ParamField>
-    
-    <ParamField path="guest" type="boolean" default={false}>
-      Start Chrome in the guest profile mode.
+    <ParamField path="guest" type="boolean" default="false">
+      Use Chrome's guest profile, with no saved data.
     </ParamField>
   </Expandable>
 </ParamField>
 
+Chrome also records the site's network traffic in the Dashcam replay.
+
 ```javascript
-// Basic
-await testdriver.provision.chrome({ url: 'https://example.com' });
-
-// With guest mode
-await testdriver.provision.chrome({
-  url: 'https://example.com',
-  guest: true,
-  maximized: true,
-});
+await testdriver.provision.chrome({ url: 'https://example.com', guest: true });
 ```
 
-### chromeExtension()
+## chromeExtension(options)
 
-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.
+Opens Chrome with an extension loaded.
 
-```javascript
-await testdriver.provision.chromeExtension(options)
+```typescript
+testdriver.provision.chromeExtension(options: ProvisionChromeExtensionOptions): Promise<void>
 ```
 
 <ParamField path="options" type="ProvisionChromeExtensionOptions" required>
-  One of `extensionPath` or `extensionId` is required.
+  Pass either `extensionId` or `extensionPath`. It throws if you pass neither.
 
   <Expandable title="properties">
-    <ParamField path="extensionPath" type="string">
-      Local path to an unpacked extension directory. The extension files are uploaded to the sandbox.
-    </ParamField>
-    
     <ParamField path="extensionId" type="string">
-      Chrome Web Store extension ID to install.
+      A Chrome Web Store extension ID. TestDriver downloads the extension into the sandbox.
     </ParamField>
-    
-    <ParamField path="maximized" type="boolean" default={true}>
-      Launch Chrome in maximized window mode.
+    <ParamField path="extensionPath" type="string">
+      The path to an unpacked extension **inside the sandbox**. Nothing is copied from your machine, so get the files there first, for example with [`exec()`](/exec).
+    </ParamField>
+    <ParamField path="maximized" type="boolean" default="true">
+      Start with the window maximized.
     </ParamField>
   </Expandable>
 </ParamField>
 
+From the Chrome Web Store:
+
 ```javascript
-// From local directory
 await testdriver.provision.chromeExtension({
-  extensionPath: './my-extension',
+  extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm', // uBlock Origin
 });
+```
 
-// From Chrome Web Store
-await testdriver.provision.chromeExtension({
-  extensionId: 'abcdefghijklmnop',
+From source:
+
+```javascript
+await testdriver.exec({
+  language: 'sh',
+  code: 'git clone https://github.com/your-org/your-extension.git /tmp/your-extension',
 });
+await testdriver.provision.chromeExtension({ extensionPath: '/tmp/your-extension' });
 ```
 
-### vscode()
+## vscode(options)
 
-Launch Visual Studio Code with an optional workspace and extensions.
+Opens VS Code, optionally with a folder and extensions.
 
-```javascript
-await testdriver.provision.vscode(options?)
+```typescript
+testdriver.provision.vscode(options?: ProvisionVSCodeOptions): Promise<void>
 ```
 
 <ParamField path="options" type="ProvisionVSCodeOptions">
   <Expandable title="properties">
     <ParamField path="workspace" type="string">
-      Path to a workspace folder or `.code-workspace` file to open.
+      A folder or `.code-workspace` file in the sandbox to open.
     </ParamField>
-    
-    <ParamField path="extensions" type="string[]" default={[]}>
-      Array of VS Code extension IDs to install before launching.
+    <ParamField path="extensions" type="string[]" default="[]">
+      Marketplace extension IDs to install before VS Code opens.
     </ParamField>
   </Expandable>
 </ParamField>
 
 ```javascript
 await testdriver.provision.vscode({
-  workspace: '/home/testdriver/project',
-  extensions: ['ms-python.python', 'esbenp.prettier-vscode'],
+  workspace: '/tmp/my-project',
+  extensions: ['esbenp.prettier-vscode'],
 });
 ```
 
-### installer()
+## installer(options)
 
-Download and run an application installer. Supports `.msi`, `.exe`, `.deb`, `.rpm`, `.appimage`, `.sh`, `.dmg`, and `.pkg` formats.
+Downloads a file into the sandbox, installs it, and returns the downloaded file's path.
 
-```javascript
-await testdriver.provision.installer(options)
+```typescript
+testdriver.provision.installer(options: ProvisionInstallerOptions): Promise<string>
 ```
 
 <ParamField path="options" type="ProvisionInstallerOptions" required>
   <Expandable title="properties">
     <ParamField path="url" type="string" required>
-      Download URL for the installer.
+      Where to download the file from.
     </ParamField>
-    
     <ParamField path="filename" type="string">
-      Override the auto-detected filename from the URL.
+      The name to save the file as. By default, it comes from the download.
     </ParamField>
-    
     <ParamField path="appName" type="string">
-      Application name to focus after installation completes.
+      The app to bring to the front after installing.
     </ParamField>
-    
-    <ParamField path="launch" type="boolean" default={true}>
-      Whether to launch the app after installation. For a `.deb` on Linux, the app is started from its `.desktop` entry (or, when `appName` is set and there is no `.desktop` entry, from its `/usr/bin` binary) and then `appName` is focused. On Windows and macOS, `appName` is focused.
+    <ParamField path="launch" type="boolean" default="true">
+      Start the app after installing it.
+
+      - **`.deb` on Linux:** starts the app from its `.desktop` entry. If there isn't one and you set `appName`, it starts the package's first `/usr/bin` program.
+      - **`.sh` scripts:** runs the script.
+      - **Everywhere:** focuses `appName`, if you set it.
+
+      With `false`, packages are still installed, and a script is only made executable.
     </ParamField>
   </Expandable>
 </ParamField>
 
-**Behavior:**
-- Downloads the installer from the URL
-- Auto-detects the install method based on file extension
-- Runs the appropriate install command (e.g., `msiexec` for `.msi`, `dpkg` for `.deb`)
-- For `.deb` packages, installs any missing dependencies with `apt-get install -f` and fails if the package isn't fully installed
-- For `.deb` packages on Linux with `launch: true`, starts the app in the background
-- Focuses `appName` when it's set and `launch` is `true`
+TestDriver picks the install method from the file extension:
+
+| OS | Extension | What happens |
+| --- | --- | --- |
+| Windows | `.msi` | Installed quietly with `msiexec` |
+| Windows | `.exe` | Run with `/S` for a silent install |
+| Linux | `.deb` | Installed with `dpkg`. Missing dependencies are installed with `apt-get`, and the step fails if the package still isn't fully installed |
+| Linux | `.rpm` | Installed with `rpm` |
+| Linux | `.AppImage` | Made executable |
+| Linux | `.sh` | Made executable and run (only made executable with `launch: false`) |
+| macOS | `.dmg`, `.pkg` | Copied to Applications, or installed with `installer` |
+
+Other file types are downloaded but not installed.
 
 ```javascript
-// Windows MSI installer
+// Install bat, then check that it runs (bat has no window, so nothing is launched)
 await testdriver.provision.installer({
-  url: 'https://example.com/app-setup.msi',
-  appName: 'MyApp',
+  url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
 });
+const output = await testdriver.exec({ language: 'sh', code: 'bat --version' });
+console.log(output); // for example "bat 0.24.0"
+```
+
+Install a desktop app and start it:
 
-// Linux DEB package: installs dependencies, starts the app, focuses it
+```javascript
+// Installs Yaak and its dependencies, starts it, and brings its window to the front
 await testdriver.provision.installer({
-  url: 'https://example.com/app.deb',
-  appName: 'MyApp',
+  url: 'https://github.com/mountain-loop/yaak/releases/download/v2026.9.0/yaak_2026.9.0_amd64.deb',
+  appName: 'Yaak',
 });
 ```
 
-### electron()
+## electron(options)
 
-Launch an Electron application.
+Opens an Electron app that's already in the sandbox.
 
-```javascript
-await testdriver.provision.electron(options)
+```typescript
+testdriver.provision.electron(options: ProvisionElectronOptions): Promise<void>
 ```
 
 <ParamField path="options" type="ProvisionElectronOptions" required>
   <Expandable title="properties">
     <ParamField path="appPath" type="string" required>
-      Path to the Electron application directory or executable.
+      The path to the app in the sandbox. It throws if this is missing.
     </ParamField>
-    
-    <ParamField path="args" type="string[]" default={[]}>
-      Additional command-line arguments to pass to the Electron app.
+    <ParamField path="args" type="string[]" default="[]">
+      Extra command-line arguments for the app.
     </ParamField>
   </Expandable>
 </ParamField>
 
 ```javascript
-await testdriver.provision.electron({
-  appPath: '/home/testdriver/my-electron-app',
-  args: ['--no-sandbox'],
-});
+await testdriver.provision.electron({ appPath: '/tmp/my-electron-app', args: ['--no-sandbox'] });
 ```
 
-### dashcam()
+## dashcam(options)
 
-Start Dashcam recording with custom options. Usually called automatically by other provision methods, but can be called directly for custom configurations.
+Starts the Dashcam recording with your own settings. The other provision methods start it for you, so call this only to change the log file, the log name, or the recording's title.
 
-```javascript
-await testdriver.provision.dashcam(options?)
+```typescript
+testdriver.provision.dashcam(options?: ProvisionDashcamOptions): Promise<void>
 ```
 
 <ParamField path="options" type="ProvisionDashcamOptions">
   <Expandable title="properties">
     <ParamField path="logPath" type="string">
-      Path to the TestDriver log file. Defaults to `/tmp/testdriver.log` (Linux) or `C:\Users\testdriver\testdriver.log` (Windows).
+      A log file in the sandbox to include in the replay. Defaults to `/tmp/testdriver.log` on Linux, or `C:\Users\testdriver\testdriver.log` on Windows.
     </ParamField>
-    
     <ParamField path="logName" type="string" default="TestDriver Log">
-      Display name for the log file in the Dashcam replay.
+      The log's name in the replay.
     </ParamField>
-    
-    <ParamField path="webLogs" type="boolean" default={true}>
-      Enable web traffic log capture.
+    <ParamField path="webLogs" type="boolean" default="true">
+      Record network traffic. It covers the site opened with `chrome()`, or all traffic otherwise.
     </ParamField>
-    
     <ParamField path="title" type="string">
-      Recording title for the Dashcam session.
+      A title for the recording.
     </ParamField>
   </Expandable>
 </ParamField>
 
 ```javascript
-await testdriver.provision.dashcam({
-  title: 'Login Flow Test',
-  logPath: '/tmp/my-app.log',
-  logName: 'Application Log',
-  webLogs: true,
-});
+await testdriver.provision.dashcam({ title: 'Checkout flow', logPath: '/tmp/my-app.log', logName: 'App log' });
 ```
 
-## Types
+## Complete example
 
-```typescript
-interface ProvisionChromeOptions {
-  url?: string;                    // Default: "http://testdriver-sandbox.vercel.app/"
-  maximized?: boolean;             // Default: true
-  guest?: boolean;                 // Default: false
-}
-
-interface ProvisionChromeExtensionOptions {
-  extensionPath?: string;          // Local unpacked extension path
-  extensionId?: string;            // Chrome Web Store ID
-  maximized?: boolean;             // Default: true
-}
-
-interface ProvisionVSCodeOptions {
-  workspace?: string;              // Workspace path
-  extensions?: string[];           // Extension IDs to install
-}
-
-interface ProvisionInstallerOptions {
-  url: string;                     // Download URL (required)
-  filename?: string;               // Override filename
-  appName?: string;                // App name to focus
-  launch?: boolean;                // Default: true
-}
-
-interface ProvisionElectronOptions {
-  appPath: string;                 // Path to Electron app (required)
-  args?: string[];                 // Additional args
-}
-
-interface ProvisionDashcamOptions {
-  logPath?: string;                // Log file path
-  logName?: string;                // Default: "TestDriver Log"
-  webLogs?: boolean;               // Default: true
-  title?: string;                  // Recording title
-}
-```
-
-## Complete Example
+```javascript tests/extension.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-```javascript
-import { describe, it, beforeAll, afterAll } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('Chrome Extension Test', () => {
-  let testdriver;
+describe('Loom extension', () => {
+  it('appears in the extensions menu', async (context) => {
+    const testdriver = TestDriver(context);
 
-  beforeAll(async () => {
-    testdriver = new TestDriver({
-      os: 'linux',
-      resolution: '1920x1080',
-    });
-    
-    await testdriver.ready();
-    
-    // Install extension and open Chrome
     await testdriver.provision.chromeExtension({
-      extensionPath: './my-extension',
+      extensionId: 'liecbddmkiiihnedobmlmillhodjkdmb',
     });
-    
-    // Start Dashcam with custom logs
-    await testdriver.provision.dashcam({
-      title: 'Extension Test',
-      webLogs: true,
-    });
-  });
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+    await testdriver.find('puzzle-piece extensions icon in the Chrome toolbar').click();
 
-  it('tests the extension popup', async () => {
-    await testdriver.find('extension icon').click();
-    await testdriver.find('popup content').click();
+    const loom = await testdriver.find('Loom in the extensions dropdown');
+    expect(loom.found()).toBe(true);
   });
 });
 ```
+
+## Related
+
+- [Client & connection](/client): create and connect the client
+- [exec()](/exec): run commands in the sandbox, for example to fetch files before provisioning
+- [Dashcam](/dashcam): how runs are recorded
+- [Examples](/examples/installer): complete tests that install and launch apps

package/docs/quickstart-claude.mdx

@@ -0,0 +1,85 @@
+---
+title: "Add TestDriver to Claude Code"
+sidebarTitle: "Claude Code"
+description: "Install one plugin to get the TestDriver MCP server, agent, and skills in Claude Code."
+icon: "terminal"
+---
+
+Install the TestDriver plugin, and Claude Code can write, run, and debug end-to-end tests in a live sandbox.
+
+The plugin bundles three things:
+
+- The TestDriver MCP server
+- The `testdriver` agent, which builds tests step by step
+- Skills that teach Claude the TestDriver SDK
+
+## Before you begin
+
+- **[Claude Code](https://code.claude.com)** and **Node.js 20.19 or later**, which runs the MCP server.
+- **A TestDriver API key.** Create one at [console.testdriver.ai/team/api-keys](https://console.testdriver.ai/team/api-keys).
+- **A project with the TestDriver SDK installed**, so the agent can run the tests it writes. If you don't have one yet, see [Set up a project](/quickstart-manual).
+
+<Steps>
+  <Step title="Set your API key">
+
+    The plugin's MCP server reads your key from the `TD_API_KEY` environment variable. Add it to your shell profile (such as `~/.zshrc`) so every Claude Code session can use it:
+
+    ```bash
+    export TD_API_KEY="your_api_key"
+    ```
+
+    Open a new terminal, or run `source ~/.zshrc`, before you start Claude Code.
+
+  </Step>
+  <Step title="Install the plugin">
+
+    TestDriver is a community plugin. In Claude Code, run `/plugin`, open the **Discover** tab, search for **TestDriver**, and install it.
+
+    You can also install it from TestDriver's own marketplace:
+
+    ```text
+    /plugin marketplace add testdriverai/testdriverai
+    /plugin install testdriver@testdriver
+    ```
+
+  </Step>
+  <Step title="Check the connection">
+
+    Run `/mcp` in Claude Code. The `testdriver` server should be listed as connected.
+
+    If it isn't, check that `TD_API_KEY` is set in the terminal you started Claude Code from.
+
+  </Step>
+  <Step title="Write your first test">
+
+    Ask for the TestDriver agent by name:
+
+    ```text
+    Use the testdriver agent to write a test that logs in to https://testdriver-sandbox.vercel.app/login and adds an item to the cart.
+    ```
+
+    The agent starts a sandbox and performs each step. It writes the code into a test file under `tests/`, then runs it with Vitest until it passes.
+
+  </Step>
+</Steps>
+
+<Tip>
+  Only need TestDriver's tools in chat, without the agent or skills? Add the hosted server instead. It signs in through your browser and needs no API key. See [MCP Setup](/mcp-setup).
+</Tip>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Generate tests with AI" icon="compass" href="/generating-tests">
+    Prompt the agent and steer it while it works.
+  </Card>
+  <Card title="Make assertions" icon="circle-check" href="/making-assertions">
+    Check what's on screen in plain language.
+  </Card>
+  <Card title="Run tests" icon="play" href="/copilot/running-tests">
+    Run your tests locally and choose a device.
+  </Card>
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Run your tests on every pull request.
+  </Card>
+</CardGroup>

package/docs/quickstart-github.mdx

@@ -1,54 +1,84 @@
 ---
 title: "Add TestDriver to GitHub"
 sidebarTitle: "Add to GitHub"
-description: "Drop-in UI tests for any GitHub repository."
+description: "Get an AI code review on every pull request, backed by a real run of your app."
 icon: "github"
 ---
 
-Drop-in UI tests for any GitHub repository. Mention `@testdriverai` in a pull request or issue and it writes, runs, and commits UI tests, then catches regressions before they merge. No local install required.
+Install the TestDriver GitHub app, and the TestDriver agent reviews every pull request in your repository.
 
-<Card
-  title="Add to GitHub"
-  icon="github"
-  href="https://go.testdriver.ai/github"
-  arrow
-  horizontal
->
-  Install the TestDriver GitHub App and start testing in minutes.
-</Card>
+- It reads the diff for bugs.
+- When a user would see the change, it runs your app in a real sandbox to prove what it finds.
+- It writes and maintains end-to-end tests whenever you ask.
+
+There's nothing to install locally.
+
+## Before you begin
+
+- **A GitHub repository** where you can install apps (you own it, or you're an admin of its organization).
+- **A TestDriver account.** You create one or sign in during installation.
+- **A paid plan or trial for automatic reviews.** On the free plan, the agent still reviews a pull request when you @mention it. See [pricing](https://testdriver.ai/pricing).
 
 <Steps>
-  <Step title="Install the GitHub App">
-    Click **Add to GitHub** above and choose the repositories you want to test. You can add more repositories later from your GitHub organization settings.
+  <Step title="Install the GitHub app">
+
+    Open [TestDriver on GitHub](https://go.testdriver.ai/github). Install the app on the repositories you want reviewed, and sign in to TestDriver when prompted.
+
+    You can add more repositories later from your GitHub settings.
+
+  </Step>
+  <Step title="Get your first tests">
+
+    Choose a repository to set up. TestDriver opens a **Set up TestDriver** issue in it.
+
+    The agent picks up the issue, writes a few sample tests for your app, and runs them. It opens a pull request with the tests and their recordings. Review it and merge it like any other pull request.
+
   </Step>
+  <Step title="Open a pull request">
 
-  <Step title="Mention @testdriverai">
-    Open a pull request or an issue and describe the test you want in a comment:
+    From now on, every pull request you open gets a review without anyone asking. The agent reads the change and runs it when there's something to drive.
+
+    It posts a single review comment with:
+
+    - A summary
+    - A walkthrough of the changed files
+    - Any bugs it found, each labelled `observed` (seen during a run) or `suspected` (inferred from the code)
+
+    Pushing new commits triggers a fresh review.
+
+    The review is a comment, so it never approves or blocks a merge. To fail a pull request when a test breaks, [run your tests in CI](/ci-cd).
+
+  </Step>
+  <Step title="Ask for more with @testdriverai">
+
+    Mention the agent on any issue or pull request to ask a follow-up question or request a new test:
 
     ```text
-    @testdriverai Write a test that verifies the homepage loads and the signup button works.
+    @testdriverai Write a test that logs in, adds the first product to the cart, and confirms the cart badge shows 1.
     ```
 
-    TestDriver replies in the thread, starts a sandbox, writes the test, runs it, and posts the result with a link to the recording. It then opens a pull request that adds the test file to your repository.
+    The agent replies in the thread and posts screenshots as it works. When it's done, it opens a pull request with the test.
 
     <Tip>
-    Describe what a user does and what they should see, not implementation details. "Log in, add the first product to the cart, and confirm the cart badge shows 1" gives better results than "click `#add-btn`".
+      Describe what a user does and what they should see, not how the page is built. "Confirm the cart badge shows 1" works better than "check `#cart-count`".
     </Tip>
-  </Step>
 
-  <Step title="Catch regressions automatically">
-    Once tests are committed, TestDriver runs them on every pull request that changes something a user would see and posts a review with what it observed, including a recording. Mention `@testdriverai` on any PR to ask follow-up questions or request more tests.
   </Step>
 </Steps>
 
-Want to use TestDriver from GitHub Copilot or the GitHub Mobile app? Read the full GitHub guide:
-
-<Card
-  title="GitHub Integration Guide"
-  icon="arrow-right"
-  href="/copilot/auto-healing#use-testdriver-in-github"
-  arrow
-  horizontal
->
-  Use TestDriver from GitHub web, Copilot chat, PR reviews, and mobile.
-</Card>
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="How the agent works" icon="hand-horns" href="/agent">
+    What the agent does on pull requests, issues, and mentions.
+  </Card>
+  <Card title="Prevent regressions" icon="shield-check" href="/copilot/auto-healing">
+    Run tests in CI and have the agent fix them when your app changes.
+  </Card>
+  <Card title="Run tests in CI/CD" icon="code-branch" href="/ci-cd">
+    Run your TestDriver tests in GitHub Actions.
+  </Card>
+  <Card title="Set up a project" icon="wrench" href="/quickstart-manual">
+    Write and run tests yourself in your own repository.
+  </Card>
+</CardGroup>