testdriverai 7.1.0 → 7.1.2

package/docs/v7/_drafts/auto-cache-key.mdx

@@ -0,0 +1,167 @@
+# Auto-Generated Cache Keys from File Hash
+
+## Overview
+
+When you create a TestDriver instance without providing an explicit `cacheKey`, the SDK will automatically generate one based on the SHA-256 hash of the calling file. This provides automatic cache invalidation when your test file changes, while enabling cache hits for identical test runs.
+
+## How It Works
+
+1. **Stack Trace Analysis**: When `TestDriver()` is called, the SDK analyzes the call stack to find the caller file
+2. **File Hashing**: The content of the caller file is hashed using SHA-256
+3. **Cache Key Generation**: The first 16 characters of the hash are used as the cache key
+4. **Automatic Updates**: When the test file is modified, the hash changes, automatically invalidating the cache
+
+## Benefits
+
+- ✅ **No Manual Cache Management**: Cache keys are automatically generated and updated
+- ✅ **File-Scoped Caching**: All tests in the same file share the same cache
+- ✅ **Automatic Invalidation**: Cache is invalidated when the test file changes
+- ✅ **Explicit Override**: You can still provide a manual `cacheKey` if needed
+
+## Usage Examples
+
+### Automatic Cache Key (Recommended)
+
+```javascript
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+test('login test', async (context) => {
+  // No cacheKey provided - will be auto-generated from this file's hash
+  const testdriver = TestDriver(context, { 
+    headless: true 
+  });
+  
+  // Cache key is automatically set based on this file
+  console.log(testdriver.options.cacheKey); // e.g., "4cae7be040f293b9"
+  
+  const button = await testdriver.find('login button');
+  // Subsequent calls in this test file will use the same cache
+});
+```
+
+### Explicit Cache Key (Override)
+
+```javascript
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+test('login test', async (context) => {
+  // Explicit cacheKey provided - auto-generation is skipped
+  const testdriver = TestDriver(context, { 
+    headless: true,
+    cacheKey: 'my-custom-key-v1'
+  });
+  
+  console.log(testdriver.options.cacheKey); // "my-custom-key-v1"
+  
+  const button = await testdriver.find('login button');
+});
+```
+
+## Cache Behavior
+
+### With Auto-Generated Key
+
+1. **First Run**: Creates cache entries with key = hash of test file
+2. **Subsequent Runs** (file unchanged): Cache hits
+3. **After File Modification**: New hash = new cache key = cache miss
+
+### Cache Hit Example
+
+```javascript
+// File: login.test.mjs (hash: 4cae7be040f293b9)
+
+const testdriver = TestDriver(context);
+// Auto-generated cacheKey: "4cae7be040f293b9"
+
+const button1 = await testdriver.find('login button'); // Cache MISS (first time)
+const button2 = await testdriver.find('login button'); // Cache HIT (same file, same test run)
+```
+
+After modifying the file (adding a comment, changing test logic, etc.):
+
+```javascript
+// File: login.test.mjs (hash: 7f3d9a2b1c5e8f6a) <- changed!
+
+const testdriver = TestDriver(context);
+// Auto-generated cacheKey: "7f3d9a2b1c5e8f6a" <- different from before
+
+const button1 = await testdriver.find('login button'); // Cache MISS (new hash)
+```
+
+## Debug Mode
+
+To see the auto-generated cache key in debug logs:
+
+```bash
+# Set environment variable
+export TD_DEBUG=1
+
+# Or in your test
+process.env.TD_DEBUG = '1';
+```
+
+With debug mode enabled, you'll see:
+```
+🔍 find() threshold: 0.05 (cache ENABLED, cacheKey: 4cae7be040f293b9 (auto-generated from file hash))
+```
+
+## Implementation Details
+
+### Stack Trace Filtering
+
+The auto-generation skips the following in the stack trace to find the actual test file:
+- `sdk.js` (TestDriver SDK)
+- `hooks.mjs` / `hooks.js` (Vitest hooks)
+- `node_modules` (dependencies)
+- `node:internal` (Node.js internals)
+
+### File Path Handling
+
+The implementation handles both:
+- Regular file paths: `/Users/you/project/test.mjs`
+- File URL format: `file:///Users/you/project/test.mjs`
+
+### Hash Format
+
+- Algorithm: SHA-256
+- Output: First 16 hexadecimal characters (e.g., `4cae7be040f293b9`)
+- Collision probability: Effectively zero for practical purposes
+
+## When to Use Manual Cache Keys
+
+Consider using manual `cacheKey` values when:
+
+1. **Cross-File Caching**: You want to share cache across multiple test files
+2. **Version-Based Caching**: You want explicit control over cache invalidation
+3. **CI/CD Integration**: You want to tie caching to build numbers or git commits
+
+Example:
+
+```javascript
+const cacheKey = \`test-suite-\${process.env.GIT_COMMIT}\`;
+const testdriver = TestDriver(context, { cacheKey });
+```
+
+## Migration from Manual Keys
+
+If you currently use manual cache keys:
+
+### Before
+```javascript
+const testdriver = TestDriver(context, { 
+  cacheKey: 'login-test-v1' 
+});
+```
+
+### After (automatic)
+```javascript
+// Just remove the cacheKey - it will be auto-generated!
+const testdriver = TestDriver(context);
+```
+
+The cache will automatically invalidate when the test file changes, which is usually the desired behavior.
+
+## See Also
+
+- [SDK_README.md](./SDK_README.md) - Cache configuration options
+- [CACHE_ARCHITECTURE.md](../api/CACHE_ARCHITECTURE.md) - Cache system architecture

package/docs/v7/{guides → _drafts}/caching-selectors.mdx

@@ -9,12 +9,76 @@ icon: "crosshairs"
 
 The Selector Cache stores element locations on the server, so `.find()` calls can skip the AI vision analysis.
 
+**Important:** Selector caching is **disabled by default** as of v7.1. You must provide a `cacheKey` to enable caching.
+
 This provides:
 - ⚡ **Up to 10x faster** - Skip AI vision analysis
 - 💰 **Lower AI costs** - Fewer vision API calls
 - 🎯 **Consistent results** - Same UI = same coordinates
 - 📊 **Metrics tracking** - See cache hit rates in console
 
+## Enabling the Cache
+
+### Auto-Generated Cache Keys (Recommended)
+
+TestDriver automatically generates cache keys based on your test file:
+
+```javascript
+// Cache automatically enabled - uses file hash as cache key
+const button = await testdriver.find('submit button');
+// Cache key: "a1b2c3d4e5f6..." (first 16 chars of file SHA-256)
+```
+
+**Benefits:**
+- ✅ **Per-file isolation** - Each test file has its own cache
+- ✅ **Auto-invalidation** - Cache updates when test code changes
+- ✅ **Zero configuration** - Works out of the box
+- ✅ **Safe** - No cross-test pollution
+
+### Custom Cache Keys
+
+Provide your own cache key for more control:
+
+```javascript
+// Custom cache key
+const button = await testdriver.find('submit button', {
+  cacheKey: 'my-test-key'
+});
+
+// Share cache across tests
+const button = await testdriver.find('submit button', {
+  cacheKey: 'shared-submit-button'
+});
+```
+
+### Global Cache Key
+
+Enable caching for all finds in your test:
+
+```javascript
+const client = new TestDriver(apiKey, {
+  cacheKey: 'my-global-key'  // All finds will use this cache
+});
+
+// Now all finds are cached
+await testdriver.find('button 1');  // Uses 'my-global-key'
+await testdriver.find('button 2');  // Uses 'my-global-key'
+```
+
+### Disable Auto-Cache
+
+If you don't want automatic caching:
+
+```javascript
+// Disable cache for this find
+await testdriver.find('button', { cacheThreshold: -1 });
+
+// Or use a threshold of -1 globally
+const client = new TestDriver(apiKey, {
+  cacheThreshold: { find: -1, findAll: -1 }
+});
+```
+
 ## How It Works
 
 ```mermaid
@@ -65,22 +129,32 @@ The selector cache uses a three-tier matching system:
 
 ## Controlling Cache Threshold
 
-Adjust similarity threshold per call:
+Adjust similarity threshold when cache is enabled:
 
 ```javascript
 // Default: 95% similarity (5% difference allowed)
-await testdriver.find('submit button');
+await testdriver.find('submit button', { cacheKey: 'test-1' });
 
 // Stricter: 99% similarity (1% difference allowed)
-await testdriver.find('submit button', { threshold: 0.01 });
+await testdriver.find('submit button', { 
+  cacheKey: 'test-1',
+  cacheThreshold: 0.01 
+});
 
 // More lenient: 90% similarity (10% difference allowed)
-await testdriver.find('submit button', { threshold: 0.10 });
+await testdriver.find('submit button', { 
+  cacheKey: 'test-1',
+  cacheThreshold: 0.10 
+});
 
 // Disable cache: force fresh AI analysis
-await testdriver.find('submit button', { threshold: -1 });
+await testdriver.find('submit button', { cacheThreshold: -1 });
 ```
 
+<Note>
+  `cacheThreshold` only works when caching is enabled via `cacheKey` or global config.
+</Note>
+
 ## Cache Filtering
 
 The selector cache automatically filters by:
@@ -126,13 +200,19 @@ test('find element', async (context) => {
     url: 'https://example.com'
   });
   
+  // Auto-cache enabled (uses file hash as cache key)
   // First call: AI vision analysis, saves to cache
   const button = await testdriver.find('More information link');
-  console.log('Cache hit:', button.cacheHit); // false
+  console.log('Cache hit:', button.cacheHit); // false (first run)
   
   // Second call: uses cache (instant)
   const button2 = await testdriver.find('More information link');
-  console.log('Cache hit:', button2.cacheHit); // true
+  console.log('Cache hit:', button2.cacheHit); // true (cache hit)
+  
+  // Custom cache key
+  const button3 = await testdriver.find('submit button', { 
+    cacheKey: 'my-button' 
+  });
 });
 ```
 
@@ -142,14 +222,20 @@ test('find element', async (context) => {
 test('strict vs lenient matching', async (context) => {
   const { testdriver } = await chrome(context, { url });
   
-  // Strict: 99% similarity required
-  const elem1 = await testdriver.find('button', { threshold: 0.01 });
+  // Strict: 99% similarity required (auto-cache key)
+  const elem1 = await testdriver.find('button', { cacheThreshold: 0.01 });
   
   // Lenient: 90% similarity acceptable
-  const elem2 = await testdriver.find('button', { threshold: 0.10 });
+  const elem2 = await testdriver.find('button', { cacheThreshold: 0.10 });
+  
+  // Bypass cache entirely (no cacheKey needed)
+  const elem3 = await testdriver.find('button', { cacheThreshold: -1 });
   
-  // Bypass cache entirely
-  const elem3 = await testdriver.find('button', { threshold: -1 });
+  // Custom cache key with threshold
+  const elem4 = await testdriver.find('button', {
+    cacheKey: 'my-button',
+    cacheThreshold: 0.05
+  });
 });
 ```
 
@@ -159,12 +245,21 @@ test('strict vs lenient matching', async (context) => {
 test('monitor cache performance', async (context) => {
   const { testdriver } = await chrome(context, { url });
   
+  // Auto-cache enabled
   const element = await testdriver.find('submit button');
   
   if (element.cacheHit) {
     console.log('✅ Cache hit - instant response');
+    console.log('Cache strategy:', element.cacheStrategy);
+    console.log('Cache age:', element.cacheCreatedAt);
   } else {
     console.log('⏱️  Cache miss - AI analysis performed');
+    console.log('New cache entry created');
+  }
+  
+  // Check similarity score
+  if (element.similarity) {
+    console.log(`Similarity: ${(element.similarity * 100).toFixed(1)}%`);
   }
 });
 ```
@@ -174,17 +269,30 @@ test('monitor cache performance', async (context) => {
 ### 1. Use Appropriate Thresholds
 
 ```javascript
-// Stable UI: strict threshold
-await testdriver.find('logo', { threshold: 0.01 });
+// Stable UI: strict threshold (auto-cache)
+await testdriver.find('logo', { cacheThreshold: 0.01 });
 
 // Dynamic UI: lenient threshold
-await testdriver.find('news feed item', { threshold: 0.10 });
+await testdriver.find('news feed item', { cacheThreshold: 0.10 });
 
 // Always fresh: disable cache
-await testdriver.find('timestamp', { threshold: -1 });
+await testdriver.find('timestamp', { cacheThreshold: -1 });
 ```
 
-### 2. Monitor Cache Performance
+### 2. Choose Cache Key Strategy
+
+```javascript
+// Auto-cache (recommended) - per-file isolation
+await testdriver.find('button');
+
+// Custom key - share across tests
+await testdriver.find('button', { cacheKey: 'global-submit' });
+
+// Global key - all finds in test
+const testdriver = new TestDriver(apiKey, {
+  cacheKey: 'test-suite-1'
+});
+```
 
 Check [console.testdriver.ai](https://console.testdriver.ai) regularly to:
 - See cache hit rates

package/docs/v7/_drafts/dashcam-title-feature.mdx

@@ -0,0 +1,89 @@
+# Dashcam Recording Titles
+
+## Overview
+
+Dashcam recordings now automatically use meaningful titles instead of the generic "Dashcam Recording" label.
+
+## Automatic Title Generation
+
+When using TestDriver with Vitest, the dashcam recording title is automatically generated from:
+1. **Test file name** - Extracted from the test file path
+2. **Test name** - The name of the test case
+
+### Example
+
+For a test file `login.test.mjs` with test case `"should login successfully"`:
+```
+Recording title: "login - should login successfully"
+```
+
+For standalone usage without test context:
+```
+Recording title: "Recording 2025-12-02 14:30:45"
+```
+
+## Custom Titles
+
+You can set a custom title before starting the dashcam recording:
+
+### With Vitest Integration
+
+```javascript
+import { test } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest';
+
+test('my test', async (context) => {
+  const testdriver = TestDriver(context, { headless: true });
+  
+  // Set custom title before dashcam starts
+  testdriver.dashcam.setTitle('My Custom Recording Title');
+  
+  // Start recording (provision methods start dashcam automatically)
+  await testdriver.provision.chrome({ url: 'https://example.com' });
+  
+  await testdriver.find('button').click();
+});
+```
+
+### Direct SDK Usage
+
+```javascript
+const TestDriver = require('testdriverai');
+
+const client = new TestDriver(process.env.TD_API_KEY);
+await client.connect();
+
+// Set custom title
+client.dashcam.setTitle('Integration Test - Payment Flow');
+
+// Start recording
+await client.dashcam.start();
+
+await client.provision.chrome({ url: 'https://example.com' });
+await client.find('Checkout button').click();
+
+// Stop recording and get URL
+const dashcamUrl = await client.dashcam.stop();
+console.log('Recording:', dashcamUrl);
+```
+
+## Constructor Option
+
+You can also pass a title when creating the Dashcam instance:
+
+```javascript
+const { Dashcam } = require('testdriverai/core');
+
+const dashcam = new Dashcam(client, {
+  title: 'Custom Title',
+  autoStart: true
+});
+```
+
+## Implementation Details
+
+- **Default title generation** uses test context (`__vitestContext`) when available
+- **Test file names** are cleaned (removes `.test`, `.spec`, file extensions)
+- **Fallback** to ISO timestamp if no test context is available
+- **Title escaping** handles special characters in shell commands properly
+- **Cross-platform** support for Windows (PowerShell) and Linux/Mac (bash/zsh)