testdriverai 7.0.0 → 7.1.1

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/_drafts/best-practices.mdx

@@ -0,0 +1,486 @@
+---
+title: "Best Practices"
+description: "Patterns and practices for reliable tests"
+icon: "star"
+---
+
+## Test Structure
+
+### Use beforeAll/afterAll
+
+Create one sandbox per test suite:
+
+```javascript
+describe('Login Flow', () => {
+  let testdriver;
+  
+  beforeAll(async () => {
+    const client = await TestDriver.create({
+      apiKey: process.env.TD_API_KEY,
+      os: 'linux'
+    });
+    await client.auth();
+    await client.connect({ newSandbox: true });
+    testdriver = client;
+  });
+  
+  afterAll(async () => {
+    await testdriver?.disconnect();
+  });
+  
+  it('logs in successfully', async () => {
+    // Test code
+  });
+  
+  it('shows error on invalid credentials', async () => {
+    // Test code
+  });
+});
+```
+
+### Use Presets
+
+Presets handle lifecycle automatically:
+
+```javascript
+// ✅ Good - automatic lifecycle
+test('my test', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+  // Test code
+});
+
+// ❌ Avoid - manual lifecycle
+test('my test', async () => {
+  const client = new TestDriver(...);
+  await client.auth();
+  await client.connect();
+  // Test code
+  await client.disconnect();
+});
+```
+
+## Element Finding
+
+### Be Specific
+
+```javascript
+// ❌ Too vague
+await testdriver.find('button');
+
+// ✅ Specific
+await testdriver.find('blue submit button at bottom of login form');
+
+// ✅ Include visual context
+await testdriver.find('red delete button next to user John Doe');
+
+// ✅ Use nearby text
+await testdriver.find('button below "Confirm your email" text');
+```
+
+### Always Check found()
+
+```javascript
+// ❌ Assumes element exists
+const button = await testdriver.find('submit button');
+await button.click();
+
+// ✅ Verifies element exists
+const button = await testdriver.find('submit button');
+if (!button.found()) {
+  throw new Error('Submit button not found');
+}
+await button.click();
+
+// ✅ Or use assertion
+const button = await testdriver.find('submit button');
+expect(button.found()).toBe(true);
+await button.click();
+```
+
+### Poll for Dynamic Elements
+
+```javascript
+// ✅ Wait for element to appear
+async function waitFor(testdriver, description, timeout = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    const element = await testdriver.find(description);
+    if (element.found()) return element;
+    await new Promise(r => setTimeout(r, 1000));
+  }
+  throw new Error(`Element not found: ${description}`);
+}
+
+const button = await waitFor(testdriver, 'submit button');
+await button.click();
+```
+
+## Actions
+
+### Use Descriptive Prompts
+
+```javascript
+// ❌ Generic
+await testdriver.ai('login');
+
+// ✅ Specific steps
+await testdriver.ai('click the username field and type user@example.com');
+await testdriver.ai('click the password field and type password123');
+await testdriver.ai('click the blue submit button');
+```
+
+### Chain Actions
+
+```javascript
+// ✅ Find once, use multiple times
+const input = await testdriver.find('username field');
+await input.click();
+await testdriver.type('user@example.com');
+await testdriver.pressKeys(['Tab']);
+
+// ✅ Or chain directly
+await testdriver.find('username field').then(el => el.click());
+```
+
+### Use Keyboard Shortcuts
+
+```javascript
+// ✅ Faster than UI navigation
+await testdriver.pressKeys(['ctrl', 'a']); // Select all
+await testdriver.pressKeys(['ctrl', 'c']); // Copy
+await testdriver.pressKeys(['ctrl', 'v']); // Paste
+await testdriver.pressKeys(['escape']); // Close dialog
+```
+
+## Assertions
+
+### Verify Key States
+
+```javascript
+// ✅ Assert at checkpoints
+await testdriver.assert('login page is visible');
+await testdriver.find('username').then(el => el.click());
+await testdriver.type('user@example.com');
+await testdriver.find('password').then(el => el.click());
+await testdriver.type('password123');
+await testdriver.find('submit').then(el => el.click());
+await testdriver.assert('dashboard is visible');
+await testdriver.assert('welcome message shows username');
+```
+
+### Use Vitest Assertions
+
+```javascript
+// ✅ Combine TestDriver and Vitest
+const element = await testdriver.find('error message');
+expect(element.found()).toBe(true);
+expect(element.text).toContain('Invalid credentials');
+
+const result = await testdriver.assert('dashboard loaded');
+expect(result).toBe(true);
+```
+
+## Performance
+
+### Reuse Sandboxes
+
+```javascript
+// ✅ One sandbox per suite
+beforeAll(async () => {
+  testdriver = await TestDriver.create(...);
+});
+
+afterAll(async () => {
+  await testdriver.disconnect();
+});
+
+// ❌ One sandbox per test (slow!)
+beforeEach(async () => {
+  testdriver = await TestDriver.create(...);
+});
+```
+
+### Use Caching
+
+```javascript
+// ✅ Enable caching for repeated elements
+await testdriver.find('submit button'); // AI call
+await testdriver.find('submit button'); // Cache hit (fast!)
+
+// ✅ Use consistent prompts
+const buttonDesc = 'blue submit button at bottom';
+await testdriver.find(buttonDesc); // Cache hit on reuse
+```
+
+### Parallel Execution
+
+```javascript
+// vitest.config.mjs
+export default defineConfig({
+  test: {
+    pool: 'forks',
+    maxConcurrency: 5,  // Run 5 tests in parallel
+    fileParallelism: true
+  }
+});
+```
+
+## Error Handling
+
+### Graceful Failures
+
+```javascript
+test('handles missing elements', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+  
+  const optionalButton = await testdriver.find('optional newsletter button');
+  
+  if (optionalButton.found()) {
+    await optionalButton.click();
+  } else {
+    console.log('Newsletter button not present, skipping');
+  }
+  
+  // Continue with required elements
+  const required = await testdriver.find('continue button');
+  expect(required.found()).toBe(true);
+  await required.click();
+});
+```
+
+### Try-Catch for exec()
+
+```javascript
+// ✅ Handle command failures
+try {
+  await testdriver.exec('sh', 'risky-command', 30000, false);
+} catch (error) {
+  console.log('Command failed, using fallback');
+  await testdriver.exec('sh', 'fallback-command', 30000, false);
+}
+```
+
+### Cleanup in Finally
+
+```javascript
+let testdriver;
+
+try {
+  testdriver = await TestDriver.create(...);
+  await testdriver.auth();
+  await testdriver.connect();
+  
+  // Test code
+  
+} catch (error) {
+  console.error('Test failed:', error);
+  throw error;
+} finally {
+  await testdriver?.disconnect();
+}
+```
+
+## Code Organization
+
+### Extract Common Patterns
+
+```javascript
+// helpers.mjs
+export async function login(testdriver, email, password) {
+  await testdriver.find('username field').then(el => el.click());
+  await testdriver.type(email);
+  await testdriver.find('password field').then(el => el.click());
+  await testdriver.type(password);
+  await testdriver.find('submit button').then(el => el.click());
+  await testdriver.assert('dashboard is visible');
+}
+
+// test file
+import { login } from './helpers.mjs';
+
+test('user can access settings', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+  await login(testdriver, 'user@example.com', 'password123');
+  await testdriver.find('settings').then(el => el.click());
+});
+```
+
+### Use Page Objects
+
+```javascript
+// pages/LoginPage.mjs
+export class LoginPage {
+  constructor(testdriver) {
+    this.testdriver = testdriver;
+  }
+  
+  async login(email, password) {
+    await this.testdriver.find('username field').then(el => el.click());
+    await this.testdriver.type(email);
+    await this.testdriver.find('password field').then(el => el.click());
+    await this.testdriver.type(password);
+    await this.testdriver.find('submit button').then(el => el.click());
+  }
+  
+  async assertVisible() {
+    const result = await this.testdriver.assert('login page is visible');
+    expect(result).toBe(true);
+  }
+}
+
+// test file
+import { LoginPage } from './pages/LoginPage.mjs';
+
+test('login flow', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+  const loginPage = new LoginPage(testdriver);
+  
+  await loginPage.assertVisible();
+  await loginPage.login('user@example.com', 'password123');
+});
+```
+
+## Environment Management
+
+### Use Environment Variables
+
+```javascript
+// ✅ Good - configurable
+const testdriver = await TestDriver.create({
+  apiKey: process.env.TD_API_KEY,
+  os: process.env.TD_OS || 'linux',
+  resolution: process.env.TD_RESOLUTION || '1920x1080'
+});
+
+// ❌ Bad - hardcoded
+const testdriver = await TestDriver.create({
+  apiKey: 'td_1234567890',
+  os: 'linux'
+});
+```
+
+### Separate Test Data
+
+```javascript
+// test-data.json
+{
+  "validUser": {
+    "email": "user@example.com",
+    "password": "password123"
+  },
+  "adminUser": {
+    "email": "admin@example.com",
+    "password": "admin123"
+  }
+}
+
+// test file
+import testData from './test-data.json';
+
+test('login as user', async (context) => {
+  const { testdriver } = await chrome(context, { url });
+  await login(testdriver, testData.validUser.email, testData.validUser.password);
+});
+```
+
+## Documentation
+
+### Comment Complex Logic
+
+```javascript
+// ✅ Explain why, not what
+// Wait for animation to complete before interacting
+await new Promise(r => setTimeout(r, 1000));
+
+// Navigate to nested menu item since direct click doesn't work
+await testdriver.find('menu button').then(el => el.hover());
+await testdriver.find('submenu item').then(el => el.click());
+```
+
+### Name Tests Clearly
+
+```javascript
+// ✅ Clear intent
+test('user sees error when submitting form with invalid email', async () => {});
+test('admin can delete user accounts from settings page', async () => {});
+
+// ❌ Vague
+test('form validation', async () => {});
+test('user deletion', async () => {});
+```
+
+## Anti-Patterns
+
+### Don't Use Hardcoded Delays
+
+```javascript
+// ❌ Brittle - might be too short or too long
+await new Promise(r => setTimeout(r, 5000));
+
+// ✅ Poll for condition
+const element = await waitFor(testdriver, 'success message');
+```
+
+### Don't Ignore Errors
+
+```javascript
+// ❌ Silently fails
+try {
+  await testdriver.find('button').then(el => el.click());
+} catch (error) {
+  // Ignore
+}
+
+// ✅ Handle gracefully
+const button = await testdriver.find('button');
+if (!button.found()) {
+  console.warn('Optional button not found, skipping');
+} else {
+  await button.click();
+}
+```
+
+### Don't Test Implementation Details
+
+```javascript
+// ❌ Too specific to implementation
+await testdriver.find('div with class submit-btn-container').then(el => el.click());
+
+// ✅ User-facing behavior
+await testdriver.find('submit button').then(el => el.click());
+```
+
+## Checklist
+
+Before committing tests:
+
+- ✅ Tests use `beforeAll`/`afterAll` for sandbox lifecycle
+- ✅ All elements checked with `.found()` before use
+- ✅ Descriptive element descriptions with visual context
+- ✅ Key assertions at important checkpoints
+- ✅ No hardcoded delays (use polling instead)
+- ✅ API keys in environment variables
+- ✅ Test names clearly describe intent
+- ✅ Common patterns extracted to helpers
+- ✅ Error handling for optional elements
+- ✅ Cleanup in `finally` blocks
+
+## See Also
+
+<CardGroup cols={2}>
+  <Card title="Debugging" icon="bug" href="/v7/guides/debugging">
+    Debug failing tests
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/v7/getting-started/configuration">
+    Configure TestDriver
+  </Card>
+  
+  <Card title="Caching" icon="bolt" href="/v7/guides/caching-ai">
+    Optimize with caching
+  </Card>
+  
+  <Card title="Examples" icon="code" href="/v7/presets/chrome">
+    See working examples
+  </Card>
+</CardGroup>