testdriverai 6.2.2 → 7.1.0

package/docs/MIGRATION.md

@@ -0,0 +1,425 @@
+# Migration Guide: v6 → v7
+
+This guide helps you migrate from the old TestDriver API (v6) to the new SDK architecture (v7).
+
+## Overview
+
+v7 introduces a **progressive disclosure** pattern with three API levels:
+
+1. **Presets** (Beginner) - Zero config, instant setup
+2. **Hooks** (Intermediate) - Flexible lifecycle management
+3. **Core Classes** (Advanced) - Full manual control
+
+You can mix and match these patterns based on your needs.
+
+## Quick Migration Examples
+
+### Before (v6) - Legacy Helpers
+
+```javascript
+import { test } from 'vitest';
+import { authDashcam, startDashcam, stopDashcam } from 'testdriverai';
+
+test('my test', async ({ client }) => {
+  await authDashcam(client);
+  await startDashcam(client);
+  
+  await client.find('Login button').click();
+  
+  const url = await stopDashcam(client);
+  console.log('Replay:', url);
+});
+```
+
+### After (v7) - Using Presets
+
+```javascript
+import { test } from 'vitest';
+import { chromePreset } from 'testdriverai/presets';
+
+test('my test', async (context) => {
+  const { client } = await chromePreset(context, {
+    url: 'https://myapp.com'
+  });
+  
+  // Dashcam already running, auto-stops at test end
+  await client.find('Login button').click();
+});
+```
+
+### After (v7) - Using Hooks
+
+```javascript
+import { test } from 'vitest';
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  const client = useTestDriver(context, { os: 'linux' });
+  const dashcam = useDashcam(context, client, {
+    autoAuth: true,
+    autoStart: true,
+    autoStop: true
+  });
+  
+  await client.find('Login button').click();
+});
+```
+
+### After (v7) - Using Core Classes
+
+```javascript
+import { test } from 'vitest';
+import { TestDriver, Dashcam } from 'testdriverai/core';
+
+test('my test', async (context) => {
+  const client = new TestDriver(process.env.TD_API_KEY, { os: 'linux' });
+  const dashcam = new Dashcam(client);
+  
+  await client.auth();
+  await client.connect();
+  
+  await dashcam.auth();
+  await dashcam.start();
+  
+  await client.find('Login button').click();
+  
+  const url = await dashcam.stop();
+  await client.disconnect();
+  
+  console.log('Replay:', url);
+});
+```
+
+## Package Exports
+
+v7 introduces multiple entry points for different use cases:
+
+```javascript
+// Main SDK (unchanged)
+import TestDriver from 'testdriverai';
+
+// Core classes
+import { TestDriver, Dashcam } from 'testdriverai/core';
+
+// Vitest hooks
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+// Presets
+import { chromePreset, vscodePreset } from 'testdriverai/presets';
+
+// Vitest plugin (unchanged)
+import testDriver from 'testdriverai/vitest';
+```
+
+## API Changes
+
+### Dashcam Lifecycle Helpers (DEPRECATED)
+
+The following functions are **deprecated** but still work for backward compatibility:
+
+```javascript
+// ❌ OLD (still works, but deprecated)
+import { 
+  authDashcam,
+  addDashcamLog,
+  startDashcam,
+  stopDashcam 
+} from 'testdriverai';
+
+authDashcam(client);
+startDashcam(client);
+stopDashcam(client);
+```
+
+**Migrate to:**
+
+```javascript
+// ✅ NEW - Direct class usage
+import { Dashcam } from 'testdriverai/core';
+
+const dashcam = new Dashcam(client);
+await dashcam.auth();
+await dashcam.start();
+const url = await dashcam.stop();
+```
+
+Or even better:
+
+```javascript
+// ✅ NEW - Using hooks
+import { useDashcam } from 'testdriverai/vitest/hooks';
+
+const dashcam = useDashcam(context, client, {
+  autoAuth: true,
+  autoStart: true,
+  autoStop: true
+});
+```
+
+### TestDriver Client Creation
+
+**No changes needed** - the main SDK API remains the same:
+
+```javascript
+// Still works exactly the same
+import TestDriver from 'testdriverai';
+const client = new TestDriver(apiKey, { os: 'linux' });
+```
+
+But you now have cleaner alternatives:
+
+```javascript
+// Using hooks (auto-cleanup)
+import { useTestDriver } from 'testdriverai/vitest/hooks';
+const client = useTestDriver(context, { os: 'linux' });
+
+// Using presets (zero config)
+import { chromePreset } from 'testdriverai/presets';
+const { browser } = await chromePreset(context, { url: 'https://example.com' });
+```
+
+## Migration Strategies
+
+### Strategy 1: Gradual Migration
+
+Keep existing tests working, adopt new APIs for new tests:
+
+```javascript
+// old-test.js - Leave as-is
+import { authDashcam, startDashcam } from 'testdriverai';
+
+// new-test.js - Use new APIs
+import { chromePreset } from 'testdriverai/presets';
+```
+
+The old helpers will continue to work indefinitely.
+
+### Strategy 2: Convert to Hooks
+
+Replace lifecycle helpers with hooks for better lifecycle management:
+
+**Before:**
+```javascript
+import { authDashcam, startDashcam, stopDashcam } from 'testdriverai';
+
+test('my test', async ({ client }) => {
+  await authDashcam(client);
+  await startDashcam(client);
+  // test code
+  await stopDashcam(client);
+});
+```
+
+**After:**
+```javascript
+import { useDashcam } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  // Assuming client is already available via plugin or another hook
+  const dashcam = useDashcam(context, client, {
+    autoAuth: true,
+    autoStart: true,
+    autoStop: true
+  });
+  // test code
+  // Auto-stops at test end
+});
+```
+
+### Strategy 3: Adopt Presets
+
+For common scenarios (Chrome, VS Code, Electron), use presets:
+
+**Before:**
+```javascript
+test('chrome test', async ({ client }) => {
+  await authDashcam(client);
+  await startDashcam(client);
+  
+  await client.exec('sh', 'google-chrome "https://example.com" &', 30000);
+  await client.focusApplication('Google Chrome');
+  
+  await client.find('button').click();
+  
+  await stopDashcam(client);
+});
+```
+
+**After:**
+```javascript
+test('chrome test', async (context) => {
+  const { browser } = await chromePreset(context, {
+    url: 'https://example.com'
+  });
+  
+  await browser.find('button').click();
+  // Dashcam auto-stops, cleanup automatic
+});
+```
+
+## Benefits of Migration
+
+### Before Migration
+
+- ❌ Manual lifecycle management (easy to forget cleanup)
+- ❌ Lots of boilerplate for common scenarios
+- ❌ No TypeScript support
+- ❌ Helper functions scattered across codebase
+- ❌ Tight coupling to plugin
+
+### After Migration
+
+- ✅ Automatic lifecycle management (hooks)
+- ✅ Zero boilerplate (presets)
+- ✅ Full TypeScript definitions
+- ✅ Organized, composable APIs
+- ✅ Works with or without plugin
+
+## Common Patterns
+
+### Pattern 1: Chrome Testing
+
+```javascript
+// OLD
+test('chrome test', async ({ client }) => {
+  await client.exec('sh', 'google-chrome "https://example.com" &', 30000);
+  await client.focusApplication('Google Chrome');
+  await authDashcam(client);
+  await startDashcam(client);
+  // ... test code
+  await stopDashcam(client);
+});
+
+// NEW
+import { chromePreset } from 'testdriverai/presets';
+
+test('chrome test', async (context) => {
+  const { client } = await chromePreset(context, {
+    url: 'https://example.com'
+  });
+  // ... test code
+});
+```
+
+**Lines of code:** 7 → 2 (71% reduction)
+
+### Pattern 2: Manual Dashcam Control
+
+```javascript
+// OLD
+test('dashcam test', async ({ client }) => {
+  await authDashcam(client);
+  await startDashcam(client);
+  // ... test code
+  const url = await stopDashcam(client);
+  console.log(url);
+});
+
+// NEW
+import { Dashcam } from 'testdriverai/core';
+
+test('dashcam test', async (context) => {
+  const dashcam = new Dashcam(client);
+  await dashcam.auth();
+  await dashcam.start();
+  // ... test code
+  const url = await dashcam.stop();
+  console.log(url);
+});
+```
+
+### Pattern 3: Custom Application Setup
+
+```javascript
+// OLD
+test('custom app', async ({ client }) => {
+  await authDashcam(client);
+  await startDashcam(client);
+  await client.exec('sh', 'myapp --arg1 --arg2 &', 30000);
+  await client.focusApplication('MyApp');
+  // ... test code
+  await stopDashcam(client);
+});
+
+// NEW - Create custom preset
+import { createPreset } from 'testdriverai/presets';
+
+const myAppPreset = createPreset({
+  name: 'My App',
+  defaults: { args: [] },
+  async setup(context, client, dashcam, options) {
+    const { args = [] } = options;
+    const argsStr = args.join(' ');
+    await client.exec('sh', `myapp ${argsStr} &`, 30000);
+    await client.focusApplication('MyApp');
+    return {}; // client is returned automatically
+  }
+});
+
+test('custom app', async (context) => {
+  const { client } = await myAppPreset(context, {
+    args: ['--arg1', '--arg2']
+  });
+  // ... test code
+  // Auto-cleanup
+});
+```
+
+**Reusable** - Use `myAppPreset` in all your tests!
+
+## TypeScript Support
+
+v7 includes full TypeScript definitions:
+
+```typescript
+import { test } from 'vitest';
+import { chromePreset, ChromePresetOptions } from 'testdriverai/presets';
+import { useTestDriver, UseDashcamOptions } from 'testdriverai/vitest/hooks';
+import { Dashcam, DashcamOptions } from 'testdriverai/core';
+
+// Full autocomplete and type checking!
+test('typed test', async (context) => {
+  const { client } = await chromePreset(context, {
+    url: 'https://example.com',
+    maximized: true,
+    os: 'linux' // Type-safe: only 'linux' | 'mac' | 'windows'
+  });
+  
+  await client.find('button').click();
+});
+```
+
+## Breaking Changes
+
+### None! 🎉
+
+v7 is **100% backward compatible**. All existing code continues to work.
+
+The old lifecycle helpers (`authDashcam`, `startDashcam`, `stopDashcam`) are marked as deprecated but fully functional.
+
+## Deprecation Timeline
+
+- **v7.0** - New APIs introduced, old helpers work (with deprecation warnings)
+- **v7.x** - Old helpers continue to work
+- **v8.0** - Old helpers removed (TBD, at least 6 months notice)
+
+## Getting Help
+
+- 📖 **Hooks Documentation**: See `/docs/HOOKS.md`
+- 📖 **Presets Documentation**: See `/docs/PRESETS.md`
+- 💬 **Examples**: See `/testdriver/acceptance-sdk/*-example.test.mjs`
+- 🐛 **Issues**: GitHub Issues
+
+## Summary
+
+**Choose your level:**
+
+| Level | Best For | Example |
+|-------|----------|---------|
+| **Presets** | Common apps (Chrome, VS Code) | `chromePreset(context, { url })` |
+| **Hooks** | Custom lifecycle, power users | `useTestDriver(context, options)` |
+| **Core** | Advanced control, debugging | `new Dashcam(client)` |
+
+**Recommendation:** Start with presets for common scenarios, use hooks for custom needs, drop to core classes only when necessary.
+
+Migration is **optional** - your existing code continues to work!

package/docs/PRESETS.md

@@ -0,0 +1,210 @@
+# TestDriver Presets
+
+Presets provide pre-configured setups for common applications, reducing boilerplate and making your tests easier to write.
+
+## Available Presets
+
+### chromePreset
+
+Automatically sets up Chrome browser with TestDriver and Dashcam.
+
+```javascript
+import { test } from 'vitest';
+import { chromePreset } from 'testdriverai/presets';
+
+test('my test', async (context) => {
+  const { client } = await chromePreset(context, {
+    url: 'https://myapp.com/login'
+  });
+  
+  await client.find('email input').type('user@example.com');
+  await client.find('Login button').click();
+});
+```
+
+**Options:**
+- `url` - URL to navigate to (default: 'http://testdriver-sandbox.vercel.app/')
+- `os` - Target OS: 'linux', 'mac', 'windows' (default: 'linux')
+- `dashcam` - Enable Dashcam recording (default: true)
+- `maximized` - Start maximized (default: true)
+- `guest` - Use guest mode (default: true)
+
+**Returns:**
+- `client` - TestDriver instance
+- `dashcam` - Dashcam instance (if enabled)
+
+### vscodePreset
+
+Automatically sets up VS Code with TestDriver and Dashcam.
+
+```javascript
+import { vscodePreset } from 'testdriverai/presets';
+
+test('extension test', async (context) => {
+  const { vscode } = await vscodePreset(context, {
+    workspace: '/tmp/test-project',
+    extensions: ['ms-python.python']
+  });
+  
+  await vscode.find('File menu').click();
+  await vscode.find('New File').click();
+});
+```
+
+**Options:**
+- `workspace` - Workspace/folder to open
+- `os` - Target OS (default: 'linux')
+- `dashcam` - Enable Dashcam recording (default: true)
+- `extensions` - Array of extension IDs to install
+
+**Returns:**
+- `client` - TestDriver instance
+- `vscode` - Alias for client
+- `dashcam` - Dashcam instance (if enabled)
+
+### electronPreset
+
+Automatically sets up an Electron application.
+
+```javascript
+import { electronPreset } from 'testdriverai/presets';
+
+test('electron app test', async (context) => {
+  const { app } = await electronPreset(context, {
+    appPath: '/path/to/electron/app',
+    args: ['--enable-logging']
+  });
+  
+  await app.find('main window').click();
+});
+```
+
+**Options:**
+- `appPath` - Path to Electron app (required)
+- `os` - Target OS (default: 'linux')
+- `dashcam` - Enable Dashcam recording (default: true)
+- `args` - Additional electron arguments
+
+**Returns:**
+- `client` - TestDriver instance
+- `app` - Alias for client
+- `dashcam` - Dashcam instance (if enabled)
+
+### webAppPreset
+
+Generic web application preset (currently uses Chrome).
+
+```javascript
+import { webAppPreset } from 'testdriverai/presets';
+
+test('web app test', async (context) => {
+  const { client } = await webAppPreset(context, {
+    url: 'https://example.com',
+    browser: 'chrome' // Only Chrome supported currently
+  });
+  
+  await client.find('login form').click();
+});
+```
+
+## Creating Custom Presets
+
+Use `createPreset` to build your own presets:
+
+```javascript
+import { createPreset } from 'testdriverai/presets';
+
+const firefoxPreset = createPreset({
+  name: 'Firefox Browser',
+  defaults: { os: 'linux', dashcam: true },
+  async setup(context, client, dashcam, options) {
+    const { url } = options;
+    
+    // Launch Firefox
+    await client.exec('sh', `firefox "${url}" >/dev/null 2>&1 &`, 30000);
+    await client.focusApplication('Firefox');
+    
+    return {
+      // client is already included automatically
+    };
+  },
+});
+
+// Use your custom preset
+test('my test', async (context) => {
+  const { client } = await firefoxPreset(context, {
+    url: 'https://example.com',
+  });
+  
+  await client.find('page content').click();
+});
+```
+
+### createPreset API
+
+```javascript
+createPreset({
+  name: string,           // Preset name (for errors)
+  defaults: object,       // Default options
+  setup: async function   // Setup function
+})
+```
+
+The `setup` function receives:
+- `context` - Vitest test context
+- `client` - TestDriver instance (already connected)
+- `dashcam` - Dashcam instance (if enabled)
+- `options` - Merged defaults + user options
+
+The `setup` function should return an object with any custom properties. The returned object will automatically include `client` and `dashcam`.
+
+## How Presets Work
+
+Presets automatically:
+
+1. **Create TestDriver client** - Uses `useTestDriver` hook
+2. **Connect to sandbox** - Authenticates and connects
+3. **Set up Dashcam** - If enabled (default: true)
+4. **Configure application** - Launch and focus the app
+5. **Handle cleanup** - Automatic disconnect and dashcam stop
+
+All lifecycle is managed automatically via Vitest hooks.
+
+## Progressive Disclosure
+
+Presets fit into the progressive disclosure pattern:
+
+### Beginner (Presets)
+```javascript
+const { client } = await chromePreset(context, { url: 'https://example.com' });
+```
+Everything automatic - just pass URL and start testing.
+
+### Intermediate (Hooks)
+```javascript
+const client = useTestDriver(context, { os: 'linux' });
+const dashcam = useDashcam(context, client, { autoStart: true });
+// Custom setup code
+```
+More control over lifecycle, still automatic cleanup.
+
+### Advanced (Direct)
+```javascript
+const client = new TestDriver(apiKey, { os: 'linux' });
+await client.auth();
+await client.connect();
+// Full manual control
+```
+Complete control, manual everything.
+
+## Best Practices
+
+1. **Use presets for common scenarios** - Chrome, VS Code, Electron
+2. **Create custom presets for your apps** - Encapsulate setup logic
+3. **Enable dashcam by default** - Great for debugging failures
+4. **Keep presets focused** - One app/scenario per preset
+5. **Use descriptive variable names** - `client`, `vscode`, `app` based on what you're testing
+
+## Examples
+
+See `testdriver/acceptance-sdk/presets-example.test.mjs` for working examples.