@testdriverai/agent 7.8.0-canary.10

package/docs/v7/_drafts/screenshot.mdx

@@ -0,0 +1,155 @@
+---
+title: "screenshot()"
+sidebarTitle: "screenshot"
+description: "Capture a screenshot of the current screen"
+icon: "camera"
+---
+
+## Overview
+
+Capture a screenshot of the current sandbox screen. Returns a base64 encoded PNG, or saves directly to a file and returns the filepath.
+
+## Syntax
+
+```javascript
+// Options object (recommended)
+await testdriver.screenshot(options)
+
+// Legacy positional arguments
+await testdriver.screenshot(scale, silent, mouse)
+```
+
+## Parameters
+
+<ParamField path="options" type="object">
+  Options object for screenshot capture
+</ParamField>
+
+<ParamField path="options.scale" type="number" default="1">
+  Scale factor for the screenshot (1 = original size, 0.5 = half size, etc.)
+</ParamField>
+
+<ParamField path="options.silent" type="boolean" default="false">
+  Whether to suppress logging output
+</ParamField>
+
+<ParamField path="options.mouse" type="boolean" default="false">
+  Whether to include the mouse cursor in the screenshot
+</ParamField>
+
+<ParamField path="options.path" type="string">
+  File path to save the screenshot. If provided, the screenshot is saved to this file and the filepath is returned instead of base64 data. Directories are created automatically if they don't exist.
+</ParamField>
+
+## Returns
+
+`Promise<string>` - Base64 encoded PNG screenshot, or the filepath if `options.path` was provided.
+
+## Examples
+
+### Basic Screenshot (Base64)
+
+```javascript
+// Capture a screenshot and get base64 data
+const screenshot = await testdriver.screenshot();
+
+// Write to file manually
+import fs from 'fs';
+fs.writeFileSync('screenshot.png', Buffer.from(screenshot, 'base64'));
+```
+
+### Save Directly to File
+
+```javascript
+// Save screenshot directly to a file (returns filepath)
+const filepath = await testdriver.screenshot({ path: './screenshots/test.png' });
+console.log(`Screenshot saved to: ${filepath}`);
+```
+
+### With Mouse Cursor
+
+```javascript
+// Include mouse cursor in screenshot
+const screenshot = await testdriver.screenshot({ mouse: true });
+
+// Or save to file with mouse cursor
+const filepath = await testdriver.screenshot({ 
+  path: './debug/with-cursor.png',
+  mouse: true 
+});
+```
+
+### Scaled Screenshot
+
+```javascript
+// Capture at half size (useful for reducing file size)
+const screenshot = await testdriver.screenshot({ scale: 0.5 });
+
+// Capture at double size
+const filepath = await testdriver.screenshot({ 
+  path: './hires.png',
+  scale: 2 
+});
+```
+
+### Silent Mode
+
+```javascript
+// Capture without logging output
+const screenshot = await testdriver.screenshot({ silent: true });
+```
+
+### Legacy Usage
+
+```javascript
+// Legacy positional arguments still work
+const screenshot = await testdriver.screenshot(1, false, true);
+// Equivalent to: screenshot({ scale: 1, silent: false, mouse: true })
+```
+
+## Use Cases
+
+### Debugging Test Failures
+
+```javascript
+it('should complete checkout', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: 'https://shop.example.com' });
+
+  try {
+    await testdriver.find('Checkout button').click();
+    await testdriver.assert('Order confirmation is visible');
+  } catch (error) {
+    // Save screenshot on failure for debugging
+    await testdriver.screenshot({ path: './failures/checkout-failed.png' });
+    throw error;
+  }
+});
+```
+
+### Visual Documentation
+
+```javascript
+// Capture screenshots at each step for documentation
+await testdriver.screenshot({ path: './docs/step1-login.png' });
+await testdriver.find('Login button').click();
+await testdriver.screenshot({ path: './docs/step2-dashboard.png' });
+```
+
+### Comparing States
+
+```javascript
+// Capture before and after states
+const before = await testdriver.screenshot();
+await testdriver.find('Toggle dark mode').click();
+const after = await testdriver.screenshot();
+
+// Both are base64 - can be compared or stored
+```
+
+## Notes
+
+- Screenshots are captured from the sandbox's virtual display
+- The base64 string does not include a data URI prefix (raw base64)
+- When using `path`, directories are created automatically if they don't exist
+- File format is always PNG regardless of the file extension used

package/docs/v7/_drafts/sdk-awesome-logs.mdx

@@ -0,0 +1,468 @@
+# TestDriver SDK - AWESOME Logs 🎨
+
+Beautiful, emoji-rich logging with incredible DX that makes your test output a joy to read!
+
+## Features
+
+✨ **Rich Emojis & UTF-8** - Full emoji support now that dashcam supports UTF-8!  
+🎨 **Color-Coded Actions** - Different colors for different action types  
+⚡ **Performance Indicators** - Color-coded duration times (green < 100ms, yellow < 500ms, red > 500ms)  
+📊 **Progress Tracking** - Beautiful progress bars for multi-step operations  
+🔍 **Cache Visualization** - Clear indication of cache hits/misses  
+📍 **Coordinate Display** - See exactly where elements are found  
+⏱️ **Timing Information** - Elapsed time from test start on every log  
+📦 **Beautiful Headers** - Box-drawn section headers for organization  
+
+## Log Types
+
+### 🔍 Element Finding
+
+```javascript
+const element = await client.find("submit button");
+```
+
+**Output:**
+```
+[2.34s] 🔍 Found "submit button" · 📍 (682, 189) · ⏱️ 167ms · ⚡ cached
+```
+
+Features:
+- Green checkmark for successful finds
+- Coordinates with pin emoji
+- Duration with color coding
+- Cache status with lightning bolt
+
+### 👆 User Actions
+
+```javascript
+await element.click();
+await element.hover();
+await client.type("hello world");
+```
+
+**Output:**
+```
+[2.51s] 👆 Click "submit button"
+[2.67s] 👉 Hover "menu item"
+[2.89s] ⌨️ Type → hello world
+```
+
+Action emojis:
+- 👆 Click
+- 👆👆 Double-click
+- 🖱️ Right-click
+- 👉 Hover
+- ⌨️ Type
+- 🎹 Press Keys
+- 📜 Scroll
+
+### ✅ Assertions
+
+```javascript
+await client.assert("page title is Example Domain");
+```
+
+**Output:**
+```
+[3.12s] ✅ Assert "page title is Example Domain" · ✓ PASSED · ⏱️ 45ms
+[3.45s] ❌ Assert "login form visible" · ✗ FAILED · ⏱️ 1234ms
+```
+
+Color-coded results:
+- ✅ Green for PASSED
+- ❌ Red for FAILED
+- Performance-based duration coloring
+
+### ⚡ Cache Performance
+
+The SDK automatically logs cache performance:
+
+**Cache HIT:**
+```
+⚡ Cache HIT · 98.5% similar · image strategy
+```
+
+**Cache MISS:**
+```
+💤 Cache MISS · text strategy
+```
+
+### 🔌 Connection Status
+
+```javascript
+await client.connect();
+await client.disconnect();
+```
+
+**Output:**
+```
+🔌 Connected · Sandbox: i-0a1b2c3d4e5f6 · OS: windows
+🔌 Disconnected
+```
+
+### 📸 Screenshots
+
+```javascript
+await client.screenshot();
+```
+
+**Output:**
+```
+[5.67s] 📸 Screenshot · /tmp/testdriver-debug/screenshot-123.png · 245 KB
+```
+
+### 🚨 Errors
+
+Errors are beautifully formatted with context:
+
+```
+[8.90s] ❌ Element not found → Timeout after 5000ms
+```
+
+### 📈 Progress Tracking
+
+For multi-step operations:
+
+```
+Progress ████████████████████ 100% 5/5 · Processing complete
+```
+
+### 📊 Test Summary
+
+At the end of your test suite:
+
+```
+────────────────────────────────────────────────────────────
+✓ 12 passed │ ✗ 2 failed │ ⊘ 1 skipped │ 15 total │ ⏱️ 45.23s
+────────────────────────────────────────────────────────────
+```
+
+### 📦 Section Headers
+
+Organize your test output with beautiful headers:
+
+```
+╭────────────────────────────────────────────────────────────╮
+│ ✨ User Authentication Flow                                │
+╰────────────────────────────────────────────────────────────╯
+```
+
+## Configuration
+
+### Enable/Disable Logging
+
+```javascript
+const client = new TestDriver(apiKey, {
+  logging: true,  // Enable logging (default)
+});
+
+// Or disable later
+client.setLogging(false);
+```
+
+### Emojis vs Simple Symbols
+
+The formatter automatically uses emojis when available. If you need to disable emojis:
+
+```javascript
+const { formatter } = require('testdriverai/sdk-log-formatter');
+formatter.useEmojis = false; // Falls back to simple Unicode symbols
+```
+
+### Test Context Integration
+
+Integrate with Vitest or other test frameworks:
+
+```javascript
+import { describe, it, beforeEach } from 'vitest';
+
+describe('Login Tests', () => {
+  let client;
+
+  beforeEach(() => {
+    client = new TestDriver(process.env.TD_API_KEY);
+    
+    // Set test context for better logging
+    client.setTestContext({
+      file: 'login.test.js',
+      test: 'should log in successfully',
+      startTime: Date.now()
+    });
+  });
+
+  it('should log in successfully', async () => {
+    // All logs will now include elapsed time from test start
+    await client.connect();
+    // ...test code...
+  });
+});
+```
+
+## Examples
+
+### Basic Usage
+
+```javascript
+const TestDriver = require('testdriverai');
+
+const client = new TestDriver(process.env.TD_API_KEY, {
+  logging: true,
+});
+
+await client.connect();
+
+// Find and click - logs automatically
+const button = await client.find('submit button');
+await button.click();
+
+await client.disconnect();
+```
+
+**Output:**
+```
+🔌 Connected · Sandbox: i-0a1b2c3d · OS: windows
+🔍 Found "submit button" · 📍 (682, 189) · ⏱️ 167ms · ⚡ cached
+👆 Click "submit button"
+🔌 Disconnected
+```
+
+### Manual Formatting
+
+You can also use the formatter directly for custom logs:
+
+```javascript
+const { formatter } = require('testdriverai/sdk-log-formatter');
+
+// Format custom messages
+console.log(formatter.formatHeader('My Test Suite', '🧪'));
+console.log(formatter.formatAction('custom action', 'my element'));
+console.log(formatter.formatProgress(3, 10, 'Processing...'));
+console.log(formatter.formatDivider());
+```
+
+### Performance Monitoring
+
+Duration colors help you spot slow operations:
+
+- **🟢 Green** (< 100ms): Fast, optimal
+- **🟡 Yellow** (100-500ms): Acceptable
+- **🔴 Red** (> 500ms): Slow, may need optimization
+
+Example output:
+```
+⏱️ 45ms   ← Green (fast)
+⏱️ 234ms  ← Yellow (acceptable)
+⏱️ 1.2s   ← Red (slow)
+```
+
+### Cache Monitoring
+
+Track cache effectiveness in real-time:
+
+```javascript
+// Enable cache debugging
+process.env.VERBOSE = 'true';
+
+// Now you'll see detailed cache info
+const element = await client.find('button');
+```
+
+**Output:**
+```
+🔍 find() threshold: 0.05 (cache ENABLED)
+🔍 Found "button" · 📍 (500, 300) · ⏱️ 89ms · ⚡ cached
+
+Element Found:
+  Description: button
+  Coordinates: (500, 300)
+  Duration: 89ms
+  Cache Hit: ✅ YES
+  Cache Strategy: image
+  Similarity: 98.50%
+  Cache Age: 2s (created: 2024-11-18T15:30:45.123Z)
+  Pixel Diff: 1.23%
+```
+
+## Advanced Features
+
+### Test Lifecycle Tracking
+
+```javascript
+const { formatter } = require('testdriverai/sdk-log-formatter');
+
+// Test start
+console.log(formatter.formatTestStart('Login Flow'));
+
+// ... test code ...
+
+// Test end
+console.log(formatter.formatTestEnd('Login Flow', true, 2345));
+```
+
+**Output:**
+```
+▶️ Running: Login Flow
+
+✅ PASSED Login Flow · 2.35s
+```
+
+### Multi-Step Workflows
+
+```javascript
+const steps = [
+  'Navigate to login',
+  'Enter credentials',
+  'Submit form',
+  'Verify dashboard',
+  'Logout'
+];
+
+for (let i = 0; i < steps.length; i++) {
+  console.log(formatter.formatProgress(i + 1, steps.length, steps[i]));
+  // ... perform step ...
+}
+```
+
+**Output:**
+```
+Progress ████░░░░░░░░░░░░░░░░ 20% 1/5 · Navigate to login
+Progress ████████░░░░░░░░░░░░ 40% 2/5 · Enter credentials
+Progress ████████████░░░░░░░░ 60% 3/5 · Submit form
+Progress ████████████████░░░░ 80% 4/5 · Verify dashboard
+Progress ████████████████████ 100% 5/5 · Logout
+```
+
+### Error Reporting
+
+```javascript
+try {
+  await client.find('non-existent element');
+} catch (error) {
+  console.log(formatter.formatError('Element search failed', error));
+}
+```
+
+**Output:**
+```
+❌ Element search failed → Element "non-existent element" not found.
+
+=== Debug Information ===
+Element searched for: "non-existent element"
+Cache threshold: 0.05 (95.0% similarity required)
+Cache: MISS
+Similarity score: 45.23%
+Current screenshot: /tmp/testdriver-debug/screenshot-1234.png
+```
+
+## Tips for Great Logs
+
+1. **Use descriptive element descriptions** - They appear in the logs!
+   ```javascript
+   // ✅ Good
+   await client.find('blue submit button in login form');
+   
+   // ❌ Less helpful
+   await client.find('button');
+   ```
+
+2. **Leverage test context** - Set it once, get timestamps on all logs
+   ```javascript
+   client.setTestContext({
+     test: 'User Login',
+     startTime: Date.now()
+   });
+   ```
+
+3. **Monitor cache performance** - Use VERBOSE mode during development
+   ```bash
+   VERBOSE=true node my-test.js
+   ```
+
+4. **Organize with headers** - Make long test output scannable
+   ```javascript
+   console.log(formatter.formatHeader('Setup Phase', '⚙️'));
+   // ... setup code ...
+   
+   console.log(formatter.formatHeader('Test Execution', '🧪'));
+   // ... test code ...
+   ```
+
+5. **Track progress** - Show users what's happening in long-running tests
+   ```javascript
+   for (let i = 0; i < items.length; i++) {
+     console.log(formatter.formatProgress(i + 1, items.length));
+     // ... process item ...
+   }
+   ```
+
+## Demo
+
+Run the comprehensive demo to see all logging features:
+
+```bash
+TD_API_KEY=your_key node examples/sdk-awesome-logs-demo.js
+```
+
+Or check out the cache thresholds example:
+
+```bash
+TD_API_KEY=your_key VERBOSE=true node examples/sdk-cache-thresholds.js
+```
+
+## Color Reference
+
+The logging system uses consistent color coding:
+
+- **🔵 Blue**: Info, navigation, system messages
+- **🟢 Green**: Success, passed assertions, fast operations
+- **🟡 Yellow**: Warnings, caching, acceptable performance
+- **🔴 Red**: Errors, failures, slow operations
+- **🟣 Magenta**: Finding/searching operations
+- **🔵 Cyan**: User actions, interactive elements
+- **⚪ Gray**: Debug info, metadata, timestamps
+
+## Emoji Reference
+
+### Actions
+- 👆 Click / Tap
+- 👉 Hover / Point
+- ⌨️ Type / Keyboard input
+- 🎹 Press keys
+- 📜 Scroll
+- 🖱️ Right-click
+- ✊ Drag
+
+### Status
+- ✅ Success / Passed
+- ❌ Error / Failed
+- ⚠️ Warning
+- ℹ️ Info
+- 🔧 Debug
+
+### Operations
+- 🔍 Find / Search
+- 🔎 Find all
+- 📸 Screenshot
+- 🧠 Remember (AI)
+- 🎯 Focus
+- ⚡ Cache hit
+- 💤 Cache miss
+
+### System
+- 🔌 Connect / Disconnect
+- 🚀 Launch / Start
+- 🏁 Finish / End
+- ⏳ Waiting / Loading
+- ⏱️ Duration / Time
+- 📍 Location / Coordinates
+- 📊 Statistics / Summary
+- 📈 Progress
+
+### Organizational
+- ✨ Header / Title
+- 📦 Section / Group
+- ▶️ Running / Active
+- 🎉 Complete / Success
+- 🚨 Alert / Critical
+
+Enjoy your AWESOME logs! 🎨✨