@testdriverai/mcp 7.10.0-canary.0 → 7.10.1-test

package/setup/aws/spawn-runner.sh

@@ -145,17 +145,38 @@ done
 echo "Installing runner..."
 
 # Determine environment and version
-TD_CHANNEL="${TD_CHANNEL:-stable}"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SDK_PKG_JSON="${SCRIPT_DIR}/../../../sdk/package.json"
+# SDK package.json — works both from monorepo (sdk/setup/aws/) and npm install (setup/aws/)
+SDK_PKG_JSON="${SCRIPT_DIR}/../../package.json"
 RUNNER_DIR="${SCRIPT_DIR}/../../../runner"
 
+# Derive channel from TD_CHANNEL env, or from the SDK version's prerelease tag
+# (mirrors sdk/lib/resolve-channel.js logic)
+if [ -z "${TD_CHANNEL:-}" ]; then
+  if [ -f "$SDK_PKG_JSON" ]; then
+    SDK_VERSION=$(jq -r '.version' "$SDK_PKG_JSON")
+    # Extract prerelease tag: "7.6.0-canary.5" → "canary", "7.6.0" → ""
+    PRE_TAG=$(echo "$SDK_VERSION" | sed -n 's/^[0-9]*\.[0-9]*\.[0-9]*-\([a-z]*\).*/\1/p')
+    if [ -n "$PRE_TAG" ] && echo "$PRE_TAG" | grep -qE '^(dev|test|canary|stable)$'; then
+      TD_CHANNEL="$PRE_TAG"
+      echo "Channel derived from SDK version ($SDK_VERSION): $TD_CHANNEL"
+    else
+      TD_CHANNEL="stable"
+      echo "SDK version $SDK_VERSION has no prerelease tag, defaulting to: $TD_CHANNEL"
+    fi
+  else
+    TD_CHANNEL="stable"
+    echo "SDK package.json not found, defaulting channel to: $TD_CHANNEL"
+  fi
+fi
+echo "Using channel: $TD_CHANNEL"
+
 if [ -f "$SDK_PKG_JSON" ]; then
   RUNNER_VERSION=$(jq -r '.version' "$SDK_PKG_JSON")
   echo "Runner version from SDK: $RUNNER_VERSION"
 else
   RUNNER_VERSION="$TD_CHANNEL"
-  echo "SDK package.json not found, using env tag: $RUNNER_VERSION"
+  echo "SDK package.json not found, using channel as runner version: $RUNNER_VERSION"
 fi
 
 if [ "$TD_CHANNEL" = "dev" ]; then

package/docs/v7/_drafts/caching-ai.mdx

@@ -1,215 +0,0 @@
----
-title: "AI Prompt Caching"
-sidebarTitle: "AI Caching"
-description: "How TestDriver caches AI-generated YAML commands for faster tests"
-icon: "bolt"
----
-
-## Overview
-
-The Prompt Cache stores AI-generated YAML commands locally, so repeated `.ai()` calls with the same prompt skip the AI entirely.
-
-This provides:
-- ⚡ **Instant execution** - No AI call needed
-- 💰 **Cost savings** - Reduces API usage
-- 🔌 **Offline testing** - Works without network
-- 🎯 **Deterministic** - Same prompt = same commands
-
-## How It Works
-
-<Steps>
-  <Step title="First Call">
-    ```javascript
-    await testdriver.ai('click the submit button');
-    ```
-    
-    - Sends prompt + screenshot to AI
-    - Receives YAML commands
-    - Saves to `.testdriver/.cache/{prompt-hash}.yaml`
-  </Step>
-  
-  <Step title="Subsequent Calls">
-    ```javascript
-    await testdriver.ai('click the submit button');
-    ```
-    
-    - Checks cache first
-    - Finds matching cached YAML
-    - Uses cached commands (no AI call)
-    - Shows `(using cached response)` in output
-  </Step>
-</Steps>
-
-## Cache Location
-
-Cached prompts are stored locally in your project:
-
-```
-.testdriver/
-  .cache/
-    click-the-submit-button-a1b2c3d4.yaml
-    find-login-form-e5f6a7b8.yaml
-    verify-dashboard-c9d0e1f2.yaml
-```
-
-Files are named using:
-- Sanitized prompt (first 50 chars, alphanumeric)
-- MD5 hash of full prompt for uniqueness
-
-## Cache Matching
-
-The prompt cache uses **exact text matching**:
-- Case-insensitive comparison
-- Whitespace trimmed
-- No screenshot comparison
-
-```javascript
-// These all match the same cache entry:
-await testdriver.ai('click the submit button');
-await testdriver.ai('CLICK THE SUBMIT BUTTON');
-await testdriver.ai('  click the submit button  ');
-
-// This creates a new cache entry:
-await testdriver.ai('click the submit btn'); // Different text
-```
-
-## Disabling Prompt Cache
-
-Bypass the cache for a specific call:
-
-```javascript
-// Force fresh AI call, bypass cache
-await testdriver.ai('click the submit button', false);
-
-// These use cache (default)
-await testdriver.ai('click the submit button');
-await testdriver.ai('click the submit button', true);
-```
-
-## Clearing Prompt Cache
-
-Clear all cached prompts:
-
-```bash
-rm -rf .testdriver/.cache/*.yaml
-```
-
-Or programmatically:
-
-```javascript
-const promptCache = require('testdriverai/agent/lib/cache.js');
-promptCache.clearCache();
-```
-
-## Usage Examples
-
-### Basic Caching
-
-```javascript
-import { test } from 'vitest';
-import { chrome } from 'testdriverai/presets';
-
-test('login flow', async (context) => {
-  const { testdriver } = await chrome(context, {
-    url: 'https://myapp.com/login'
-  });
-  
-  // First call: AI generates commands, saves to cache
-  await testdriver.ai('click the login button');
-  
-  // Run test again - uses cache (instant)
-  // Look for: "(using cached response)" in output
-});
-```
-
-### Bypassing Cache
-
-```javascript
-test('always fresh', async (context) => {
-  const { testdriver } = await chrome(context, { url });
-  
-  // Always get fresh AI response
-  await testdriver.ai('analyze the current state', false);
-});
-```
-
-## Best Practices
-
-### 1. Use Consistent Prompts
-
-```javascript
-// ✅ Good - consistent prompt
-await testdriver.ai('fill out the login form');
-await testdriver.ai('fill out the login form'); // Cache hit
-
-// ❌ Bad - different prompts
-await testdriver.ai('fill out the login form');
-await testdriver.ai('complete the login form'); // Cache miss
-```
-
-### 2. Clear Cache When Test Logic Changes
-
-If you update your test prompts, clear the cache:
-
-```bash
-rm -rf .testdriver/.cache/*.yaml
-```
-
-### 3. Don't Commit Cache to Git
-
-Add to `.gitignore`:
-
-```gitignore
-.testdriver/.cache/
-```
-
-### 4. Version Control Consideration
-
-While you _can_ commit cached prompts for team consistency, it's generally not recommended because:
-- AI responses may improve over time
-- Different team members may need different cached results
-- Cache files can become stale
-
-## Cache Storage Details
-
-| Property | Value |
-|----------|-------|
-| Location | Local (`.testdriver/.cache/`) |
-| Persistence | Until manually cleared |
-| Scope | Per-project |
-| Matching | Exact prompt text (case-insensitive) |
-| Expiration | Never |
-
-## Troubleshooting
-
-### Cache Not Working
-
-Check:
-1. Prompts match exactly (case-insensitive)
-2. `.testdriver/.cache/` directory exists and is writable
-3. `TD_NO_PROMPT_CACHE` environment variable is not set
-
-### Stale Cache Data
-
-If AI responses seem outdated:
-
-```bash
-# Clear all cached prompts
-rm -rf .testdriver/.cache/*.yaml
-```
-
-Or clear specific prompts:
-
-```bash
-# Find cache files
-ls -la .testdriver/.cache/
-
-# Delete specific cache file
-rm .testdriver/.cache/click-the-submit-button-*.yaml
-```
-
-## See Also
-
-- [Selector Caching](/v7/guides/caching-selectors) - Cache element locations
-- [`.ai()` Method](/v7/api/ai) - AI command generation
-- [Vitest Integration](/v7/guides/vitest) - Testing with TestDriver

package/docs/v7/_drafts/caching.mdx

@@ -1,366 +0,0 @@
----
-title: "Caching Prompts"
-sidebarTitle: "Caching Prompts"
-description: "How TestDriver caches AI responses and element locations for faster tests"
-icon: "bolt"
----
-
-## Overview
-
-TestDriver uses two types of caching to dramatically speed up your tests and reduce AI costs:
-
-1. **Prompt Cache** - Caches AI-generated commands (`.ai()` responses)
-2. **Selector Cache** - Caches element locations (`.find()` results)
-
-Both caches are enabled by default and work automatically.
-
-## Prompt Cache
-
-The Prompt Cache stores AI-generated YAML commands locally, so repeated `.ai()` calls with the same prompt skip the AI entirely.
-
-### How It Works
-
-<Steps>
-  <Step title="First Call">
-    ```javascript
-    await testdriver.ai('click the submit button');
-    ```
-    
-    - Sends prompt + screenshot to AI
-    - Receives YAML commands
-    - Saves to `.testdriver/.cache/{prompt-hash}.yaml`
-  </Step>
-  
-  <Step title="Subsequent Calls">
-    ```javascript
-    await testdriver.ai('click the submit button');
-    ```
-    
-    - Checks cache first
-    - Finds matching cached YAML
-    - Uses cached commands (no AI call)
-    - Shows `(using cached response)` in output
-  </Step>
-</Steps>
-
-### Cache Location
-
-Cached prompts are stored locally:
-
-```
-.testdriver/
-  .cache/
-    click-the-submit-button-a1b2c3d4.yaml
-    find-login-form-e5f6a7b8.yaml
-    verify-dashboard-c9d0e1f2.yaml
-```
-
-Files are named using:
-- Sanitized prompt (first 50 chars, alphanumeric)
-- MD5 hash of full prompt for uniqueness
-
-### Disabling Prompt Cache
-
-Bypass the cache for a specific call:
-
-```javascript
-// Force fresh AI call, bypass cache
-await testdriver.ai('click the submit button', false);
-
-// These use cache (default)
-await testdriver.ai('click the submit button');
-await testdriver.ai('click the submit button', true);
-```
-
-### Clearing Prompt Cache
-
-Clear all cached prompts:
-
-```bash
-rm -rf .testdriver/.cache/*.yaml
-```
-
-Or programmatically:
-
-```javascript
-const promptCache = require('testdriverai/agent/lib/cache.js');
-promptCache.clearCache();
-```
-
-### Benefits
-
-- ⚡ **Instant execution** - No AI call needed
-- 💰 **Cost savings** - Reduces API usage
-- 🔌 **Offline testing** - Works without network
-- 🎯 **Deterministic** - Same prompt = same commands
-
-## Selector Cache
-
-The Selector Cache stores element locations on the server, so `.find()` calls can skip the AI vision analysis.
-
-### How It Works
-
-```mermaid
-sequenceDiagram
-    participant Test as Your Test
-    participant SDK as TestDriver SDK
-    participant API as TestDriver API
-    participant AI as Claude Vision
-    participant Cache as Selector Cache DB
-
-    Test->>SDK: testdriver.find('submit button')
-    SDK->>API: POST /locate (screenshot + prompt)
-    
-    API->>Cache: Check for matching cache entry
-    
-    alt Cache Hit (95%+ similar screenshot)
-        Cache-->>API: Return cached coordinates
-        API-->>SDK: {x, y, cacheHit: true}
-        SDK-->>Test: Element found (instant)
-    else Cache Miss
-        API->>AI: Analyze screenshot
-        AI-->>API: Element coordinates
-        API->>Cache: Save new cache entry
-        API-->>SDK: {x, y, cacheHit: false}
-        SDK-->>Test: Element found
-    end
-```
-
-### Cache Matching Strategy
-
-The selector cache uses a three-tier matching system:
-
-1. **Exact Hash Match** (Fastest)
-   - Perceptual hash comparison
-   - Same screenshot = instant match
-   - 0% difference threshold
-
-2. **Pixel Diff Match** (Fast)
-   - 80%+ perceptual hash similarity
-   - Pixel-by-pixel comparison
-   - Default 5% difference threshold (95% similarity)
-   - Configurable per call
-
-3. **Template Match** (Fallback)
-   - Edge detection + template matching
-   - Finds visually similar UI elements
-   - 75%+ confidence threshold
-
-### Viewing Cache Entries
-
-View all cached selectors at [console.testdriver.ai](https://console.testdriver.ai)
-
-The console shows:
-- Cached screenshots with green circles on found elements
-- Original prompts
-- Hit count (how many times cache was used)
-- Similarity scores
-- Cache age and last accessed time
-
-### Controlling Cache Threshold
-
-Adjust similarity threshold per call:
-
-```javascript
-// Default: 95% similarity (5% difference allowed)
-await testdriver.find('submit button');
-
-// Stricter: 99% similarity (1% difference allowed)
-await testdriver.find('submit button', { threshold: 0.01 });
-
-// More lenient: 90% similarity (10% difference allowed)
-await testdriver.find('submit button', { threshold: 0.10 });
-
-// Disable cache: force fresh AI analysis
-await testdriver.find('submit button', { threshold: -1 });
-```
-
-### Cache Filtering
-
-The selector cache automatically filters by:
-
-- **Prompt** - Exact text match (case-insensitive)
-- **Team** - Your team ID
-- **OS** - Operating system (if specified)
-- **Resolution** - Screen resolution (if specified)
-- **Time Window** - Last 7 days by default
-
-### Cache Statistics
-
-Each cache entry tracks:
-
-- **Hit Count** - Number of times cache was used
-- **Last Hit** - When cache was last accessed
-- **Similarity** - Percentage match to original
-- **Created At** - When entry was created
-- **Element Type** - button, input, link, etc.
-- **Element Bounds** - Bounding box coordinates
-
-### Benefits
-
-- ⚡ **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
-
-## Cache Behavior Examples
-
-### Prompt Cache Example
-
-```javascript
-import { test } from 'vitest';
-import { chrome } from 'testdriverai/presets';
-
-test('login flow', async (context) => {
-  const { testdriver } = await chrome(context, {
-    url: 'https://myapp.com/login'
-  });
-  
-  // First call: AI generates commands, saves to cache
-  await testdriver.ai('click the login button');
-  
-  // Run test again - uses cache (instant)
-  // Look for: "(using cached response)" in output
-});
-```
-
-### Selector Cache Example
-
-```javascript
-import { test } from 'vitest';
-import { chrome } from 'testdriverai/presets';
-
-test('find element', async (context) => {
-  const { testdriver } = await chrome(context, {
-    url: 'https://example.com'
-  });
-  
-  // First call: AI vision analysis, saves to cache
-  const button = await testdriver.find('More information link');
-  console.log('Cache hit:', button.cacheHit); // false
-  
-  // Second call: uses cache (instant)
-  const button2 = await testdriver.find('More information link');
-  console.log('Cache hit:', button2.cacheHit); // true
-});
-```
-
-### Dynamic Threshold Example
-
-```javascript
-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 });
-  
-  // Lenient: 90% similarity acceptable
-  const elem2 = await testdriver.find('button', { threshold: 0.10 });
-  
-  // Bypass cache entirely
-  const elem3 = await testdriver.find('button', { threshold: -1 });
-});
-```
-
-## Best Practices
-
-### 1. Use Consistent Prompts
-
-```javascript
-// ✅ Good - consistent prompt
-await testdriver.find('submit button');
-await testdriver.find('submit button'); // Cache hit
-
-// ❌ Bad - different prompts
-await testdriver.find('submit button');
-await testdriver.find('the submit button'); // Cache miss
-```
-
-### 2. Clear Cache When UI Changes
-
-If your UI changes significantly, clear the cache:
-
-```bash
-# Clear prompt cache
-rm -rf .testdriver/.cache/*.yaml
-
-# Clear selector cache
-# Use console.testdriver.ai to delete entries
-```
-
-### 3. Use Appropriate Thresholds
-
-```javascript
-// Stable UI: strict threshold
-await testdriver.find('logo', { threshold: 0.01 });
-
-// Dynamic UI: lenient threshold
-await testdriver.find('news feed item', { threshold: 0.10 });
-
-// Always fresh: disable cache
-await testdriver.find('timestamp', { threshold: -1 });
-```
-
-### 4. Monitor Cache Performance
-
-Check [console.testdriver.ai](https://console.testdriver.ai) regularly to:
-- See cache hit rates
-- Identify frequently used selectors
-- Remove stale cache entries
-- Optimize threshold settings
-
-## Cache Storage
-
-| Cache Type | Location | Persistence |
-|------------|----------|-------------|
-| Prompt Cache | Local (`.testdriver/.cache/`) | Until manually cleared |
-| Selector Cache | Server (MongoDB + S3) | 7 days default |
-
-## Important Notes
-
-### Prompt Cache
-
-- Cache keys are **prompt text only** (no screenshot comparison)
-- Case-insensitive, trimmed matching
-- Safe to commit to version control (but not recommended)
-- Never expires automatically
-
-### Selector Cache
-
-- Cache matches by **screenshot similarity** + prompt
-- Platform-specific (OS, resolution)
-- Team-scoped (your cache entries only)
-- 7-day rolling window by default
-
-## Troubleshooting
-
-### Prompt Cache Not Working
-
-Check:
-1. Prompts match exactly (case-insensitive)
-2. `.testdriver/.cache/` directory exists and is writable
-3. `TD_NO_PROMPT_CACHE` environment variable is not set
-
-### Selector Cache Not Working
-
-Check:
-1. Threshold isn't too strict (try 0.10 for 90% similarity)
-2. Screenshot hasn't changed significantly
-3. OS/resolution matches cached entry
-4. Cache entry isn't older than 7 days
-
-### Stale Cache Data
-
-Clear prompt cache:
-```bash
-rm -rf .testdriver/.cache/*.yaml
-```
-
-Delete selector cache entries at [console.testdriver.ai](https://console.testdriver.ai)
-
-## See Also
-
-- [Console Dashboard](https://console.testdriver.ai) - View and manage selector cache
-- [`.ai()` Method](/v7/api/ai) - AI command generation
-- [`.find()` Method](/v7/api/find) - Element location
-- [Vitest Integration](/v7/guides/vitest) - Testing with TestDriver