testdriverai 7.2.2 → 7.2.9

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/_drafts/quick-start-test-recording.mdx

@@ -185,7 +185,6 @@ await client.completeTestRun({
 **API (Backend)**
 - `api/models/TdTestRun.js` - Test run model
 - `api/models/TdTestCase.js` - Test case model
-- `api/models/TdSandbox.js` - Sandbox tracking model
 - `api/controllers/testdriver/testdriver-test-run-create.js` - Create test run endpoint
 - `api/controllers/testdriver/testdriver-test-run-complete.js` - Complete test run endpoint
 - `api/controllers/testdriver/testdriver-test-case-create.js` - Record test case endpoint

package/docs/v7/_drafts/test-recording.mdx

@@ -376,12 +376,6 @@ const run2 = await client.createTestRun({
 - Associated dashcam replay
 - Timing and duration
 
-### TdSandbox
-- VM/sandbox lifecycle tracking
-- Platform and OS information
-- Dashcam integration status
-- Cost and usage metrics
-
 ### Replay
 - Dashcam recordings
 - Linked to test runs and cases

package/docs/v7/api/act.mdx

@@ -3,6 +3,7 @@ title: "act()"
 sidebarTitle: "act"
 description: "Execute natural language tasks using AI"
 icon: "wand-magic-sparkles"
+tag: beta
 ---
 
 ## Overview

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