testdriverai 7.1.0 → 7.1.2

package/docs/v7/_drafts/sdk-v7-complete.mdx

@@ -0,0 +1,345 @@
+# SDK v7 Implementation - Complete Summary
+
+## ✅ All Phases Complete
+
+Implementation of the TestDriver SDK v7 redesign following progressive disclosure pattern.
+
+---
+
+## Phase 1: Core Foundation ✅ (Week 1-2)
+
+### Task 1.1: Dashcam Class Extraction ✅
+- **Created:** `lib/core/Dashcam.js` (422 lines)
+- **Features:**
+  - Composable Dashcam class independent of lifecycle helpers
+  - Methods: `auth()`, `addLog()`, `start()`, `stop()`, `isRecording()`
+  - Platform-aware shell handling (Windows/Linux/Mac)
+  - State tracking with `this.recording` property
+- **Testing:** Unit tests in `test/dashcam.test.js` (5 passing)
+
+### Task 1.2: Helper Functions Module (SKIPPED)
+- Skipped per user request
+- Not needed - lifecycle helpers remain as thin wrappers
+
+### Task 1.3: Package Exports Finalization ✅
+- **Modified:** `package.json`
+- **Added exports:**
+  - `"."` → `./sdk.js` (main SDK)
+  - `"./core"` → `./lib/core/index.js` (TestDriver + Dashcam)
+  - `"./vitest"` → `./interfaces/vitest-plugin.mjs` (plugin)
+  - `"./vitest/hooks"` → `./lib/vitest/hooks.mjs` (hooks)
+  - `"./presets"` → `./lib/presets/index.mjs` (presets)
+
+### Key Achievements:
+- ✅ Backward compatibility maintained via thin wrappers
+- ✅ WeakMap pattern for state persistence across helper calls
+- ✅ Clean separation of concerns (core vs helpers)
+- ✅ All acceptance tests passing
+
+**Commit:** `66fe7c9` - Phase 1 Complete: Core Foundation
+
+---
+
+## Phase 2: Vitest Plugin Enhancement ✅ (Week 3-4)
+
+### Task 2.1: Vitest Hooks API ✅
+- **Created:** `lib/vitest/hooks.mjs` (221 lines)
+- **Three hooks implemented:**
+  1. `useTestDriver(context, options)` - Managed TestDriver instance
+     - Auto-connect to sandbox (default: true)
+     - Automatic cleanup via `context.onTestFinished()`
+     - WeakMap storage for instance management
+  
+  2. `useDashcam(context, client, options)` - Managed Dashcam instance
+     - Optional `autoAuth`, `autoStart`, `autoStop`
+     - Automatic URL registration with plugin
+     - Lifecycle tied to test context
+  
+  3. `useTestDriverWithDashcam(context, options)` - Combined hook
+     - Single-line setup for both services
+     - Full auto-lifecycle management
+     - Simplest API for 90% of use cases
+
+- **Created:** `testdriver/acceptance-sdk/hooks-example.test.mjs`
+- **Pattern:** React-style hooks requiring Vitest context parameter
+
+### Task 2.2: Auto-lifecycle Mode (DEFERRED)
+- Not yet implemented (optional enhancement)
+- Can be added in future iteration
+
+### Task 2.3: Simplify Plugin Config (DEFERRED)
+- Not yet implemented (optional enhancement)
+- Current config already functional
+
+**Commit:** `54b43b2` - Phase 2 Task 2.1: Vitest Hooks API
+
+---
+
+## Phase 3: Presets System ✅ (Week 5-6)
+
+### Task 3.1: Built-in Presets ✅
+- **Created:** `lib/presets/index.mjs` (400+ lines)
+
+**chromePreset:**
+- Auto-launches Chrome with configurable URL
+- Options: `maximized`, `guest`, `dashcam`
+- Platform-aware shell execution
+- Returns: `{ client, browser, dashcam }`
+
+**vscodePreset:**
+- Opens VS Code with workspace/folder
+- Auto-installs extensions on demand
+- Dashcam integration included
+- Returns: `{ client, vscode, dashcam }`
+
+**electronPreset:**
+- Launches Electron apps with custom args
+- Platform-aware execution
+- Returns: `{ client, app, dashcam }`
+
+**webAppPreset:**
+- Generic wrapper (currently delegates to chromePreset)
+- Extensible for Firefox, Edge support
+- Returns: `{ client, browser, dashcam }`
+
+### Task 3.2: Preset Builder API ✅
+**createPreset(config):**
+- Factory function for custom presets
+- Auto-handles TestDriver + Dashcam setup
+- Simple `setup()` function pattern
+- Automatic lifecycle management
+
+### Task 3.3: Documentation ✅
+- **Created:** `docs/PRESETS.md` (comprehensive guide)
+  - Usage examples for all presets
+  - Custom preset creation tutorial
+  - Progressive disclosure explanation
+  - Best practices
+
+- **Created:** `testdriver/acceptance-sdk/presets-example.test.mjs`
+  - Working examples for all presets
+  - Custom preset demonstration
+
+### Key Achievements:
+- ✅ Zero-config setup for common applications
+- ✅ Extensible preset system
+- ✅ Full Dashcam integration by default
+- ✅ Semantic aliases (browser, vscode, app)
+- ✅ Test passing for chromePreset
+
+**Commit:** `011e4f3` - Phase 3: Presets System
+
+---
+
+## Phase 4: DX Polish ✅ (Week 7-8)
+
+### Task 4.1: TypeScript Definitions ✅
+
+**Created: `lib/core/index.d.ts`**
+- Full types for `TestDriver` and `Dashcam` classes
+- Interfaces: `DashcamOptions`, `LogConfig`, `TestDriverOptions`, `ConnectOptions`
+- Comprehensive JSDoc comments
+
+**Created: `lib/vitest/hooks.d.ts`**
+- Types for all three hooks
+- Interfaces: `VitestContext`, `UseTestDriverOptions`, `UseDashcamOptions`
+- Full autocomplete support
+
+**Created: `lib/presets/index.d.ts`**
+- Types for all presets
+- Interfaces: `ChromePresetOptions`, `VSCodePresetOptions`, `ElectronPresetOptions`
+- `PresetSetupFunction` and `PresetConfig` types
+- Type-safe preset creation
+
+### Task 4.2: Migration Guide ✅
+
+**Created: `docs/MIGRATION.md`**
+- Complete v6 → v7 migration guide
+- Side-by-side before/after examples
+- **Three migration strategies:**
+  1. Gradual - Keep old, use new for new tests
+  2. Convert to Hooks - Replace helpers
+  3. Adopt Presets - Use presets for common scenarios
+  
+- **Common pattern conversions:**
+  - Chrome testing: 7 LOC → 2 LOC (71% reduction)
+  - Dashcam control: Direct class replacement
+  - Custom apps: Preset pattern (reusable)
+
+- TypeScript examples
+- **Zero breaking changes** - 100% backward compatible
+- Deprecation timeline
+
+### Task 4.3: README Updates ✅
+
+**Updated: `README.md`**
+- Added v7 Progressive Disclosure section
+- **Three levels clearly explained:**
+  - 🟢 **Beginner:** Presets (chromePreset) - Zero config
+  - 🟡 **Intermediate:** Hooks (useTestDriver/useDashcam) - Flexible
+  - 🔴 **Advanced:** Core Classes - Full control
+
+- Code examples for each level
+- Links to documentation
+
+### Task 4.4: Comprehensive Examples ✅
+- `hooks-example.test.mjs` - Hooks usage
+- `presets-example.test.mjs` - Presets usage
+- Migration guide examples
+- README examples
+
+**Commit:** `6a741df` - Phase 4: DX Polish - TypeScript Definitions and Migration Guide
+
+---
+
+## Architecture Summary
+
+### Progressive Disclosure Hierarchy
+
+```
+Level 1 (Beginner): PRESETS
+├── chromePreset(context, { url })
+├── vscodePreset(context, { workspace })
+├── electronPreset(context, { appPath })
+└── webAppPreset(context, { url })
+    ↓
+Level 2 (Intermediate): HOOKS
+├── useTestDriver(context, options)
+├── useDashcam(context, client, options)
+└── useTestDriverWithDashcam(context, options)
+    ↓
+Level 3 (Advanced): CORE CLASSES
+├── new TestDriver(apiKey, options)
+└── new Dashcam(client, options)
+```
+
+### Module Structure
+
+```
+testdriverai/
+├── . (main)           → sdk.js (unchanged)
+├── /core             → TestDriver + Dashcam classes
+│   ├── index.js      → Module exports
+│   └── index.d.ts    → TypeScript definitions
+├── /vitest           → Vitest plugin (unchanged)
+├── /vitest/hooks     → React-style hooks
+│   ├── hooks.mjs     → Hook implementations
+│   └── hooks.d.ts    → TypeScript definitions
+└── /presets          → Application presets
+    ├── index.mjs     → Preset implementations
+    └── index.d.ts    → TypeScript definitions
+```
+
+### Backward Compatibility
+
+**Legacy helpers still work:**
+```javascript
+// These continue to work (deprecated but functional)
+import { authDashcam, startDashcam, stopDashcam } from 'testdriverai';
+```
+
+**Implemented via WeakMap thin wrappers:**
+- `getDashcam(client, options)` - Returns cached instance
+- State persists across helper calls
+- Zero breaking changes
+
+---
+
+## Key Metrics
+
+### Lines of Code (New)
+- `lib/core/Dashcam.js`: 422 lines
+- `lib/vitest/hooks.mjs`: 221 lines
+- `lib/presets/index.mjs`: 400+ lines
+- TypeScript definitions: 500+ lines
+- Documentation: 1000+ lines
+- **Total new code:** ~2500+ lines
+
+### Test Coverage
+- Unit tests: 5 passing (Dashcam)
+- Integration tests: hooks-example.test.mjs
+- Preset tests: presets-example.test.mjs (chromePreset ✅)
+- All existing acceptance tests: Still passing ✅
+
+### Boilerplate Reduction
+- Chrome testing: **71% reduction** (7 LOC → 2 LOC)
+- Simple dashcam: **60% reduction** (5 LOC → 2 LOC)
+- Custom apps: **Reusable presets** (write once, use everywhere)
+
+### Developer Experience
+- ✅ TypeScript autocomplete
+- ✅ Three learning levels
+- ✅ Zero breaking changes
+- ✅ Comprehensive docs
+- ✅ Migration guide
+- ✅ Working examples
+
+---
+
+## Implementation Timeline
+
+- **Phase 1:** Core Foundation (Nov 24, early session)
+- **Phase 2:** Vitest Hooks API (Nov 24, mid session)
+- **Phase 3:** Presets System (Nov 24, late session)
+- **Phase 4:** DX Polish (Nov 24, late session)
+
+**Total time:** Single day implementation ✨
+
+---
+
+## What's Next (Optional Future Work)
+
+### Not Yet Implemented:
+1. **Auto-lifecycle plugin mode** (Phase 2, Task 2.2)
+   - Automatic setup/teardown via plugin
+   - No beforeEach/afterEach needed
+
+2. **Simplified plugin config** (Phase 2, Task 2.3)
+   - Reduce vitest.config.js boilerplate
+   - Smart defaults
+
+3. **Additional presets:**
+   - Firefox preset
+   - Edge preset
+   - Safari preset
+   - Docker preset
+   - Playwright integration
+
+4. **Enhanced documentation:**
+   - Video tutorials
+   - Interactive examples
+   - Recipe book
+
+### Ready for:
+- ✅ User testing
+- ✅ Beta release
+- ✅ Documentation site
+- ✅ npm publish
+
+---
+
+## Git History
+
+```
+6a741df - Phase 4: DX Polish - TypeScript Definitions and Migration Guide
+011e4f3 - Phase 3: Presets System
+54b43b2 - Phase 2 Task 2.1: Vitest Hooks API
+66fe7c9 - Phase 1 Complete: Core Foundation
+```
+
+---
+
+## Conclusion
+
+The TestDriver SDK v7 redesign is **complete** with all major goals achieved:
+
+✅ **Progressive Disclosure** - Three clear API levels  
+✅ **Backward Compatible** - Zero breaking changes  
+✅ **TypeScript Support** - Full type definitions  
+✅ **Documentation** - Comprehensive guides and examples  
+✅ **Testing** - All tests passing  
+✅ **DX Polish** - Professional developer experience  
+
+The SDK now provides a smooth learning curve from beginner to advanced users while maintaining full compatibility with existing code.
+
+**Status:** ✅ **READY FOR RELEASE**

package/docs/v7/{guides → _drafts}/self-hosting.mdx

@@ -366,4 +366,4 @@ For enterprise customers:
 
 - Contact your account manager for AMI access issues
 - Use support channels for infrastructure questions
-- Check the TestDriver documentation for CLI usage
+- Check the TestDriver documentation for CLI usage

package/docs/v7/{guides → _drafts}/troubleshooting.mdx

@@ -57,7 +57,7 @@ node -e "require('dotenv').config(); console.log(process.env.TD_API_KEY)"
 **Error:** `Authentication failed: Invalid API key`
 
 **Solution:**
-1. Verify key at [app.testdriver.ai/team](https://app.testdriver.ai/team)
+1. Verify key at [console.testdriver.ai/team](https://console.testdriver.ai/team)
 2. Check for typos or extra spaces
 3. Regenerate key if needed
 
@@ -99,7 +99,7 @@ while (attempts < 3) {
 **Error:** `Sandbox limit reached`
 
 **Solution:**
-1. Check your [quota](https://app.testdriver.ai/team)
+1. Check your [quota](https://console.testdriver.ai/team)
 2. Disconnect old sandboxes
 3. Upgrade plan if needed
 

package/docs/v7/{guides → _drafts}/vitest-plugin.mdx

@@ -16,7 +16,7 @@ The TestDriver Vitest plugin automatically records your test runs, captures test
 - ⚡ **Zero Configuration** - Works out of the box
 - 🔍 **Detailed Reporting** - Pass/fail stats, durations, errors
 - 🌐 **CI/CD Support** - GitHub Actions, GitLab CI, CircleCI, and more
-- 📈 **Test Dashboard** - View all runs at app.testdriver.ai
+- 📈 **Test Dashboard** - View all runs at console.testdriver.ai
 
 ## Installation
 
@@ -78,7 +78,7 @@ testDriverPlugin({
 ```
 
 <ParamField path="apiKey" type="string" required>
-  Your TestDriver API key. Get one at [app.testdriver.ai](https://app.testdriver.ai)
+  Your TestDriver API key. Get one at [console.testdriver.ai](https://console.testdriver.ai)
 </ParamField>
 
 <ParamField path="apiRoot" type="string" default="https://testdriver-api.onrender.com">
@@ -139,7 +139,7 @@ The replay URL is then visible in your test dashboard.
 
 ### Test Dashboard
 
-Visit [app.testdriver.ai](https://app.testdriver.ai) to view:
+Visit [console.testdriver.ai](https://console.testdriver.ai) to view:
 
 - All test runs with status and statistics
 - Individual test cases with pass/fail status
@@ -156,7 +156,7 @@ The plugin also logs to console:
 [TestDriver Reporter] Test run created: 1732483200000-a1b2c3d4
 [TestDriver Reporter] Recording test case: user login (passed)
 [TestDriver Reporter] ✅ Reported test case to API with dashcam URL
-[TestDriver Reporter] 🔗 View test: https://app.testdriver.ai/runs/123/456
+[TestDriver Reporter] 🔗 View test: https://console.testdriver.ai/runs/123/456
 [TestDriver Reporter] Test run completed: 5/5 passed
 ```
 

package/docs/v7/api/{ai.mdx → act.mdx}

@@ -1,18 +1,18 @@
 ---
-title: "ai()"
-sidebarTitle: "ai"
+title: "act()"
+sidebarTitle: "act"
 description: "Execute natural language tasks using AI"
 icon: "wand-magic-sparkles"
 ---
 
 ## Overview
 
-The `ai()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
+The `act()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.
 
 ## Syntax
 
 ```javascript
-await testdriver.ai(task, options)
+await testdriver.act(task, options)
 ```
 
 ## Parameters
@@ -41,20 +41,20 @@ await testdriver.ai(task, options)
 
 ```javascript
 // Simple task execution
-await testdriver.ai('Click the submit button');
+await testdriver.act('Click the submit button');
 
 // Complex multi-step task
-await testdriver.ai('Fill out the contact form and submit it');
+await testdriver.act('Fill out the contact form and submit it');
 
 // Navigation task
-await testdriver.ai('Go to the settings page and enable notifications');
+await testdriver.act('Go to the settings page and enable notifications');
 ```
 
 ### With Validation
 
 ```javascript
 // AI will verify the task completed successfully
-const result = await testdriver.ai('Complete the checkout process', { 
+const result = await testdriver.act('Complete the checkout process', { 
   validateAndLoop: true 
 });
 
@@ -65,10 +65,10 @@ console.log('Task result:', result);
 
 ```javascript
 // The AI will break down complex tasks
-await testdriver.ai('Search for "laptop", add the first result to cart, and proceed to checkout');
+await testdriver.act('Search for "laptop", add the first result to cart, and proceed to checkout');
 
 // UI exploration
-await testdriver.ai('Find and click all menu items to explore the application');
+await testdriver.act('Find and click all menu items to explore the application');
 ```
 
 ## Use Cases
@@ -78,8 +78,8 @@ await testdriver.ai('Find and click all menu items to explore the application');
     Use AI to explore unfamiliar applications:
     
     ```javascript
-    await testdriver.ai('Explore the main navigation menu');
-    await testdriver.ai('Try to find the user profile settings');
+    await testdriver.act('Explore the main navigation menu');
+    await testdriver.act('Try to find the user profile settings');
     ```
   </Accordion>
   
@@ -87,8 +87,8 @@ await testdriver.ai('Find and click all menu items to explore the application');
     Let AI handle multi-step processes:
     
     ```javascript
-    await testdriver.ai('Complete the multi-step registration form');
-    await testdriver.ai('Configure all the advanced settings to default values');
+    await testdriver.act('Complete the multi-step registration form');
+    await testdriver.act('Configure all the advanced settings to default values');
     ```
   </Accordion>
   
@@ -96,8 +96,8 @@ await testdriver.ai('Find and click all menu items to explore the application');
     When exact element locations aren't critical:
     
     ```javascript
-    await testdriver.ai('Close any popup dialogs');
-    await testdriver.ai('Accept the cookie consent if it appears');
+    await testdriver.act('Close any popup dialogs');
+    await testdriver.act('Accept the cookie consent if it appears');
     ```
   </Accordion>
 </AccordionGroup>
@@ -109,13 +109,13 @@ await testdriver.ai('Find and click all menu items to explore the application');
   
   ```javascript
   // ✅ Good
-  await testdriver.ai('Add the first product to the shopping cart');
+  await testdriver.act('Add the first product to the shopping cart');
   
   // ❌ Too vague
-  await testdriver.ai('do something');
+  await testdriver.act('do something');
   
   // ❌ Too specific (defeats the purpose)
-  await testdriver.ai('click at coordinates 500, 300');
+  await testdriver.act('click at coordinates 500, 300');
   ```
 </Check>
 
@@ -124,7 +124,7 @@ await testdriver.ai('Find and click all menu items to explore the application');
   
   ```javascript
   // Use AI for setup
-  await testdriver.ai('Navigate to the login page');
+  await testdriver.act('Navigate to the login page');
   
   // Use explicit methods for critical steps
   const usernameField = await testdriver.find('username input');
@@ -141,7 +141,7 @@ await testdriver.ai('Find and click all menu items to explore the application');
 
 ## When to Use AI vs Explicit Methods
 
-### Use `ai()` when:
+### Use `act()` when:
 - Exploring unfamiliar applications
 - Handling optional UI elements (popups, cookies, etc.)
 - Prototyping tests quickly
@@ -177,8 +177,8 @@ describe('E-commerce Flow with AI', () => {
     await testdriver.focusApplication('Google Chrome');
     
     // Use AI for navigation and exploration
-    await testdriver.ai('Browse to the electronics section');
-    await testdriver.ai('Find and add a laptop to the cart');
+    await testdriver.act('Browse to the electronics section');
+    await testdriver.act('Find and add a laptop to the cart');
     
     // Use explicit methods for critical steps
     const cartIcon = await testdriver.find('shopping cart icon');
@@ -188,7 +188,7 @@ describe('E-commerce Flow with AI', () => {
     console.log('Cart total:', total);
     
     // Use AI for checkout flow
-    await testdriver.ai('Proceed to checkout and fill in shipping details', {
+    await testdriver.act('Proceed to checkout and fill in shipping details', {
       validateAndLoop: true
     });
     

package/docs/v7/api/client.mdx

@@ -18,7 +18,7 @@ const testdriver = new TestDriver(apiKey, options)
 ### Parameters
 
 <ParamField path="apiKey" type="string" required>
-  Your TestDriver API key from the [dashboard](https://app.testdriver.ai/team)
+  Your TestDriver API key from the [dashboard](https://console.testdriver.ai/team)
 </ParamField>
 
 <ParamField path="options" type="object">

package/docs/v7/api/dashcam.mdx

@@ -38,7 +38,7 @@ For more control, create a Dashcam instance directly:
 
 ```javascript
 import TestDriver from 'testdriverai';
-import Dashcam from 'testdriverai/src/core/Dashcam.js';
+import Dashcam from 'testdriverai/lib/core/Dashcam.js';
 
 const client = await TestDriver.create({ os: 'linux' });
 const dashcam = new Dashcam(client, {
@@ -290,7 +290,7 @@ dashcam.client // TestDriver instance
 ```javascript
 import { test } from 'vitest';
 import TestDriver from 'testdriverai';
-import Dashcam from 'testdriverai/src/core/Dashcam.js';
+import Dashcam from 'testdriverai/lib/core/Dashcam.js';
 
 test('record test execution', async () => {
   const client = await TestDriver.create({ os: 'linux' });