testdriverai 7.0.0 → 7.1.1

package/docs/v7/_drafts/hooks.mdx

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