testdriverai 7.2.64 → 7.2.65

package/docs/v7/_drafts/troubleshooting.mdx

@@ -1,526 +0,0 @@
----
-title: "Troubleshooting"
-description: "Common issues and solutions"
-icon: "circle-question"
----
-
-## Installation Issues
-
-### Module Not Found
-
-**Error:** `Cannot find module 'testdriverai'`
-
-**Solution:**
-```bash
-# Verify installation
-npm list testdriverai
-
-# Reinstall
-npm install testdriverai --save-dev
-
-# Clear cache and reinstall
-rm -rf node_modules package-lock.json
-npm install
-```
-
-### Version Mismatch
-
-**Error:** `TestDriver requires Node 16+`
-
-**Solution:**
-```bash
-# Check Node version
-node --version
-
-# Update Node
-nvm install 18
-nvm use 18
-```
-
-## Authentication Issues
-
-### API Key Not Found
-
-**Error:** `API key required`
-
-**Solution:**
-```bash
-# Create .env file
-echo "TD_API_KEY=your_api_key_here" > .env
-
-# Verify it loads
-node -e "require('dotenv').config(); console.log(process.env.TD_API_KEY)"
-```
-
-### Invalid API Key
-
-**Error:** `Authentication failed: Invalid API key`
-
-**Solution:**
-1. Verify key at [console.testdriver.ai/team](https://console.testdriver.ai/team)
-2. Check for typos or extra spaces
-3. Regenerate key if needed
-
-```javascript
-// Remove quotes, spaces, newlines
-const apiKey = process.env.TD_API_KEY.trim();
-```
-
-## Connection Issues
-
-### Sandbox Connection Timeout
-
-**Error:** `Connection timeout after 60000ms`
-
-**Solution:**
-```javascript
-// Increase connection timeout
-const client = await TestDriver.create({
-  apiKey: process.env.TD_API_KEY,
-  connectionTimeout: 120000  // 2 minutes
-});
-
-// Or retry connection
-let attempts = 0;
-while (attempts < 3) {
-  try {
-    await client.connect();
-    break;
-  } catch (error) {
-    attempts++;
-    if (attempts === 3) throw error;
-    await new Promise(r => setTimeout(r, 5000));
-  }
-}
-```
-
-### Sandbox Quota Exceeded
-
-**Error:** `Sandbox limit reached`
-
-**Solution:**
-1. Check your [quota](https://console.testdriver.ai/team)
-2. Disconnect old sandboxes
-3. Upgrade plan if needed
-
-```javascript
-// Ensure cleanup in all tests
-afterAll(async () => {
-  await testdriver?.disconnect();
-});
-```
-
-## Element Finding Issues
-
-### Element Not Found
-
-**Error:** Element returns `found() === false`
-
-**Solutions:**
-
-**1. Be more specific:**
-```javascript
-// ❌ Too vague
-await testdriver.find('button');
-
-// ✅ Specific
-await testdriver.find('blue submit button at bottom right of login form');
-```
-
-**2. Wait for element to appear:**
-```javascript
-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(`Timeout waiting for: ${description}`);
-}
-
-const button = await waitFor(testdriver, 'submit button');
-```
-
-**3. Check if page loaded:**
-```javascript
-// Verify page is ready
-await testdriver.assert('page fully loaded');
-await testdriver.find('submit button');
-```
-
-**4. Try alternative descriptions:**
-```javascript
-const descriptions = [
-  'submit button',
-  'blue button at bottom',
-  'button with text Submit',
-  'primary button in form'
-];
-
-let button;
-for (const desc of descriptions) {
-  button = await testdriver.find(desc);
-  if (button.found()) break;
-}
-```
-
-### Wrong Element Found
-
-**Issue:** Finds wrong element or multiple matches
-
-**Solutions:**
-
-**1. Add more context:**
-```javascript
-// ❌ Ambiguous
-await testdriver.find('delete button');
-
-// ✅ Specific location
-await testdriver.find('delete button in the row for user John Doe');
-await testdriver.find('red delete button next to email field');
-```
-
-**2. Check confidence:**
-```javascript
-const element = await testdriver.find('button');
-console.log('Confidence:', element.confidence);
-
-if (element.confidence < 0.8) {
-  console.warn('Low confidence, trying alternative');
-  element = await testdriver.find('more specific button description');
-}
-```
-
-## Cache Issues
-
-### Stale Cache
-
-**Issue:** Using outdated cached element
-
-**Solutions:**
-
-**1. Bypass cache:**
-```javascript
-// Force fresh lookup
-const element = await testdriver.find('button', { threshold: -1 });
-```
-
-**2. Clear cache:**
-```bash
-# Clear prompt cache
-rm -rf .testdriver/.cache/*.yaml
-
-# Clear selector cache via console
-# Visit https://console.testdriver.ai
-```
-
-**3. Adjust threshold:**
-```javascript
-// More lenient (90% similarity)
-await testdriver.find('button', { threshold: 0.10 });
-
-// Stricter (99% similarity)
-await testdriver.find('button', { threshold: 0.01 });
-```
-
-### Cache Not Working
-
-**Issue:** No cache hits despite repeated calls
-
-**Solutions:**
-
-**1. Use consistent prompts:**
-```javascript
-// ❌ Different prompts
-await testdriver.find('submit button');
-await testdriver.find('the submit button');
-
-// ✅ Consistent
-const desc = 'submit button';
-await testdriver.find(desc);
-await testdriver.find(desc); // Cache hit
-```
-
-**2. Check cache is enabled:**
-```javascript
-// Verify cache not disabled
-console.log('Prompt cache:', !process.env.TD_NO_PROMPT_CACHE);
-console.log('Selector cache:', !process.env.TD_NO_SELECTOR_CACHE);
-```
-
-## Command Execution Issues
-
-### exec() Timeout
-
-**Error:** `Command timeout after 30000ms`
-
-**Solutions:**
-
-**1. Increase timeout:**
-```javascript
-await testdriver.exec('sh', 'slow-command', 120000); // 2 minutes
-```
-
-**2. Run in background:**
-```javascript
-// Add & for background execution
-await testdriver.exec('sh', 'long-running-process &', 5000);
-```
-
-**3. Check command exists:**
-```javascript
-// Verify command available
-const result = await testdriver.exec('sh', 'which google-chrome', 5000, true);
-console.log('Chrome path:', result);
-```
-
-### Command Failed
-
-**Error:** Command returns non-zero exit code
-
-**Solutions:**
-
-**1. Ignore errors:**
-```javascript
-// Last parameter ignores errors
-await testdriver.exec('sh', 'risky-command', 30000, true);
-```
-
-**2. Check output:**
-```javascript
-try {
-  const output = await testdriver.exec('sh', 'command', 30000, false);
-  console.log('Output:', output);
-} catch (error) {
-  console.error('Command failed:', error.message);
-}
-```
-
-**3. Use correct shell:**
-```javascript
-// Linux/Mac
-await testdriver.exec('sh', 'echo "test"', 5000);
-
-// Windows
-await testdriver.exec('pwsh', 'Write-Output "test"', 5000);
-```
-
-## Test Execution Issues
-
-### Test Timeout
-
-**Error:** `Test timed out after 60000ms`
-
-**Solutions:**
-
-**1. Increase test timeout:**
-```javascript
-// vitest.config.mjs
-export default defineConfig({
-  test: {
-    testTimeout: 300000  // 5 minutes
-  }
-});
-
-// Or per test
-test('slow test', async () => {
-  // ...
-}, 300000); // 5 minutes
-```
-
-**2. Optimize test:**
-```javascript
-// Use faster actions
-await testdriver.find('button').then(el => el.click());
-
-// Instead of
-await testdriver.ai('click the button');
-```
-
-### Tests Fail in CI
-
-**Issue:** Tests pass locally but fail in CI
-
-**Solutions:**
-
-**1. Check environment variables:**
-```yaml
-# .github/workflows/test.yml
-env:
-  TD_API_KEY: ${{ secrets.TD_API_KEY }}
-  TD_DEFAULT_OS: linux
-```
-
-**2. Increase timeouts for CI:**
-```javascript
-const timeout = process.env.CI ? 600000 : 300000;
-
-export default defineConfig({
-  test: {
-    testTimeout: timeout
-  }
-});
-```
-
-**3. Reduce concurrency:**
-```javascript
-// CI might have resource limits
-export default defineConfig({
-  test: {
-    maxConcurrency: process.env.CI ? 2 : 5
-  }
-});
-```
-
-## Dashcam Issues
-
-### No Replay URL
-
-**Issue:** `dashcam.url` is `null`
-
-**Solutions:**
-
-**1. Ensure dashcam started:**
-```javascript
-const dashcam = new Dashcam(client);
-await dashcam.auth();
-await dashcam.start();  // Must call start!
-
-// Run test
-
-const url = await dashcam.stop();
-console.log('Replay:', url);
-```
-
-**2. Check dashcam installed:**
-```javascript
-// Verify dashcam CLI available
-await testdriver.exec('sh', 'dashcam version', 5000);
-```
-
-**3. Use preset:**
-```javascript
-// Presets handle dashcam automatically
-const { testdriver, dashcam } = await chrome(context, {
-  dashcam: true
-});
-```
-
-### Recording Not Started
-
-**Issue:** Dashcam doesn't record
-
-**Solutions:**
-
-**1. Check authentication:**
-```javascript
-await dashcam.auth(process.env.TD_API_KEY);
-const recording = await dashcam.isRecording();
-console.log('Recording:', recording);
-```
-
-**2. Wait after start:**
-```javascript
-await dashcam.start();
-await new Promise(r => setTimeout(r, 2000)); // Wait 2s
-```
-
-## Performance Issues
-
-### Slow Test Execution
-
-**Solutions:**
-
-**1. Reuse sandboxes:**
-```javascript
-// ✅ One sandbox per suite
-beforeAll(async () => {
-  testdriver = await TestDriver.create(...);
-});
-
-// ❌ One per test (slow!)
-beforeEach(async () => {
-  testdriver = await TestDriver.create(...);
-});
-```
-
-**2. Use caching:**
-```javascript
-// Enable caching for repeated elements
-await testdriver.find('button'); // First call
-await testdriver.find('button'); // Cached (faster!)
-```
-
-**3. Run in parallel:**
-```javascript
-// vitest.config.mjs
-export default defineConfig({
-  test: {
-    maxConcurrency: 5,
-    fileParallelism: true
-  }
-});
-```
-
-### High Memory Usage
-
-**Solutions:**
-
-**1. Reduce concurrency:**
-```javascript
-maxConcurrency: 2  // Lower for resource-constrained environments
-```
-
-**2. Cleanup sandboxes:**
-```javascript
-afterAll(async () => {
-  await testdriver?.disconnect();
-});
-```
-
-**3. Monitor resources:**
-```javascript
-console.log('Memory:', process.memoryUsage());
-```
-
-## Getting Help
-
-If issues persist:
-
-1. **Check Dashcam recording** - See what actually happened
-2. **Enable debug logging** - `verbosity: 2`
-3. **Search Discord** - [discord.com/invite/cWDFW8DzPm](https://discord.com/invite/cWDFW8DzPm)
-4. **Check docs** - [docs.testdriver.ai](https://docs.testdriver.ai)
-5. **Report bug** - [github.com/testdriverai/testdriverai/issues](https://github.com/testdriverai/testdriverai/issues)
-
-### Information to Include
-
-When reporting issues:
-
-- TestDriver version: `npm list testdriverai`
-- Node version: `node --version`
-- OS: `uname -a` or `$PSVersionTable.OS`
-- Error message (full stack trace)
-- Dashcam URL
-- Minimal reproduction code
-
-## See Also
-
-<CardGroup cols={2}>
-  <Card title="Debugging" icon="bug" href="/v7/guides/debugging">
-    Debug failing tests
-  </Card>
-  
-  <Card title="Best Practices" icon="star" href="/v7/guides/best-practices">
-    Testing patterns
-  </Card>
-  
-  <Card title="Configuration" icon="gear" href="/v7/getting-started/configuration">
-    Configure TestDriver
-  </Card>
-  
-  <Card title="FAQ" icon="question" href="/v7/guides/faq">
-    Frequently asked questions
-  </Card>
-</CardGroup>