@testdriverai/agent 7.11.239-test → 7.11.241-canary

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

@@ -1,311 +1,267 @@
 ---
 name: testdriver:provision
-description: Launch browsers, desktop apps, and extensions in your sandbox
+description: Start Chrome, a Chrome extension, VS Code, an Electron app, or an installer in the sandbox.
 ---
 <!-- Generated from provision.mdx. DO NOT EDIT. -->
 
-## 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 focus/launch the app after installation.
+    <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`)
-- Optionally focuses the installed application
+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
+```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',
-  launch: true,
+  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/ai/skills/testdriver-quickstart/SKILL.md

@@ -1,21 +1,37 @@
 ---
 name: testdriver:quickstart
-description: Run your first computer-use test in minutes.
+description: Start with TestDriver from GitHub, Claude Code, VS Code, Cursor, any MCP client, or your own project.
 ---
 <!-- Generated from quickstart.mdx. DO NOT EDIT. -->
 
-TestDriver writes and runs computer-use tests for web apps, desktop apps, and browser extensions. Tests describe what a user sees and does in plain English, and run on real machines in the cloud. Pick the path that fits how you work:
+TestDriver writes and runs end-to-end tests for web apps, desktop apps, and browser extensions.
+
+Each test describes what a user sees and does in plain language. It runs on a real machine in the cloud.
+
+Choose where you want to start:
 
 <CardGroup cols={1}>
   <Card title="Add to GitHub" icon="github" href="/quickstart-github" arrow horizontal>
-    No install. Mention `@testdriverai` in a PR or issue and it writes, runs, and commits tests for you.
+    An AI code reviewer that tests every pull request in a real sandbox.
+  </Card>
+  <Card title="Claude Code" icon="terminal" href="/quickstart-claude" arrow horizontal>
+    Install the plugin to write and run tests from Claude Code.
   </Card>
-  <Card title="MCP Setup" icon="plug" href="/mcp-setup" arrow horizontal>
-    Add one URL to Claude, Cursor, VS Code, ChatGPT, or any MCP client. No install, no API key.
+  <Card title="VS Code & Cursor" icon="code" href="/quickstart-vscode" arrow horizontal>
+    Install the extension to write tests and watch them run live.
   </Card>
-  <Card title="Manual" icon="wrench" href="/quickstart-manual" arrow horizontal>
-    Add TestDriver to an existing Vitest project file by file.
+  <Card title="Connect your AI client" icon="plug" href="/mcp-setup" arrow horizontal>
+    Add one URL to any MCP client, such as Claude or ChatGPT.
+  </Card>
+  <Card title="Set up a project" icon="wrench" href="/quickstart-manual" arrow horizontal>
+    Write and run Vitest tests in your own repository.
   </Card>
 </CardGroup>
 
-<Tip><a href="https://discord.com/invite/cWDFW8DzPm" target="_blank" rel="noreferrer">Join our Discord</a> if you have questions or get stuck.</Tip>
+Not sure? Start with GitHub. Your next pull request gets a review without any setup.
+
+Set up a project when you want to write and run tests yourself.
+
+<Tip>
+  Questions along the way? Ask in the [TestDriver Discord](https://discord.com/invite/cWDFW8DzPm).
+</Tip>

package/ai/skills/testdriver-quickstart-claude/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: testdriver:quickstart-claude
+description: Install one plugin to get the TestDriver MCP server, agent, and skills in Claude Code.
+---
+<!-- Generated from quickstart-claude.mdx. DO NOT EDIT. -->
+
+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>