testdriverai 6.2.2 → 7.1.0

package/docs/v7/progressive-apis/HOOKS.md

@@ -0,0 +1,360 @@
+# Hooks API
+
+React-style hooks for managing TestDriver and Dashcam lifecycle in Vitest tests.
+
+## Overview
+
+Hooks provide automatic lifecycle management - no more forgetting to disconnect or stop recording. They integrate seamlessly with Vitest's test context.
+
+```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, {
+    autoStart: true,
+    autoStop: true
+  });
+  
+  // Test code here
+  // Automatic cleanup at test end!
+});
+```
+
+## Available Hooks
+
+### useTestDriver
+
+Creates and manages a TestDriver instance with automatic cleanup.
+
+```javascript
+import { useTestDriver } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  const client = useTestDriver(context, {
+    os: 'linux',           // Target OS (default: 'linux')
+    autoConnect: true,     // Auto-connect to sandbox (default: true)
+    apiKey: process.env.TD_API_KEY,
+    apiRoot: 'https://...',
+    resolution: '1366x768',
+    analytics: true
+  });
+  
+  // Client is ready to use
+  await client.find('button').click();
+  
+  // Auto-disconnects at test end
+});
+```
+
+**Parameters:**
+- `context` - Vitest test context (required)
+- `options` - TestDriver configuration options
+
+**Options:**
+- `os` - Target OS: `'linux'`, `'mac'`, or `'windows'` (default: `'linux'`)
+- `autoConnect` - Automatically connect to sandbox (default: `true`)
+- `apiKey` - TestDriver API key (default: `process.env.TD_API_KEY`)
+- `apiRoot` - API endpoint URL
+- `resolution` - Screen resolution (default: `'1366x768'`)
+- `analytics` - Enable analytics (default: `true`)
+- `cacheThresholds` - Cache settings for find operations
+
+**Returns:**
+- TestDriver instance, ready to use
+
+### useDashcam
+
+Creates and manages a Dashcam instance with optional auto-lifecycle.
+
+```javascript
+import { useDashcam } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  // Assuming you have a client from useTestDriver
+  const dashcam = useDashcam(context, client, {
+    autoAuth: true,    // Auto-authenticate (default: true)
+    autoStart: true,   // Auto-start recording (default: false)
+    autoStop: true,    // Auto-stop at test end (default: false)
+    apiKey: process.env.TD_API_KEY  // Optional - uses TD_API_KEY by default
+  });
+  
+  // If autoStart is false, manually start:
+  // await dashcam.start();
+  
+  // Your test code
+  
+  // If autoStop is true, URL is saved automatically
+  // Otherwise, manually stop:
+  // const url = await dashcam.stop();
+});
+```
+
+**Parameters:**
+- `context` - Vitest test context (required)
+- `client` - TestDriver instance from `useTestDriver()` (required)
+- `options` - Dashcam configuration options
+
+**Options:**
+- `autoAuth` - Automatically authenticate (default: `true`)
+- `autoStart` - Automatically start recording (default: `false`)
+- `autoStop` - Automatically stop recording at test end (default: `false`)
+- `apiKey` - API key (default: `process.env.TD_API_KEY`, same as TestDriver)
+
+**Returns:**
+- Dashcam instance
+
+### useTestDriverWithDashcam
+
+Combined hook for the simplest usage - everything automatic.
+
+```javascript
+import { useTestDriverWithDashcam } from 'testdriverai/vitest/hooks';
+
+test('my test', async (context) => {
+  const { client, dashcam } = useTestDriverWithDashcam(context, {
+    os: 'linux',
+    // All TestDriver options +
+    // All Dashcam options (autoAuth, autoStart, autoStop all true by default)
+  });
+  
+  // Everything is ready - just write your test!
+  await client.find('button').click();
+  
+  // Dashcam auto-stops, client auto-disconnects
+});
+```
+
+**Parameters:**
+- `context` - Vitest test context (required)
+- `options` - Combined TestDriver and Dashcam options
+
+**Returns:**
+- `{ client, dashcam }` - Both instances, fully configured
+
+## Complete Examples
+
+### Basic Test with Hooks
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import { useTestDriver } from 'testdriverai/vitest/hooks';
+
+describe('Search Tests', () => {
+  it('should search successfully', async (context) => {
+    const client = useTestDriver(context, { os: 'linux' });
+    
+    await client.focusApplication('Google Chrome');
+    await client.find('search box').type('testdriverai');
+    await client.pressKeys(['enter']);
+    
+    const result = await client.assert('search results appear');
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+### With Dashcam Recording
+
+```javascript
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+test('recorded test', async (context) => {
+  const client = useTestDriver(context, { os: 'linux' });
+  const dashcam = useDashcam(context, client, {
+    autoAuth: true,
+    autoStart: true,
+    autoStop: true  // URL saved automatically
+  });
+  
+  await client.focusApplication('Google Chrome');
+  await client.find('button').click();
+  
+  // Dashcam URL will be in test results
+});
+```
+
+### Fully Automatic
+
+```javascript
+import { useTestDriverWithDashcam } from 'testdriverai/vitest/hooks';
+
+test('automatic everything', async (context) => {
+  const { client } = useTestDriverWithDashcam(context);
+  
+  await client.focusApplication('Google Chrome');
+  await client.find('login').click();
+  
+  // Dashcam + TestDriver managed automatically
+});
+```
+
+### Manual Control (Advanced)
+
+```javascript
+import { useTestDriver, useDashcam } from 'testdriverai/vitest/hooks';
+
+test('manual control', async (context) => {
+  const client = useTestDriver(context, {
+    os: 'linux',
+    autoConnect: false  // We'll connect manually
+  });
+  
+  // Manual connection
+  await client.auth();
+  await client.connect({ new: true });
+  
+  const dashcam = useDashcam(context, client, {
+    autoAuth: true,
+    autoStart: false,  // Manual start
+    autoStop: false    // Manual stop
+  });
+  
+  // Start recording when ready
+  await dashcam.start();
+  
+  await client.find('button').click();
+  
+  // Stop and get URL
+  const url = await dashcam.stop();
+  console.log('Replay:', url);
+  
+  // Cleanup still automatic!
+});
+```
+
+## How Hooks Work
+
+Hooks use Vitest's `context.onTestFinished()` to register cleanup handlers:
+
+```javascript
+// Internally, hooks do this:
+export function useTestDriver(context, options = {}) {
+  const client = new TestDriver(apiKey, options);
+  
+  // Register cleanup
+  context.onTestFinished(async () => {
+    await client.disconnect();
+  });
+  
+  return client;
+}
+```
+
+This ensures cleanup always runs, even if your test fails.
+
+## TypeScript Support
+
+```typescript
+import { useTestDriver, UseDashcamOptions } from 'testdriverai/vitest/hooks';
+
+test('typed test', async (context) => {
+  const client = useTestDriver(context, {
+    os: 'linux',  // ✅ Type-safe
+    resolution: '1920x1080'
+  });
+  
+  const dashcamOptions: UseDashcamOptions = {
+    autoAuth: true,
+    autoStart: true,
+    autoStop: true
+    // apiKey is optional - uses TD_API_KEY by default
+  };
+  
+  const dashcam = useDashcam(context, client, dashcamOptions);
+});
+```
+
+## When to Use Hooks
+
+**Use hooks when:**
+- You want automatic cleanup
+- You're testing with Vitest
+- You need custom lifecycle control
+- You're a power user who understands the lifecycle
+
+**Use `provision()` instead when:**
+- You're testing Chrome, VS Code, or Electron
+- You want zero configuration
+- You're a beginner
+- You want the simplest API
+
+**Use core classes directly when:**
+- You need full manual control
+- You're not using Vitest
+- You're debugging lifecycle issues
+
+## Best Practices
+
+1. **Always pass context** - Required for automatic cleanup
+2. **One client per test** - Don't share clients between tests
+3. **Use autoStart/autoStop for Dashcam** - Unless you have specific timing needs
+4. **Leverage TypeScript** - Get autocomplete and catch errors early
+5. **Keep options in variables** - Easier to maintain and reuse
+
+## Common Patterns
+
+### Shared Setup
+
+```javascript
+function setupBrowser(context) {
+  const client = useTestDriver(context, { os: 'linux' });
+  const dashcam = useDashcam(context, client, {
+    autoAuth: true,
+    autoStart: true,
+    autoStop: true
+  });
+  return { client, dashcam };
+}
+
+test('test 1', async (context) => {
+  const { client } = setupBrowser(context);
+  // ...
+});
+
+test('test 2', async (context) => {
+  const { client } = setupBrowser(context);
+  // ...
+});
+```
+
+### Conditional Dashcam
+
+```javascript
+test('maybe record', async (context) => {
+  const client = useTestDriver(context);
+  
+  const shouldRecord = process.env.RECORD_TESTS === 'true';
+  const dashcam = shouldRecord 
+    ? useDashcam(context, client, { autoStart: true, autoStop: true })
+    : null;
+  
+  // Test code...
+});
+```
+
+## Error Handling
+
+Cleanup runs even if your test fails:
+
+```javascript
+test('failing test', async (context) => {
+  const client = useTestDriver(context);
+  
+  try {
+    await client.find('nonexistent element').click();
+  } catch (error) {
+    console.error('Test failed:', error);
+    throw error;  // Test marked as failed
+  }
+  
+  // client.disconnect() still runs automatically
+});
+```
+
+## See Also
+
+- [Provision API](./PROVISION.md) - Simpler API for common apps
+- [Core Classes](./CORE.md) - Manual control
+- [Migration Guide](../MIGRATION.md) - Upgrading from v6

package/docs/v7/progressive-apis/PROGRESSIVE_DISCLOSURE.md

@@ -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)