@testdriverai/agent 7.8.0-test.38

package/docs/v7/caching.mdx

@@ -0,0 +1,128 @@
+---
+title: "Caching Prompts"
+description: "1.7x faster test execution with intelligent caching and optimization"
+icon: "bolt"
+---
+
+TestDriver is engineered for performance with intelligent caching that delivers up to **1.7x faster** test execution by skipping redundant AI vision analysis.
+
+
+```javascript
+// First run: builds cache
+await testdriver.find('submit button');
+
+// Second run: exact match
+await testdriver.find('submit button');
+``` 
+
+## Automatic Caching
+
+Caching is enabled automatically with zero configuration. The cache key is computed from:
+
+- **File hash**: SHA-256 hash of the test file contents
+- **Selector prompt**: The exact text description passed to `find()`
+- **Screenshot context**: Perceptual hash of the current screen state
+- **Platform**: Operating system and browser version
+
+When you modify your test file, the hash changes automatically, invalidating stale cache entries and ensuring fresh AI analysis with your updated test logic.
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('auto-cached test', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com'
+  });
+
+  // First call: AI analyzes screen, saves to cache
+  await testdriver.find('More information link'); // 2.1s
+
+  // Second call: cache hit, instant response
+  await testdriver.find('More information link'); // 12ms ⚡
+});
+```
+
+## Managing the Cache
+
+You can clear the cache within the TestDriver console. There, you'll also find previews of cached elements, the input prompts, as well as analytics on cache hit rates.
+
+<Card href="https://console.testdriver.ai/cache" title="TestDriver Cache" icon="database">
+  Manage and clear your test cache from the TestDriver console.
+</Card>
+
+## Debugging Cache Hits and Misses
+
+You can track cache performance in your tests:
+
+```javascript
+test('monitor cache performance', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+
+  const element = await testdriver.find('submit button');
+
+  if (element.cacheHit) {
+    console.log('✅ Cache hit - instant response');
+    console.log('Strategy:', element.cacheStrategy); // 'exact', 'pixeldiff', or 'template'
+    console.log('Similarity:', `${(element.similarity * 100).toFixed(1)}%`);
+    console.log('Cache age:', element.cacheCreatedAt);
+  } else {
+    console.log('⏱️  Cache miss - AI analysis performed');
+    console.log('New cache entry created');
+  }
+});
+```
+
+## Configuring the Cache
+
+You can configure cache behavior globally when initializing TestDriver:
+
+```javascript
+import { TestDriver } from 'testdriverai';
+
+const testdriver = new TestDriver({
+  apiKey: process.env.TD_API_KEY,
+  cacheKey: 'my-test-suite', // cache-key for this instance
+  cacheDefaults: {
+    threshold: 0.05,      // 95% similarity
+  }
+});
+```
+
+It's also possible to override cache settings per `find()` call:
+
+```javascript
+// Default: 95% similarity required
+await testdriver.find('submit button');
+
+// Explicit strict threshold
+await testdriver.find('submit button', {
+  cacheThreshold: 0.01 // 99% similarity
+});
+```
+
+## Caching with Variables
+
+Custom cache keys prevent cache pollution when using variables in prompts, dramatically improving cache hit rates.
+
+```javascript
+// ❌ Without cache key - creates new cache for each variable value
+const email = 'user@example.com';
+await testdriver.find(`input for ${email}`); // Cache miss every time
+
+// ✅ With cache key - reuses cache regardless of variable
+const email = 'user@example.com';
+await testdriver.find(`input for ${email}`, {
+  cacheKey: 'email-input'
+});
+
+// Also useful for dynamic IDs, names, or other changing data
+const orderId = generateOrderId();
+await testdriver.find(`order ${orderId} status`, {
+  cacheKey: 'order-status'  // Same cache for all orders
+});
+```
+
+
+
+

package/docs/v7/captcha.mdx

@@ -0,0 +1,159 @@
+---
+title: "captcha()"
+sidebarTitle: "captcha"
+description: "Solve captchas using 2captcha service"
+icon: "shield-check"
+---
+
+# Captcha Solving
+
+TestDriver can automatically solve captchas during your tests using the 2captcha service. This feature works on both **Linux** and **Windows** sandboxes.
+
+## Quick Start
+
+
+```javascript
+const result = await testdriver.captcha({
+  apiKey: process.env.TWOCAPTCHA_API_KEY,
+});
+
+console.log(result.success); // true
+console.log(result.token);   // The solved captcha token
+```
+
+That's it! TestDriver will automatically:
+- Detect the captcha type on the page
+- Extract the sitekey
+- Solve the captcha via 2captcha
+- Inject the token into the page
+- Trigger any callbacks
+
+## Supported Captcha Types
+
+| Type | Auto-Detected | Notes |
+|------|---------------|-------|
+| reCAPTCHA v2 | ✅ | Including invisible |
+| reCAPTCHA v3 | ✅ | Action is auto-detected |
+| hCaptcha | ✅ | |
+| Cloudflare Turnstile | ✅ | |
+
+## Getting a 2captcha API Key
+
+1. Sign up at [2captcha.com](https://2captcha.com)
+2. Add funds to your account
+3. Copy your API key from the dashboard
+
+## Configuration Options
+
+```javascript
+const result = await testdriver.captcha({
+  // Required
+  apiKey: '2CAPTCHA_API_KEY',
+
+  // Optional - usually auto-detected
+  sitekey: '6Le...',           // Override auto-detected sitekey
+  type: 'recaptcha_v3',        // Override auto-detected type
+  action: 'submit',            // reCAPTCHA v3 action
+
+  // Timing
+  timeout: 120000,             // Max wait time (default: 120s)
+  pollInterval: 5000,          // Poll interval (default: 5s)
+});
+```
+
+## Full Example
+
+```javascript
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriver";
+
+describe("Checkout flow", () => {
+  it("should complete checkout with captcha", async (context) => {
+    const testdriver = TestDriver(context);
+
+    // Navigate to checkout page
+    await testdriver.provision.chrome({
+      url: 'https://example.com/checkout',
+    });
+
+    // Fill out form
+    await testdriver.type({ text: 'John Doe', selector: '#name' });
+    await testdriver.type({ text: 'john@example.com', selector: '#email' });
+
+    // Solve the captcha
+    const result = await testdriver.captcha({
+      apiKey: process.env.TWOCAPTCHA_API_KEY,
+    });
+
+    expect(result.success).toBe(true);
+
+    // Submit the form
+    await testdriver.click({ selector: '#submit' });
+
+    // Verify success
+    await testdriver.find({ text: 'Order confirmed' });
+  }, 180000);
+});
+```
+
+## Environment Variables
+
+You can set your API key as an environment variable:
+
+```bash
+export TWOCAPTCHA_API_KEY=your_api_key_here
+```
+
+Then use it in your tests:
+
+```javascript
+const result = await testdriver.captcha({
+  apiKey: process.env.TWOCAPTCHA_API_KEY,
+});
+```
+
+### GitHub Actions
+
+Add the key to your repository secrets and expose it in your workflow:
+
+```yaml
+- name: Run Tests
+  run: vitest run
+  env:
+    TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}
+```
+
+## How It Works
+
+1. **Detection**: Scans the page for captcha elements (`data-sitekey`, script tags, etc.)
+2. **Submit**: Sends the captcha challenge to 2captcha's solving service
+3. **Poll**: Waits for human solvers to complete the captcha
+4. **Inject**: Injects the solved token into the page's hidden fields
+5. **Callback**: Triggers any JavaScript callbacks the page expects
+
+## Troubleshooting
+
+### "Could not auto-detect captcha"
+
+The captcha element wasn't found on the page. Try:
+- Waiting for the page to fully load before calling `captcha()`
+- Providing the `sitekey` and `type` manually
+
+### Timeout errors
+
+Captcha solving typically takes 10-30 seconds. If you're getting timeouts:
+- Increase the `timeout` option
+- Check your 2captcha balance
+- Verify the captcha type is correct
+
+### Token not working
+
+Some sites validate tokens immediately. Make sure:
+- The token is injected before form submission
+- The captcha type matches what the site expects
+- For reCAPTCHA v3, the `action` parameter matches the site's expected action
+
+## Requirements
+
+- Chrome must be launched with remote debugging enabled (automatic on all sandboxes)
+- A valid 2captcha API key with sufficient balance