@testdriverai/agent 7.8.0-canary.10

package/docs/v7/provision.mdx

@@ -0,0 +1,333 @@
+---
+title: "Provision"
+sidebarTitle: "Provision"
+description: "Launch browsers, desktop apps, and extensions in your sandbox"
+icon: "rocket"
+mode: "wide"
+---
+
+## Overview
+
+The Provision API sets up applications in your sandbox before tests run. It handles downloading, installing, and launching browsers, desktop apps, VS Code, Chrome extensions, and more.
+
+Access provision methods via `testdriver.provision.*`:
+
+```javascript
+await testdriver.provision.chrome({ url: 'https://example.com' });
+```
+
+<Note>
+  When `reconnect: true` is set on the client, **all provision methods are skipped** since the application is assumed to already be running.
+</Note>
+
+## Methods
+
+### chrome()
+
+Launch Google Chrome with an optional URL.
+
+```javascript
+await testdriver.provision.chrome(options?)
+```
+
+<ParamField path="options" type="ProvisionChromeOptions">
+  <Expandable title="properties">
+    <ParamField path="url" type="string" default="http://testdriver-sandbox.vercel.app/">
+      URL to navigate to after launch.
+    </ParamField>
+    
+    <ParamField path="maximized" type="boolean" default={true}>
+      Launch Chrome in maximized window mode.
+    </ParamField>
+    
+    <ParamField path="guest" type="boolean" default={false}>
+      Launch Chrome in guest profile mode.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```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,
+});
+```
+
+### chromeExtension()
+
+Install and launch a Chrome extension. You can install from a local unpacked directory or from the Chrome Web Store by extension ID.
+
+```javascript
+await testdriver.provision.chromeExtension(options)
+```
+
+<ParamField path="options" type="ProvisionChromeExtensionOptions" required>
+  One of `extensionPath` or `extensionId` is required.
+
+  <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.
+    </ParamField>
+    
+    <ParamField path="maximized" type="boolean" default={true}>
+      Launch Chrome in maximized window mode.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+// From local directory
+await testdriver.provision.chromeExtension({
+  extensionPath: './my-extension',
+});
+
+// From Chrome Web Store
+await testdriver.provision.chromeExtension({
+  extensionId: 'abcdefghijklmnop',
+});
+```
+
+### vscode()
+
+Launch Visual Studio Code with an optional workspace and extensions.
+
+```javascript
+await testdriver.provision.vscode(options?)
+```
+
+<ParamField path="options" type="ProvisionVSCodeOptions">
+  <Expandable title="properties">
+    <ParamField path="workspace" type="string">
+      Path to a workspace folder or `.code-workspace` file to open.
+    </ParamField>
+    
+    <ParamField path="extensions" type="string[]" default={[]}>
+      Array of VS Code extension IDs to install before launching.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+await testdriver.provision.vscode({
+  workspace: '/home/testdriver/project',
+  extensions: ['ms-python.python', 'esbenp.prettier-vscode'],
+});
+```
+
+### installer()
+
+Download and run an application installer. Supports `.msi`, `.exe`, `.deb`, `.rpm`, `.appimage`, `.sh`, `.dmg`, and `.pkg` formats.
+
+```javascript
+await testdriver.provision.installer(options)
+```
+
+<ParamField path="options" type="ProvisionInstallerOptions" required>
+  <Expandable title="properties">
+    <ParamField path="url" type="string" required>
+      Download URL for the installer.
+    </ParamField>
+    
+    <ParamField path="filename" type="string">
+      Override the auto-detected filename from the URL.
+    </ParamField>
+    
+    <ParamField path="appName" type="string">
+      Application name to focus after installation completes.
+    </ParamField>
+    
+    <ParamField path="launch" type="boolean" default={true}>
+      Whether to focus/launch the app after installation.
+    </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
+
+```javascript
+// Windows MSI installer
+await testdriver.provision.installer({
+  url: 'https://example.com/app-setup.msi',
+  appName: 'MyApp',
+});
+
+// Linux DEB package
+await testdriver.provision.installer({
+  url: 'https://example.com/app.deb',
+  appName: 'MyApp',
+  launch: true,
+});
+```
+
+### electron()
+
+Launch an Electron application.
+
+```javascript
+await testdriver.provision.electron(options)
+```
+
+<ParamField path="options" type="ProvisionElectronOptions" required>
+  <Expandable title="properties">
+    <ParamField path="appPath" type="string" required>
+      Path to the Electron application directory or executable.
+    </ParamField>
+    
+    <ParamField path="args" type="string[]" default={[]}>
+      Additional command-line arguments to pass to the Electron app.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+await testdriver.provision.electron({
+  appPath: '/home/testdriver/my-electron-app',
+  args: ['--no-sandbox'],
+});
+```
+
+### dashcam()
+
+Start Dashcam recording with custom options. Usually called automatically by other provision methods, but can be called directly for custom configurations.
+
+```javascript
+await testdriver.provision.dashcam(options?)
+```
+
+<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).
+    </ParamField>
+    
+    <ParamField path="logName" type="string" default="TestDriver Log">
+      Display name for the log file in the Dashcam replay.
+    </ParamField>
+    
+    <ParamField path="webLogs" type="boolean" default={true}>
+      Enable web traffic log capture.
+    </ParamField>
+    
+    <ParamField path="title" type="string">
+      Recording title for the Dashcam session.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+```javascript
+await testdriver.provision.dashcam({
+  title: 'Login Flow Test',
+  logPath: '/tmp/my-app.log',
+  logName: 'Application Log',
+  webLogs: true,
+});
+```
+
+## Reconnect Behavior
+
+When `reconnect: true` is set on the client, all provision methods are wrapped in a Proxy that intercepts calls and skips them silently. This is because when reconnecting to an existing sandbox, the applications are already running.
+
+```javascript
+const testdriver = new TestDriver({
+  reconnect: true,
+});
+
+await testdriver.ready();
+
+// These calls are silently skipped:
+await testdriver.provision.chrome({ url: 'https://example.com' });
+await testdriver.provision.dashcam();
+```
+
+## Types
+
+```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
+import { describe, it, beforeAll, afterAll } from 'vitest';
+import TestDriver from 'testdriverai';
+
+describe('Chrome Extension Test', () => {
+  let testdriver;
+
+  beforeAll(async () => {
+    testdriver = new TestDriver({
+      os: 'linux',
+      resolution: '1920x1080',
+    });
+    
+    await testdriver.ready();
+    
+    // Install extension and open Chrome
+    await testdriver.provision.chromeExtension({
+      extensionPath: './my-extension',
+    });
+    
+    // Start Dashcam with custom logs
+    await testdriver.provision.dashcam({
+      title: 'Extension Test',
+      webLogs: true,
+    });
+  });
+
+  afterAll(async () => {
+    await testdriver.disconnect();
+  });
+
+  it('tests the extension popup', async () => {
+    await testdriver.find('extension icon').click();
+    await testdriver.find('popup content').click();
+  });
+});
+```

package/docs/v7/quickstart.mdx

@@ -0,0 +1,173 @@
+---
+title: "Quick Start"
+sidebarTitle: "Quickstart"
+description: "Run your first computer-use test in minutes."
+icon: "rocket"
+---
+
+TestDriver makes it easy to write automated computer-use tests for web browsers, desktop apps, and more. Follow the directions below to run your first TestDriver test.
+
+<Tip><a href="https://discord.com/invite/cWDFW8DzPm" target="_blank" rel="noreferrer">Join our Discord</a> if you have any questions or need help getting started!</Tip>
+
+<Tabs>
+  <Tab title="CLI" icon="terminal">
+
+    Get started quickly with the TestDriver CLI.
+
+    <Steps>
+      <Step title="Install TestDriver">
+
+        Use `npx` to quickly set up an example project:
+
+        ```bash
+        npx testdriverai init
+        ```
+
+        This will walk you through creating a new project folder, installing dependencies, setting up your API key, and configuring MCP for your preferred AI assistant (VS Code, Cursor, Claude Desktop, etc.).
+
+      </Step>
+      
+      <Step title="Run Your Test">
+
+        TestDriver uses Vitest as the test runner. To run your test, use:
+        
+        ```bash
+        vitest run
+        ```
+
+        This will spawn a sandbox, launch Chrome, and run the example test!
+
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="GitHub Copilot" icon="github">
+
+    Use the TestDriver VS Code extension with GitHub Copilot for an AI-powered testing workflow.
+
+    <Card
+      title="Install TestDriver for VS Code"
+      icon="/images/content/extension/vscode.svg"
+      href="vscode:extension/testdriver.testdriver"
+      arrow
+      horizontal
+    >
+    </Card>
+
+    The extension provides one-click sign-in, project initialization, a live preview panel for watching tests execute, and MCP server configuration for GitHub Copilot.
+
+    Once installed, follow the full setup guide to configure MCP and start building tests with AI assistance:
+
+    <Card
+      title="VS Code + Copilot Setup Guide"
+      icon="arrow-right"
+      href="/v7/copilot/setup"
+      arrow
+      horizontal
+    >
+      Sign in, initialize your project, and configure MCP for GitHub Copilot.
+    </Card>
+
+  </Tab>
+  <Tab title="Manual" icon="wrench">
+
+    Install TestDriver and manually create the files yourself.
+
+    <Steps>
+      <Step title="Create a TestDriver Account">
+
+        You will need a TestDriver account to get an API key.
+
+        <Card
+          title="Get an API Key"
+          icon="user-plus"
+          href="https://console.testdriver.ai/team"
+          arrow
+          horizontal
+        >
+          Start with 60 free device minutes, no credit-card required!
+        </Card>
+
+      </Step>
+      <Step title="Install Dependencies">
+
+        Install Vitest and TestDriver as dev dependencies:
+
+        ```bash
+        npm install --save-dev vitest testdriverai
+        ```
+
+      </Step>
+      <Step title="Create a vitest.config.js File">
+
+        In your project root, create a `vitest.config.js` file with the following content:
+
+        ```js vitest.config.js
+        import TestDriver from 'testdriverai/vitest';
+        import { defineConfig } from 'vitest/config';
+
+        export default defineConfig({
+          test: {
+            testTimeout: 900000,
+            hookTimeout: 900000,
+            reporters: [
+              'default',
+              TestDriver()
+            ],
+            setupFiles: ['testdriverai/vitest/setup'],
+          },
+        });
+        ```
+
+      </Step>
+      <Step title="Create an Example Test File">
+
+        Add your API key to the example test file below and save it as `test.mjs` in your project root.
+
+        ```js test.mjs highlight={9}
+        import { describe, expect, it } from "vitest";
+        // Import TestDriver from the vitest hooks
+        import { TestDriver } from "testdriverai/vitest/hooks";
+
+        describe("Google Search Example", () => {
+          it("should search for TestDriver", async (context) => {
+            // Create TestDriver instance - automatically connects to sandbox
+            const testdriver = TestDriver(context, {
+              apiKey: 'YOUR_API_KEY_HERE' // supply your API key here 
+            });
+
+            // Provision Chrome browser with a URL
+            // This also starts dashcam recording automatically
+            await testdriver.provision.chrome({ url: "https://duckduckgo.com" });
+
+            // Find and interact with elements using natural language
+            const searchBox = await testdriver.find("DuckDuckGo search input field");
+            await searchBox.click();
+
+            // Type into the focused element
+            await testdriver.type("testdriver.ai");
+
+            // Press Enter to search
+            await testdriver.pressKeys(["enter"]);
+
+            // Assert something is visible on the page
+            const result = await testdriver.assert("search results are displayed");
+            expect(result).toBeTruthy();
+          });
+        });
+        ```
+
+      </Step>
+      <Step title="Run Your Test">
+
+        TestDriver uses Vitest as the test runner. To run your test, use:
+        
+        ```bash
+        vitest run
+        ```
+
+        This will spawn a sandbox, launch Chrome, and run the example test!
+
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>