testdriverai 7.8.0-test.8 → 7.8.0

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

@@ -10,7 +10,7 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
 <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="Automatic Setup">
+  <Tab title="CLI" icon="terminal">
 
     Get started quickly with the TestDriver CLI.
 
@@ -40,7 +40,35 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
       </Step>
     </Steps>
   </Tab>
-  <Tab title="Manual Setup">
+  <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.
 

package/docs/v7/redraw.mdx

@@ -0,0 +1,216 @@
+---
+title: "Redraw"
+sidebarTitle: "Redraw"
+description: "Wait for the screen to stabilize after interactions"
+icon: "rotate"
+mode: "wide"
+---
+
+## Overview
+
+The redraw system waits for the screen to stabilize after an interaction before continuing. It detects when animations, page loads, and network requests have settled, preventing actions from being performed on a changing screen.
+
+<Note>
+  **Redraw is disabled by default since v7.3.** Enable it explicitly if your tests interact with applications that have significant animations or loading states.
+</Note>
+
+## How It Works
+
+Redraw uses a **two-phase detection** approach:
+
+1. **Change Detection** — Compare the current frame to the initial screenshot taken right after the action. If the pixel diff exceeds 0.1%, the screen has changed.
+2. **Stability Detection** — Compare consecutive frames using z-score analysis. When the diff between frames drops below 0.1% or the z-score is negative (current diff is below average), the screen has settled.
+
+The screen is considered **settled** when both phases complete: the screen changed from the initial state AND consecutive frames are now stable.
+
+```mermaid
+flowchart TD
+    A[Action performed] --> B{Phase 1: Change Detection\ndiffFromInitial > 0.1%?}
+    B -- "Yes (screen changed)" --> C{Phase 2: Stability\nz-score < 0 or\ndiffPercent < 0.1%?}
+    C -- "Yes (frames stable)" --> D[Screen settled ✓]
+    B -- "No (waiting...)" --> B
+    C -- "No (waiting...)" --> C
+```
+
+### Polling
+
+The system polls at **500ms intervals**, comparing screenshot frames. This reduces WebSocket traffic while still providing responsive detection.
+
+### Pixel Comparison
+
+Uses [pixelmatch](https://github.com/mapbox/pixelmatch) for per-pixel comparison with a threshold of `0.1` for pixel sensitivity. A frame diff above **0.1% of total pixels** indicates the screen has changed.
+
+### Z-Score Analysis
+
+Screen stability uses statistical analysis of the last **10 measurements**:
+
+1. Calculate the mean and standard deviation of consecutive frame diffs
+2. Compute the z-score: `(currentDiff - mean) / stddev`
+3. Screen is stable when `diffPercent < 0.1%` or `z-score < 0` (current diff is below the average)
+
+This approach adapts to the specific animation patterns of your application rather than using a fixed threshold.
+
+## Per-Command Timeouts
+
+Each command type has a specific redraw timeout:
+
+| Command | Timeout | Reason |
+|---------|---------|--------|
+| `click` | 5000ms | Page navigations, modal openings |
+| `hover` (within click) | 5000ms | Same as click |
+| `hover` (standalone) | 2500ms | Tooltip animations |
+| `scroll` | 5000ms | Lazy-loaded content |
+| `type` | 5000ms | Autocomplete, validation |
+| `pressKeys` | 5000ms | Keyboard shortcuts may trigger changes |
+| `focusApplication` | 1000ms | Window focus animations |
+
+If the timeout is reached before the screen settles, the command continues anyway. The timeout event is available via the `redraw:complete` event.
+
+## Configuration
+
+### Constructor Options
+
+```javascript
+const testdriver = new TestDriver({
+  // Shorthand: enable/disable
+  redraw: true,    // enable with defaults
+  redraw: false,   // disable (default since v7.3)
+
+  // Full configuration
+  redraw: {
+    enabled: true,
+    screenRedraw: true,       // enable screen pixel diff detection
+    networkMonitor: false,    // enable network settling detection
+  },
+});
+```
+
+<ParamField path="redraw" type="RedrawConfig | boolean" default={false}>
+  Redraw configuration. Pass `true`/`false` for shorthand, or an object for fine-grained control.
+
+  <Expandable title="properties">
+    <ParamField path="enabled" type="boolean" default={false}>
+      Enable or disable the redraw system. Default changed to `false` in v7.3.
+    </ParamField>
+    
+    <ParamField path="screenRedraw" type="boolean" default={true}>
+      Enable pixel-diff-based screen change detection. If both `screenRedraw` and `networkMonitor` are `false`, redraw auto-disables.
+    </ParamField>
+    
+    <ParamField path="networkMonitor" type="boolean" default={false}>
+      Enable network traffic monitoring for settling detection. Monitors WebSocket traffic on the sandbox to detect when network activity subsides.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Per-Command Override
+
+Override redraw settings for individual commands:
+
+```javascript
+// Enable redraw for a specific click
+await testdriver.find('load more').click({
+  redraw: { enabled: true },
+});
+
+// Disable redraw for a fast interaction
+await testdriver.find('checkbox').click({
+  redraw: false,
+});
+```
+
+## Network Settling
+
+When `networkMonitor` is enabled, the system also monitors sandbox network traffic:
+
+- Polls for `totalBytesReceived` and `totalBytesSent` from the sandbox
+- Keeps the last **60 measurements**
+- Calculates z-scores for both RX and TX byte rates
+- Network is **settled** when both RX and TX z-scores are negative (traffic is below average)
+- Has a **10-second timeout** for network polling
+- Non-critical: network errors are logged but never throw
+
+The final settling condition requires **both** screen AND network to be settled (when both are enabled).
+
+## Events
+
+The redraw system emits events through the SDK emitter. See [Events](/v7/events) for the full event reference.
+
+| Event | Description |
+|---|---|
+| `redraw:status` | Emitted on each poll with current screen diff, network stats, and timeout info |
+| `redraw:complete` | Emitted when redraw resolves (settled or timed out) |
+
+```javascript
+testdriver.emitter.on('redraw:status', (status) => {
+  console.log(`Screen: ${status.redraw.text}`);
+  console.log(`Network: ${status.network.text}`);
+  console.log(`Timeout: ${status.timeout.text}`);
+});
+
+testdriver.emitter.on('redraw:complete', (result) => {
+  if (result.isTimeout) {
+    console.warn(`Redraw timed out after ${result.timeElapsed}ms`);
+  } else {
+    console.log(`Screen settled in ${result.timeElapsed}ms`);
+  }
+});
+```
+
+## When to Use Redraw
+
+**Enable redraw when:**
+- Testing single-page applications (SPAs) with route transitions
+- Interacting with pages that lazy-load content on scroll
+- Clicking buttons that trigger animations or modals
+- Testing apps with significant network-driven UI updates
+
+**Keep redraw disabled when:**
+- Tests are already stable without it
+- You want faster test execution
+- Your application has minimal animations
+- You're using explicit waits or assertions instead
+
+## Types
+
+```typescript
+interface RedrawConfig {
+  enabled?: boolean;              // Default: false (since v7.3)
+  screenRedraw?: boolean;         // Default: true
+  networkMonitor?: boolean;       // Default: false
+}
+
+interface RedrawStatusEvent {
+  redraw: {
+    enabled: boolean;
+    settled: boolean;
+    hasChangedFromInitial: boolean;
+    consecutiveFramesStable: number;
+    diffFromInitial: number;
+    diffFromLast: number;
+    text: string;
+  };
+  network: {
+    enabled: boolean;
+    settled: boolean;
+    rxBytes: number;
+    txBytes: number;
+    text: string;
+  };
+  timeout: {
+    isTimeout: boolean;
+    elapsed: number;
+    max: number;
+    text: string;
+  };
+}
+
+interface RedrawCompleteEvent {
+  screenSettled: boolean;
+  hasChangedFromInitial: boolean;
+  consecutiveFramesStable: number;
+  networkSettled: boolean;
+  isTimeout: boolean;
+  timeElapsed: number;
+}
+```

package/docs/v7/running-tests.mdx

@@ -133,7 +133,7 @@ export default defineConfig({
 <Card
   title="View Plans & Pricing"
   icon="credit-card"
-  href="/v7/cloud"
+  href="/v7/hosted"
 >
   Compare plans and find the right level of parallelization for your team.
 </Card>