testdriverai 7.2.2 → 7.2.3

package/docs/docs.json

@@ -192,15 +192,8 @@
   "groups": [
     {
       "group": "Getting Started",
-      "icon": "rocket",
-      "pages": [
-        "/v7/getting-started/quickstart"
-      ]
-    },
-    {
-      "group": "Guides",
-      "icon": "book",
       "pages": [
+        "/v7/getting-started/quickstart",
         "/v7/getting-started/writing-tests",
         "/v7/getting-started/running-tests",
         "/v7/getting-started/debugging-tests",
@@ -209,7 +202,6 @@
     },
     {
       "group": "Examples",
-      "icon": "code",
       "pages": [
         "/v7/presets/chrome",
         "/v7/presets/chrome-extension",
@@ -218,8 +210,7 @@
       ]
     },
     {
-      "group": "Features",
-      "icon": "layer-group",
+      "group": "Guides",
       "pages": [
         {
           "group": "Selectorless Testing",

package/docs/v7/_drafts/provision.mdx

@@ -1,266 +1,329 @@
 # Provision API
 
-The `provision()` function is the easiest way to set up TestDriver for common applications. It automatically handles TestDriver initialization, application launching, and Dashcam recording.
+The `provision` object provides easy setup methods for common applications. These methods automatically handle TestDriver initialization, Dashcam recording, and application launching.
 
 ## Quick Start
 
 ```javascript
-import { test } from 'vitest';
-import { provision } from 'testdriverai/presets';
+import { describe, it, expect } from 'vitest';
+import { TestDriver } from 'testdriverai/lib/vitest/hooks.mjs';
 
-test('my test', async (context) => {
-  const { testdriver } = await provision('chrome', {
-    url: 'https://example.com'
-  }, context);
-  
-  await testdriver.find('Login button').click();
+describe('My Test Suite', () => {
+  it('should test Chrome browser', async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.chrome({
+      url: 'https://example.com'
+    });
+    
+    await testdriver.find('Login button').click();
+  });
 });
 ```
 
-## API
-
-```typescript
-provision(appType, options, context)
-```
+## Available Methods
 
-**Parameters:**
-- `appType` - Application type: `'chrome'`, `'vscode'`, `'electron'`, or `'webapp'`
-- `options` - Configuration options (varies by app type)
-- `context` - Vitest test context (from your test function parameter)
+- `provision.chrome()` - Launch Chrome browser with URL
+- `provision.vscode()` - Launch VS Code with optional extensions
+- `provision.installer()` - Download and install applications
+- `provision.electron()` - Launch Electron applications
 
-**Returns:**
-- `testdriver` - TestDriver instance ready to use
-- `dashcam` - Dashcam instance (if enabled)
-- Additional app-specific properties (like `vscode`, `app`)
+---
 
-## Application Types
+## provision.chrome()
 
-### Chrome Browser
+Launch Google Chrome with automatic Dashcam recording.
 
 ```javascript
-const { testdriver } = await provision('chrome', {
+await testdriver.provision.chrome({
   url: 'https://myapp.com',
-  maximized: true,      // Start maximized (default: true)
-  guest: true,          // Use guest mode (default: true)
-  dashcam: true,        // Enable Dashcam (default: true)
-  os: 'linux'          // Target OS (default: 'linux')
-}, context);
-
-await testdriver.find('username').type('user@example.com');
-await testdriver.find('Login').click();
+  maximized: true,
+  extensionPath: '/path/to/extension'
+});
 ```
 
 **Options:**
-- `url` - URL to navigate to (default: 'http://testdriver-sandbox.vercel.app/')
-- `maximized` - Start browser maximized (default: `true`)
-- `guest` - Use guest/incognito mode (default: `true`)
-- `dashcam` - Enable Dashcam recording (default: `true`)
-- `os` - Target OS: `'linux'`, `'mac'`, or `'windows'` (default: `'linux'`)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | `'http://testdriver-sandbox.vercel.app/'` | URL to navigate to |
+| `maximized` | boolean | `true` | Start browser maximized |
+| `extensionPath` | string | - | Path to Chrome extension to load |
 
-**Returns:**
-- `testdriver` - TestDriver instance
-- `dashcam` - Dashcam instance (if enabled)
-
-### VS Code
+**Example:**
 
 ```javascript
-const { testdriver, vscode } = await provision('vscode', {
-  workspace: '/path/to/project',
-  extensions: ['ms-python.python'],
-  dashcam: true,
-  os: 'linux'
-}, context);
-
-await vscode.find('File menu').click();
-await vscode.find('New File').click();
+it('should login to my app', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  
+  await testdriver.provision.chrome({
+    url: 'https://myapp.com/login'
+  });
+  
+  await testdriver.find('email input').type('user@example.com');
+  await testdriver.find('password input').type('password123');
+  await testdriver.find('Login button').click();
+  
+  const result = await testdriver.assert('Dashboard is visible');
+  expect(result).toBeTruthy();
+});
 ```
 
-**Options:**
-- `workspace` - Workspace/folder path to open (optional)
-- `extensions` - Array of extension IDs to install (optional)
-- `dashcam` - Enable Dashcam recording (default: `true`)
-- `os` - Target OS (default: `'linux'`)
+---
 
-**Returns:**
-- `testdriver` - TestDriver instance
-- `vscode` - Alias for testdriver (semantic clarity)
-- `dashcam` - Dashcam instance (if enabled)
+## provision.vscode()
 
-### Electron
+Launch Visual Studio Code with optional extension installation. Automatically starts Dashcam recording.
 
 ```javascript
-const { testdriver, app } = await provision('electron', {
-  appPath: '/path/to/app',
-  args: ['--enable-logging'],
-  dashcam: true,
-  os: 'linux'
-}, context);
-
-await app.find('main window').click();
+await testdriver.provision.vscode({
+  workspace: '/path/to/project',
+  extensions: ['esbenp.prettier-vscode', 'ms-python.python']
+});
 ```
 
 **Options:**
-- `appPath` - Path to Electron application (required)
-- `args` - Additional command-line arguments (optional)
-- `dashcam` - Enable Dashcam recording (default: `true`)
-- `os` - Target OS (default: `'linux'`)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `workspace` | string | - | Workspace/folder path to open |
+| `extensions` | string[] | `[]` | VS Code extension IDs to install |
 
-**Returns:**
-- `testdriver` - TestDriver instance
-- `app` - Alias for testdriver (semantic clarity)
-- `dashcam` - Dashcam instance (if enabled)
-
-### Web App
-
-Generic wrapper for web applications (currently uses Chrome):
+**Example - Basic Launch:**
 
 ```javascript
-const { testdriver } = await provision('webapp', {
-  url: 'https://example.com',
-  browser: 'chrome'  // Only 'chrome' supported currently
-}, context);
+it('should launch VS Code', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  
+  await testdriver.provision.vscode();
+  
+  const result = await testdriver.assert(
+    'Visual Studio Code window is visible on screen'
+  );
+  expect(result).toBeTruthy();
+});
 ```
 
-## Complete Example
+**Example - Install Extensions:**
 
 ```javascript
-import { describe, it, expect } from 'vitest';
-import { provision } from 'testdriverai/presets';
-
-describe('Login Flow', () => {
-  it('should login successfully', async (context) => {
-    // Provision Chrome with your app
-    const { testdriver, dashcam } = await provision('chrome', {
-      url: 'https://myapp.com/login',
-      maximized: true
-    }, context);
-    
-    // Interact with the application
-    await testdriver.find('email input').type('user@example.com');
-    await testdriver.find('password input').type('password123');
-    await testdriver.find('Login button').click();
-    
-    // Verify results
-    const result = await testdriver.assert('Welcome message is visible');
-    expect(result).toBeTruthy();
-    
-    // Dashcam automatically stops and saves replay at test end
-    // No cleanup needed - handled automatically!
+it('should install and use a VS Code extension', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  
+  // Launch VS Code with extensions installed
+  await testdriver.provision.vscode({
+    extensions: ['esbenp.prettier-vscode']
   });
+  
+  // Open the extensions panel
+  await testdriver.pressKeys(['ctrl', 'shift', 'x']);
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  
+  const result = await testdriver.assert(
+    'Prettier extension is visible in the extensions panel'
+  );
+  expect(result).toBeTruthy();
 });
 ```
 
-## How It Works
+---
 
-When you call `provision()`:
+## provision.installer()
 
-1. **Creates TestDriver client** - Initializes and connects to sandbox
-2. **Sets up Dashcam** - Authenticates and starts recording (if enabled)
-3. **Launches application** - Opens the specified app with your configuration
-4. **Focuses window** - Ensures the app is ready for interaction
-5. **Returns ready-to-use instances** - Everything is set up and ready
+Download and install applications from a URL. Automatically detects file type and runs the appropriate install command.
 
-At test end:
-- Dashcam automatically stops and saves replay URL
-- TestDriver automatically disconnects
-- All cleanup is handled for you
-
-## Automatic Lifecycle
+```javascript
+const filePath = await testdriver.provision.installer({
+  url: 'https://example.com/app.deb',
+  appName: 'MyApp'
+});
+```
 
-The `provision()` function uses Vitest hooks under the hood to manage the entire lifecycle:
+**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` | Whether to launch/focus the app after installation |
+
+**Returns:** `Promise<string>` - Path to the downloaded file
+
+**Supported File Types:**
+
+| Platform | Extensions | Install Command |
+|----------|------------|-----------------|
+| Linux | `.deb` | `sudo dpkg -i && apt-get install -f -y` |
+| Linux | `.rpm` | `sudo rpm -i` |
+| Linux | `.appimage` | `chmod +x` |
+| Linux | `.sh` | `chmod +x && execute` |
+| Windows | `.msi` | `msiexec /i /quiet /norestart` |
+| Windows | `.exe` | `Start-Process /S` |
+| macOS | `.dmg` | `hdiutil attach && cp to /Applications` |
+| macOS | `.pkg` | `installer -pkg -target /` |
+
+**Example - Install .deb Package:**
 
 ```javascript
-// ✅ This:
-const { testdriver } = await provision('chrome', { url }, context);
-
-// Is equivalent to manually doing:
-const client = new TestDriver(apiKey, { os: 'linux' });
-await client.auth();
-await client.connect();
+it('should install a .deb package', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  
+  const filePath = await testdriver.provision.installer({
+    url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb'
+  });
+  
+  // Verify installation
+  await testdriver.exec('sh', 'bat --version', 10000);
+});
+```
 
-const dashcam = new Dashcam(client);
-await dashcam.auth();
-await dashcam.start();
+**Example - Download Only (No Auto-Launch):**
 
-await client.exec('sh', 'google-chrome --start-maximized --guest "https://example.com" &', 30000);
-await client.focusApplication('Google Chrome');
+```javascript
+it('should download a script', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  
+  const filePath = await testdriver.provision.installer({
+    url: 'https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh',
+    launch: false
+  });
+  
+  // Run custom post-download commands
+  await testdriver.exec('sh', `source "${filePath}"`, 30000);
+});
+```
 
-// ... your test code ...
+**Example - Custom Post-Install:**
 
-await dashcam.stop();
-await client.disconnect();
+```javascript
+it('should run AppImage with custom flags', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  
+  const filePath = await testdriver.provision.installer({
+    url: 'https://example.com/app.AppImage',
+    launch: false
+  });
+  
+  // Run with custom arguments
+  await testdriver.exec('sh', `"${filePath}" --no-sandbox &`, 10000);
+  
+  await new Promise(resolve => setTimeout(resolve, 5000));
+  
+  const result = await testdriver.assert('App window is visible');
+  expect(result).toBeTruthy();
+});
 ```
 
-That's **15+ lines of boilerplate** reduced to **1 line**!
+---
 
-## TypeScript Support
+## provision.electron()
 
-Full TypeScript definitions included:
+Launch an Electron application.
 
-```typescript
-import { provision } from 'testdriverai/presets';
-
-test('typed test', async (context) => {
-  const { testdriver } = await provision('chrome', {
-    url: 'https://example.com',
-    maximized: true,
-    os: 'linux' // ✅ Type-safe: only 'linux' | 'mac' | 'windows'
-  }, context);
-  
-  // ✅ Full autocomplete for testdriver methods
-  await testdriver.find('button').click();
+```javascript
+await testdriver.provision.electron({
+  appPath: '/path/to/app',
+  args: ['--enable-logging']
 });
 ```
 
-## Direct Preset Functions
+**Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appPath` | string | **required** | Path to Electron application |
+| `args` | string[] | `[]` | Additional command-line arguments |
 
-You can also use the individual preset functions directly:
+**Example:**
 
 ```javascript
-import { chrome, vscode, electron } from 'testdriverai/presets';
-
-// Same as provision('chrome', options, context)
-const { testdriver } = await chrome(context, {
-  url: 'https://example.com'
-});
-
-// Same as provision('vscode', options, context)
-const { vscode } = await vscode(context, {
-  workspace: '/path/to/project'
+it('should launch Electron app', async (context) => {
+  const testdriver = TestDriver(context, { newSandbox: true });
+  
+  await testdriver.provision.electron({
+    appPath: '/path/to/my-electron-app',
+    args: ['--enable-logging']
+  });
+  
+  await testdriver.find('main window').click();
 });
 ```
 
-These are available for when you prefer explicit function names.
+---
 
-## Best Practices
+## How Provision Methods Work
+
+When you call a provision method:
 
-1. **Always pass context** - Required for automatic cleanup
-2. **Enable dashcam** - Great for debugging test failures
-3. **Use descriptive variables** - `testdriver`, `vscode`, `app` based on what you're testing
-4. **Leverage TypeScript** - Get autocomplete and type safety
-5. **Keep URLs in config** - Use environment variables for different environments
+1. **Waits for connection** - Calls `ready()` to ensure sandbox is connected
+2. **Sets up Dashcam** - Creates log file and adds to Dashcam monitoring
+3. **Starts recording** - Automatically starts Dashcam if not already recording
+4. **Launches application** - Opens the specified app with your configuration
+5. **Focuses window** - Ensures the app is ready for interaction
 
-## Error Handling
+At test end:
+- Dashcam automatically stops and saves replay URL
+- TestDriver automatically disconnects
+- All cleanup is handled for you
+
+## Complete Example
 
 ```javascript
-test('handles errors gracefully', async (context) => {
-  try {
-    const { testdriver } = await provision('chrome', {
-      url: 'https://example.com'
-    }, context);
+import { describe, it, expect } from 'vitest';
+import { TestDriver } from 'testdriverai/lib/vitest/hooks.mjs';
+
+describe('Application Testing', () => {
+  it('should test Chrome login flow', async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.chrome({
+      url: 'https://myapp.com/login'
+    });
+    
+    await testdriver.find('email').type('user@example.com');
+    await testdriver.find('password').type('password123');
+    await testdriver.find('Login').click();
     
-    await testdriver.find('button').click();
-  } catch (error) {
-    // Cleanup still happens automatically
-    console.error('Test failed:', error);
-    throw error; // Re-throw to mark test as failed
-  }
+    const result = await testdriver.assert('Welcome message is visible');
+    expect(result).toBeTruthy();
+  });
+
+  it('should test VS Code extension', async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.vscode({
+      extensions: ['ms-python.python']
+    });
+    
+    await testdriver.pressKeys(['ctrl', 'shift', 'p']);
+    await testdriver.type('Python: Select Interpreter');
+    await testdriver.pressKeys(['enter']);
+    
+    const result = await testdriver.assert('Python interpreter selector is visible');
+    expect(result).toBeTruthy();
+  });
+
+  it('should install and test CLI tool', async (context) => {
+    const testdriver = TestDriver(context, { newSandbox: true });
+    
+    await testdriver.provision.installer({
+      url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb'
+    });
+    
+    // Verify the tool works
+    await testdriver.exec('sh', 'bat --help', 10000);
+  });
 });
 ```
 
+## Best Practices
+
+1. **Use `newSandbox: true`** - Each test gets a clean environment
+2. **Enable Dashcam** - Great for debugging test failures (enabled by default)
+3. **Check assertions** - Always verify the expected state after actions
+4. **Use appropriate provision method** - Match the method to your test target
+5. **Handle async properly** - All provision methods return Promises
+
 ## See Also
 
-- [Hooks API](./HOOKS.md) - For more control over lifecycle
-- [Core Classes](./CORE.md) - For full manual control
-- [Migration Guide](../MIGRATION.md) - Upgrading from v6
-- [Examples](../../testdriver/acceptance-sdk/presets-example.test.mjs) - Working examples
+- [Hooks API](./hooks.mdx) - TestDriver initialization
+- [Find API](../api/find.mdx) - Element finding
+- [Exec API](../api/exec.mdx) - Running shell commands
+- [Assert API](../api/assert.mdx) - AI-powered assertions

package/docs/v7/getting-started/quickstart.mdx

@@ -1,12 +1,16 @@
 ---
 title: "Quick Start"
 sidebarTitle: "Quickstart"
-description: "Get started with the TestDriver JavaScript SDK in minutes."
+description: "Run your first computer-use test in minutes."
 icon: "rocket"
 mode: "wide"
 ---
 
-TestDriver makes it easy to write automated computer-use tests for web browsers, desktop apps, and more. In this quickstart, you'll write and run your first TestDriver test using Vitest in just a few minutes.
+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>
+
+## Get Started in 3 Steps
 
 <Steps>
   <Step title="Create a TestDriver Account">
@@ -20,7 +24,7 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
       arrow
       horizontal
     >
-      Start for free. No credit-card required!
+      No credit-card required!
     </Card>
 
   </Step>
@@ -41,10 +45,10 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
     TestDriver uses Vitest as the test runner. To run your test, use:
     
     ```bash
-    npx vitest run
+    vitest run
     ```
 
-    This will spawn a sandbox, launch Chrome, navigate to the specified URL, and run your test commands.
+    This will spawn a sandbox, launch Chrome, and run the example test!
 
   </Step>
 </Steps>
@@ -84,14 +88,3 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
     Choose your complexity level
   </Card>
 </CardGroup>
-
-## Why TestDriver v7?
-
-The v7 SDK offers advantages over YAML-based testing:
-
-- ✅ **Type Safety** - Full TypeScript support with IntelliSense
-- ✅ **Programmatic Control** - Use variables, loops, and functions
-- ✅ **Better Debugging** - Stack traces point to your actual code
-- ✅ **Automatic Lifecycle** - Presets handle setup and cleanup
-- ✅ **Framework Integration** - Works with Vitest, Jest, Mocha, etc.
-- ✅ **Video Replays** - Automatic Dashcam recording included

package/lib/vitest/hooks.mjs

@@ -15,11 +15,11 @@
  * });
  */
 
+import chalk from 'chalk';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { vi } from 'vitest';
-import chalk from 'chalk';
 import TestDriverSDK from '../../sdk.js';
 
 /**
@@ -78,26 +78,30 @@ function setupConsoleSpy(client, taskId) {
     }
   };
 
+  // Store original console methods before spying
+  const originalLog = console.log.bind(console);
+  const originalError = console.error.bind(console);
+  const originalWarn = console.warn.bind(console);
+  const originalInfo = console.info.bind(console);
+
   // Create spies for each console method
   const logSpy = vi.spyOn(console, 'log').mockImplementation((...args) => {
-    // Call through to original
-    logSpy.mock.calls; // Track calls
-    process.stdout.write(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ') + '\n');
+    originalLog(...args);  // Call original (Vitest will capture this)
     forwardToSandbox(args);
   });
 
   const errorSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
-    process.stderr.write(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ') + '\n');
+    originalError(...args);
     forwardToSandbox(args);
   });
 
   const warnSpy = vi.spyOn(console, 'warn').mockImplementation((...args) => {
-    process.stderr.write(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ') + '\n');
+    originalWarn(...args);
     forwardToSandbox(args);
   });
 
   const infoSpy = vi.spyOn(console, 'info').mockImplementation((...args) => {
-    process.stdout.write(args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ') + '\n');
+    originalInfo(...args);
     forwardToSandbox(args);
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.2",
+  "version": "7.2.3",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "exports": {

package/sdk.js

@@ -1702,26 +1702,49 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
        * @returns {Promise<void>}
        */
       vscode: async (options = {}) => {
-        this._ensureConnected();
+        // Automatically wait for connection to be ready
+        await this.ready();
         
         const {
           workspace = null,
           extensions = [],
         } = options;
 
+        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+
+        // If dashcam is available, set up file logging
+        if (this._dashcam) {
+          // Create the log file on the remote machine
+          const logPath = this.os === "windows" 
+            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
+            : "/tmp/testdriver.log";
+          
+          const createLogCmd = this.os === "windows"
+            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
+            : `touch ${logPath}`;
+          
+          await this.exec(shell, createLogCmd, 10000, true);
+          await this._dashcam.addFileLog(logPath, "TestDriver Log");
+        }
+        
+        // Automatically start dashcam if not already recording
+        if (!this._dashcam || !this._dashcam.recording) {
+          await this.dashcam.start();
+        }
+
         // Install extensions if provided
         for (const extension of extensions) {
-          const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+          console.log(`[provision.vscode] Installing extension: ${extension}`);
           await this.exec(
             shell,
-            `code --install-extension ${extension}`,
-            60000,
+            `code --install-extension ${extension} --force`,
+            120000,
             true
           );
+          console.log(`[provision.vscode] ✅ Extension installed: ${extension}`);
         }
 
         // Launch VS Code
-        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
         const workspaceArg = workspace ? `"${workspace}"` : '';
         
         if (this.os === 'windows') {
@@ -1738,10 +1761,148 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           );
         }
 
+        // Wait for VS Code to start up
+        await new Promise(resolve => setTimeout(resolve, 3000));
+
         // Wait for VS Code to be ready
         await this.focusApplication('Visual Studio Code');
       },
 
+      /**
+       * Download and install an application
+       * @param {Object} options - Installer options
+       * @param {string} options.url - URL to download the installer from
+       * @param {string} [options.filename] - Filename to save as (auto-detected from URL if not provided)
+       * @param {string} [options.appName] - Application name to focus after install
+       * @param {boolean} [options.launch=true] - Whether to launch the app after installation
+       * @returns {Promise<string>} Path to the downloaded file
+       * @example
+       * // Install a .deb package on Linux (auto-detected)
+       * await testdriver.provision.installer({
+       *   url: 'https://example.com/app.deb',
+       *   appName: 'MyApp'
+       * });
+       * 
+       * @example
+       * // Download and run custom commands
+       * const filePath = await testdriver.provision.installer({
+       *   url: 'https://example.com/app.AppImage',
+       *   launch: false
+       * });
+       * await testdriver.exec('sh', `chmod +x "${filePath}" && "${filePath}" &`, 10000);
+       */
+      installer: async (options = {}) => {
+        // Automatically wait for connection to be ready
+        await this.ready();
+        
+        const {
+          url,
+          filename,
+          appName,
+          launch = true,
+        } = options;
+
+        if (!url) {
+          throw new Error('[provision.installer] url is required');
+        }
+
+        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+
+        // If dashcam is available, set up file logging
+        if (this._dashcam) {
+          const logPath = this.os === "windows" 
+            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
+            : "/tmp/testdriver.log";
+          
+          const createLogCmd = this.os === "windows"
+            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
+            : `touch ${logPath}`;
+          
+          await this.exec(shell, createLogCmd, 10000, true);
+          await this._dashcam.addFileLog(logPath, "TestDriver Log");
+        }
+        
+        // Automatically start dashcam if not already recording
+        if (!this._dashcam || !this._dashcam.recording) {
+          await this.dashcam.start();
+        }
+
+        // Determine filename from URL if not provided
+        const urlObj = new URL(url);
+        const detectedFilename = filename || urlObj.pathname.split('/').pop() || 'installer';
+        
+        // Determine download directory and full path
+        const downloadDir = this.os === 'windows' 
+          ? 'C:\\Users\\testdriver\\Downloads'
+          : '/tmp';
+        const filePath = this.os === 'windows'
+          ? `${downloadDir}\\${detectedFilename}`
+          : `${downloadDir}/${detectedFilename}`;
+
+        console.log(`[provision.installer] Downloading ${url}...`);
+
+        // Download the file
+        if (this.os === 'windows') {
+          await this.exec(
+            shell,
+            `Invoke-WebRequest -Uri "${url}" -OutFile "${filePath}"`,
+            300000, // 5 min timeout for download
+            true
+          );
+        } else {
+          await this.exec(
+            shell,
+            `curl -L -o "${filePath}" "${url}"`,
+            300000,
+            true
+          );
+        }
+
+        console.log(`[provision.installer] ✅ Downloaded to ${filePath}`);
+
+        // Auto-detect install command based on file extension
+        const ext = detectedFilename.split('.').pop()?.toLowerCase();
+        let installCommand = null;
+        
+        if (this.os === 'windows') {
+          if (ext === 'msi') {
+            installCommand = `Start-Process msiexec -ArgumentList '/i', '"${filePath}"', '/quiet', '/norestart' -Wait`;
+          } else if (ext === 'exe') {
+            installCommand = `Start-Process "${filePath}" -ArgumentList '/S' -Wait`;
+          }
+        } else if (this.os === 'linux') {
+          if (ext === 'deb') {
+            installCommand = `sudo dpkg -i "${filePath}" && sudo apt-get install -f -y`;
+          } else if (ext === 'rpm') {
+            installCommand = `sudo rpm -i "${filePath}"`;
+          } else if (ext === 'appimage') {
+            installCommand = `chmod +x "${filePath}"`;
+          } else if (ext === 'sh') {
+            installCommand = `chmod +x "${filePath}" && "${filePath}"`;
+          }
+        } else if (this.os === 'darwin') {
+          if (ext === 'dmg') {
+            installCommand = `hdiutil attach "${filePath}" -mountpoint /Volumes/installer && cp -R /Volumes/installer/*.app /Applications/ && hdiutil detach /Volumes/installer`;
+          } else if (ext === 'pkg') {
+            installCommand = `sudo installer -pkg "${filePath}" -target /`;
+          }
+        }
+
+        if (installCommand) {
+          console.log(`[provision.installer] Installing...`);
+          await this.exec(shell, installCommand, 300000, true);
+          console.log(`[provision.installer] ✅ Installation complete`);
+        }
+
+        // Launch and focus the app if appName is provided and launch is true
+        if (appName && launch) {
+          await new Promise(resolve => setTimeout(resolve, 2000));
+          await this.focusApplication(appName);
+        }
+
+        return filePath;
+      },
+
       /**
        * Launch Electron app
        * @param {Object} options - Electron launch options
@@ -2606,6 +2767,8 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     createMarkdownLogger(this.emitter);
 
     // Set up basic event logging
+    // Note: We only console.log here - the console spy in vitest/hooks.mjs 
+    // handles forwarding to sandbox. This prevents duplicate output to server.
     this.emitter.on("log:**", (message) => {
       const event = this.emitter.event;
       if (event === events.log.debug && !debugMode) return;
@@ -2614,9 +2777,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           ? `[${this.testContext}] ${message}`
           : message;
         console.log(prefixedMessage);
-        
-        // Also forward to sandbox for dashcam
-        this._forwardLogToSandbox(prefixedMessage);
       }
     });
 
@@ -2675,36 +2835,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     });
   }
 
-  /**
-   * Forward log message to sandbox for debugger display
-   * @private
-   * @param {string} message - Log message to forward
-   */
-  _forwardLogToSandbox(message) {
-    try {
-      // Only forward if sandbox is connected
-      if (this.sandbox && this.sandbox.instanceSocketConnected) {
-        // Don't send objects as they cause base64 encoding errors
-        if (typeof message === "object") {
-          return;
-        }
-
-        // Add test context prefix if available
-        const prefixedMessage = this.testContext
-          ? `[${this.testContext}] ${message}`
-          : message;
-
-        this.sandbox.send({
-          type: "output",
-          output: Buffer.from(prefixedMessage).toString("base64"),
-        });
-      }
-    } catch {
-      // Silently fail to avoid breaking the log flow
-      // console.error("Error forwarding log to sandbox:", error);
-    }
-  }
-
   /**
    * Open URL in default browser
    * @private

package/test/testdriver/installer.test.mjs

@@ -0,0 +1,47 @@
+/**
+ * TestDriver SDK - Installer Test (Vitest)
+ * Tests the provision.installer() method for downloading and installing apps
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../lib/vitest/hooks.mjs";
+
+describe("Provision Installer", () => {
+  it(
+    "should download and install a .deb package on Linux",
+    async (context) => {
+      const testdriver = TestDriver(context, { newSandbox: true });
+      
+      // Install bat (a cat clone with syntax highlighting) using provision.installer
+      const filePath = await testdriver.provision.installer({
+        url: 'https://github.com/sharkdp/bat/releases/download/v0.24.0/bat_0.24.0_amd64.deb',
+      });
+
+      // Verify the file was downloaded
+      expect(filePath).toContain('bat');
+
+      // Verify bat was installed by running it
+      await testdriver.exec('sh', 'bat --version', 10000);
+    },
+  );
+
+  it(
+    "should download a shell script and verify it exists",
+    async (context) => {
+      const testdriver = TestDriver(context, { newSandbox: true });
+      
+      // Download a shell script (nvm installer)
+      const filePath = await testdriver.provision.installer({
+        url: 'https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh',
+        launch: false, // Don't auto-run the script
+      });
+
+      // Verify the file was downloaded
+      expect(filePath).toContain('install.sh');
+
+      // Verify the file is executable
+      const result = await testdriver.exec('sh', `ls -la "${filePath}"`, 10000);
+      expect(result).toBeTruthy();
+    },
+  );
+});

package/test/testdriver/launch-vscode-linux.test.mjs

@@ -0,0 +1,55 @@
+/**
+ * TestDriver SDK - Launch VS Code on Linux Test (Vitest)
+ * Tests launching Visual Studio Code on Debian/Ubuntu using provision.vscode()
+ */
+
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "../../lib/vitest/hooks.mjs";
+
+describe("Launch VS Code on Linux", () => {
+  it(
+    "should launch VS Code on Debian/Ubuntu",
+    async (context) => {
+      const testdriver = TestDriver(context, { newSandbox: true });
+      
+      // provision.vscode() automatically calls ready() and starts dashcam
+      await testdriver.provision.vscode();
+
+      // Assert that VS Code is running
+      const result = await testdriver.assert(
+        "Visual Studio Code window is visible on screen",
+      );
+      expect(result).toBeTruthy();
+    },
+  );
+
+  it(
+    "should install and use a VS Code extension",
+    async (context) => {
+      const testdriver = TestDriver(context, { newSandbox: true });
+      
+      // Launch VS Code with the Prettier extension installed
+      await testdriver.provision.vscode({
+        extensions: ["esbenp.prettier-vscode"],
+      });
+
+      // Assert that VS Code is running
+      const vsCodeVisible = await testdriver.assert(
+        "Visual Studio Code window is visible on screen",
+      );
+      expect(vsCodeVisible).toBeTruthy();
+
+      // Open the extensions panel to verify Prettier is installed
+      await testdriver.pressKeys(["ctrl", "shift", "x"]);
+      
+      // Wait for extensions panel to open
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      // Assert that Prettier extension is visible in the installed extensions
+      const prettierVisible = await testdriver.assert(
+        "Prettier extension is visible in the extensions panel or sidebar",
+      );
+      expect(prettierVisible).toBeTruthy();
+    },
+  );
+});

package/vitest.config.mjs

@@ -11,7 +11,7 @@ export default defineConfig({
     testTimeout: 900000,
     hookTimeout: 900000,
     reporters: [
-      'default',
+      'verbose',
       TestDriver(),
       ['junit', { outputFile: 'test-report.junit.xml' }]
     ],