testdriverai 7.0.0 → 7.1.1

package/docs/v7/_drafts/progressive-disclosure.mdx

@@ -0,0 +1,230 @@
+# Progressive Disclosure APIs
+
+TestDriver v7 introduces **progressive disclosure** - three levels of API to match your experience and needs.
+
+## Choose Your Level
+
+### 🟢 Beginner: Provision API
+
+**Best for:** Getting started, testing common apps (Chrome, VS Code, Electron)
+
+```javascript
+import { provision } from 'testdriverai/presets';
+
+test('my test', async (context) => {
+  const { testdriver } = await provision('chrome', {
+    url: 'https://example.com'
+  }, context);
+  
+  await testdriver.find('Login').click();
+});
+```
+
+**Why use this:**
+- ✅ Zero configuration
+- ✅ One line setup
+- ✅ Automatic everything (launch, focus, cleanup, recording)
+- ✅ Perfect for beginners
+
+[Learn more →](./PROVISION.md)
+
+---
+
+### 🟡 Intermediate: Hooks API
+
+**Best for:** Power users, custom workflows, manual lifecycle control
+
+```javascript
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  const client = useTestDriver(context, { os: 'linux' });
+  const dashcam = useDashcam(context, client, {
+    autoStart: true,
+    autoStop: true
+  });
+  
+  await client.find('button').click();
+});
+```
+
+**Why use this:**
+- ✅ Automatic cleanup
+- ✅ Flexible configuration
+- ✅ Control over lifecycle
+- ✅ Works with any application
+
+[Learn more →](./HOOKS.md)
+
+---
+
+### 🔴 Advanced: Core Classes
+
+**Best for:** Full control, non-Vitest frameworks, custom integrations
+
+```javascript
+import { TestDriver, Dashcam } from 'testdriverai/core';
+
+const client = new TestDriver(apiKey, { os: 'linux' });
+await client.auth();
+await client.connect();
+
+const dashcam = new Dashcam(client);
+await dashcam.start();
+
+// Your code
+
+await dashcam.stop();
+await client.disconnect();
+```
+
+**Why use this:**
+- ✅ Complete manual control
+- ✅ No framework dependencies
+- ✅ Works anywhere
+- ✅ Maximum flexibility
+
+[Learn more →](./CORE.md)
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│          🟢 Provision API (Easiest)         │
+│   provision('chrome', options, context)     │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│        🟡 Hooks API (Flexible)              │
+│   useTestDriver(), useDashcam()             │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│    🔴 Core Classes (Full Control)           │
+│   new TestDriver(), new Dashcam()           │
+└─────────────────────────────────────────────┘
+```
+
+Each level builds on the one below it. Choose the highest level that meets your needs.
+
+## Quick Comparison
+
+| Feature | Provision | Hooks | Core |
+|---------|-----------|-------|------|
+| Setup complexity | ⭐ 1 line | ⭐⭐ 2-3 lines | ⭐⭐⭐ 5+ lines |
+| Cleanup | ✅ Automatic | ✅ Automatic | ❌ Manual |
+| Framework requirement | Vitest | Vitest | None |
+| Application support | Chrome, VS Code, Electron | Any | Any |
+| Launch application | ✅ Automatic | ❌ Manual | ❌ Manual |
+| Dashcam recording | ✅ Automatic | ⚡ Optional automatic | ❌ Manual |
+| TypeScript support | ✅ Full | ✅ Full | ✅ Full |
+| Customization | ⚡ Limited | ✅ High | ✅ Complete |
+
+## When to Use Each
+
+### Use Provision API when:
+- ✅ Testing Chrome, VS Code, or Electron
+- ✅ You're a beginner
+- ✅ You want the simplest possible code
+- ✅ You're okay with defaults
+
+### Use Hooks API when:
+- ✅ You need custom application launch
+- ✅ You want automatic cleanup
+- ✅ You're using Vitest
+- ✅ You need fine-grained lifecycle control
+
+### Use Core Classes when:
+- ✅ Not using Vitest
+- ✅ Integrating with other frameworks
+- ✅ Building custom abstractions
+- ✅ Debugging lifecycle issues
+- ✅ Need complete manual control
+
+## Examples
+
+### Simple Chrome Test
+
+**Provision (1 line):**
+```javascript
+const { testdriver } = await provision('chrome', { url }, context);
+```
+
+**Hooks (3 lines):**
+```javascript
+const client = useTestDriver(context);
+await client.exec('sh', 'google-chrome "https://..." &', 30000);
+await client.focusApplication('Google Chrome');
+```
+
+**Core (6+ lines):**
+```javascript
+const client = new TestDriver(apiKey, { os: 'linux' });
+await client.auth();
+await client.connect();
+await client.exec('sh', 'google-chrome "https://..." &', 30000);
+await client.focusApplication('Google Chrome');
+// ... test code ...
+await client.disconnect();
+```
+
+### With Dashcam Recording
+
+**Provision (1 line):**
+```javascript
+const { testdriver, dashcam } = await provision('chrome', { url }, context);
+// Recording automatic!
+```
+
+**Hooks (2 lines):**
+```javascript
+const client = useTestDriver(context);
+const dashcam = useDashcam(context, client, { autoStart: true, autoStop: true });
+```
+
+**Core (7+ lines):**
+```javascript
+const client = new TestDriver(apiKey);
+await client.auth();
+await client.connect();
+const dashcam = new Dashcam(client);
+await dashcam.auth();
+await dashcam.start();
+// ... test code ...
+await dashcam.stop();
+await client.disconnect();
+```
+
+## Migration Path
+
+Start simple, grow as needed:
+
+1. **Start with Provision** - Get tests working quickly
+2. **Move to Hooks** - When you need custom app launch
+3. **Use Core** - Only if you need full control or non-Vitest
+
+You can mix and match in the same project!
+
+## Package Exports
+
+All three APIs are available from the same package:
+
+```javascript
+// Provision API
+import { provision, chrome, vscode, electron } from 'testdriverai/presets';
+
+// Hooks API
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+// Core Classes
+import { TestDriver, Dashcam } from 'testdriverai/core';
+```
+
+## See Also
+
+- [Provision API Reference](./PROVISION.md)
+- [Hooks API Reference](./HOOKS.md)
+- [Core Classes Reference](./CORE.md)
+- [Migration Guide](../MIGRATION.md)

package/docs/v7/_drafts/provision.mdx

@@ -0,0 +1,266 @@
+# 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.
+
+## Quick Start
+
+```javascript
+import { test } from 'vitest';
+import { provision } from 'testdriverai/presets';
+
+test('my test', async (context) => {
+  const { testdriver } = await provision('chrome', {
+    url: 'https://example.com'
+  }, context);
+  
+  await testdriver.find('Login button').click();
+});
+```
+
+## API
+
+```typescript
+provision(appType, options, context)
+```
+
+**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)
+
+**Returns:**
+- `testdriver` - TestDriver instance ready to use
+- `dashcam` - Dashcam instance (if enabled)
+- Additional app-specific properties (like `vscode`, `app`)
+
+## Application Types
+
+### Chrome Browser
+
+```javascript
+const { testdriver } = await 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();
+```
+
+**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'`)
+
+**Returns:**
+- `testdriver` - TestDriver instance
+- `dashcam` - Dashcam instance (if enabled)
+
+### VS Code
+
+```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();
+```
+
+**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)
+
+### Electron
+
+```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();
+```
+
+**Options:**
+- `appPath` - Path to Electron application (required)
+- `args` - Additional command-line arguments (optional)
+- `dashcam` - Enable Dashcam recording (default: `true`)
+- `os` - Target OS (default: `'linux'`)
+
+**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):
+
+```javascript
+const { testdriver } = await provision('webapp', {
+  url: 'https://example.com',
+  browser: 'chrome'  // Only 'chrome' supported currently
+}, context);
+```
+
+## Complete Example
+
+```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!
+  });
+});
+```
+
+## How It Works
+
+When you call `provision()`:
+
+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
+
+At test end:
+- Dashcam automatically stops and saves replay URL
+- TestDriver automatically disconnects
+- All cleanup is handled for you
+
+## Automatic Lifecycle
+
+The `provision()` function uses Vitest hooks under the hood to manage the entire lifecycle:
+
+```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();
+
+const dashcam = new Dashcam(client);
+await dashcam.auth();
+await dashcam.start();
+
+await client.exec('sh', 'google-chrome --start-maximized --guest "https://example.com" &', 30000);
+await client.focusApplication('Google Chrome');
+
+// ... your test code ...
+
+await dashcam.stop();
+await client.disconnect();
+```
+
+That's **15+ lines of boilerplate** reduced to **1 line**!
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```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();
+});
+```
+
+## Direct Preset Functions
+
+You can also use the individual preset functions directly:
+
+```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'
+});
+```
+
+These are available for when you prefer explicit function names.
+
+## Best Practices
+
+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
+
+## Error Handling
+
+```javascript
+test('handles errors gracefully', async (context) => {
+  try {
+    const { testdriver } = await provision('chrome', {
+      url: 'https://example.com'
+    }, context);
+    
+    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
+  }
+});
+```
+
+## 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

package/docs/{QUICK_START_TEST_RECORDING.md → v7/_drafts/quick-start-test-recording.mdx}

@@ -33,7 +33,7 @@ export default defineConfig({
 export TD_API_KEY="your-api-key-here"
 ```
 
-Get your API key from: https://app.testdriver.ai/settings/api-keys
+Get your API key from: https://console.testdriver.ai/settings/api-keys
 
 ### 3. Run Tests
 
@@ -42,7 +42,7 @@ npx vitest run
 ```
 
 That's it! Your tests are now being recorded. View results at:
-https://app.testdriver.ai/dashboard/test-runs
+https://console.testdriver.ai/dashboard/test-runs
 
 ## With Dashcam (Optional)
 
@@ -211,5 +211,5 @@ await client.completeTestRun({
 ## Support
 
 - Documentation: https://docs.testdriver.ai
-- Dashboard: https://app.testdriver.ai
+- Dashboard: https://console.testdriver.ai
 - API Reference: /cli/docs/TEST_RECORDING.md