testdriverai 7.2.3 → 7.2.10

package/docs/v7/features/sandbox-customization.mdx

@@ -1,229 +0,0 @@
----
-title: 'Sandbox Customization'
-description: 'Customize your test environments with pre-installed applications, dependencies, and configurations'
----
-
-## Overview
-
-TestDriver sandboxes can be customized to match your testing requirements. Install applications, configure system settings, and prepare environments programmatically to ensure your tests run in the right context.
-
-## Provisioning API
-
-The provisioning API allows you to customize sandbox environments before running tests.
-
-### Installing Applications
-
-Use the provisioning API to install software packages:
-
-```javascript
-import { ai } from '@testdriverai/sdk';
-
-// Install applications before tests
-await ai('install Chrome browser');
-await ai('install Node.js version 18');
-await ai('install PostgreSQL database');
-```
-
-### System Configuration
-
-Configure system settings and preferences:
-
-```javascript
-// Set environment variables
-await ai('set NODE_ENV to production');
-
-// Configure system settings
-await ai('enable dark mode');
-await ai('set screen resolution to 1920x1080');
-```
-
-## Exec Command
-
-The `exec` command allows you to run shell commands directly in the sandbox:
-
-```javascript
-import { exec } from '@testdriverai/sdk';
-
-// Install packages via package manager
-await exec('apt-get update && apt-get install -y git');
-
-// Run setup scripts
-await exec('npm install -g typescript');
-
-// Configure applications
-await exec('cp config.json /etc/myapp/config.json');
-```
-
-### Examples
-
-#### Installing Development Tools
-
-```javascript
-// Install common development tools
-await exec('apt-get update');
-await exec('apt-get install -y curl wget git vim');
-```
-
-#### Setting Up a Web Server
-
-```javascript
-// Install and configure nginx
-await exec('apt-get install -y nginx');
-await exec('systemctl start nginx');
-await exec('systemctl enable nginx');
-```
-
-#### Installing Language Runtimes
-
-```javascript
-// Install Python and pip
-await exec('apt-get install -y python3 python3-pip');
-await exec('pip3 install requests pytest');
-```
-
-## Pre-Test Setup
-
-Run setup commands before each test:
-
-```javascript
-import { beforeAll } from 'vitest';
-
-beforeAll(async () => {
-  // Install dependencies
-  await exec('npm install');
-  
-  // Start services
-  await exec('npm run start-server &');
-  
-  // Wait for service to be ready
-  await ai('wait for server to start on port 3000');
-});
-```
-
-## Environment Templates
-
-Create reusable environment configurations:
-
-```javascript
-// environments/chrome-dev.js
-export async function setupChromeDev() {
-  await exec('apt-get update');
-  await exec('apt-get install -y google-chrome-stable');
-  await exec('npm install -g lighthouse');
-}
-
-// Use in tests
-import { setupChromeDev } from './environments/chrome-dev';
-
-beforeAll(async () => {
-  await setupChromeDev();
-});
-```
-
-## Custom VM Images (Enterprise)
-
-For more complex customization needs, Enterprise customers can work with TestDriver to create custom VM images.
-
-### Benefits of Custom AMIs
-
-- **Faster Startup**: Pre-installed applications ready to use
-- **Consistency**: Identical environments across all test runs
-- **Complex Setup**: Handle intricate installation procedures once
-- **Version Control**: Track and manage environment changes
-
-### What Can Be Pre-Installed
-
-- Desktop applications (browsers, IDEs, etc.)
-- System dependencies and libraries
-- Language runtimes and frameworks
-- Database servers and tools
-- Custom certificates and credentials
-- System configurations and settings
-
-### Working with TestDriver
-
-Enterprise customers receive dedicated support for custom environments:
-
-1. **Requirements Gathering**: Discuss your environment needs
-2. **AMI Development**: We build and test the custom image
-3. **Validation**: Review and approve the environment
-4. **Deployment**: Roll out to your test infrastructure
-5. **Maintenance**: Regular updates and security patches
-
-Learn more about custom environments in our [Enterprise documentation](/v7/features/enterprise#custom-environments).
-
-## Best Practices
-
-### Keep Setup Scripts Fast
-
-- Pre-install large dependencies in custom AMIs when possible
-- Cache downloaded files and packages
-- Run setup in parallel when independent
-
-### Make Setup Idempotent
-
-- Check if software is already installed before installing
-- Use version checks to avoid unnecessary reinstalls
-- Handle errors gracefully
-
-```javascript
-async function ensureNodeInstalled() {
-  try {
-    await exec('node --version');
-  } catch {
-    await exec('curl -fsSL https://deb.nodesource.com/setup_18.x | bash -');
-    await exec('apt-get install -y nodejs');
-  }
-}
-```
-
-### Version Lock Dependencies
-
-- Specify exact versions of tools and packages
-- Avoid "latest" tags that can change
-- Document version requirements
-
-```javascript
-// Good - specific version
-await exec('npm install -g typescript@5.3.3');
-
-// Avoid - version may change
-await exec('npm install -g typescript');
-```
-
-## Troubleshooting
-
-### Installation Failures
-
-Check logs for detailed error messages:
-
-```javascript
-try {
-  await exec('apt-get install -y mypackage');
-} catch (error) {
-  console.error('Installation failed:', error);
-}
-```
-
-### Permission Issues
-
-Some commands may require sudo:
-
-```javascript
-await exec('sudo apt-get update');
-```
-
-### Network Issues
-
-Ensure your sandbox has internet access for downloads:
-
-```javascript
-// Test connectivity
-await exec('ping -c 3 google.com');
-```
-
-## Learn More
-
-- [Exec API Reference](/v7/api/exec)
-- [Managed Sandboxes](/v7/features/managed-sandboxes)
-- [Enterprise Features](/v7/features/enterprise)

package/docs/v7/features/stable.mdx

@@ -1,473 +0,0 @@
----
-title: "Flake Prevention"
-description: "Anti-flake technology that eliminates test instability"
-icon: "shield-check"
----
-
-Test flakiness is the bane of CI/CD pipelines. TestDriver eliminates flaky tests with built-in anti-flake technology that automatically handles timing issues, animations, and dynamic content.
-
-## The Flaky Test Problem
-
-Traditional test frameworks suffer from race conditions and timing issues:
-
-<CodeGroup>
-```javascript Traditional - Flaky
-// ❌ May fail randomly
-await page.click('button');
-await page.click('.dropdown-item'); // Element might not be ready!
-
-// ❌ Arbitrary waits
-await page.click('button');
-await page.waitForTimeout(1000); // Hope 1 second is enough
-await page.click('.dropdown-item');
-
-// ❌ Complex wait logic
-await page.click('button');
-await page.waitForSelector('.dropdown-item', {
-  state: 'visible',
-  timeout: 5000
-});
-await page.waitForLoadState('networkidle');
-await page.waitForTimeout(200); // Still need extra buffer!
-await page.click('.dropdown-item');
-```
-
-```javascript TestDriver - Stable
-// ✅ Just works
-await testdriver.find('button').click();
-await testdriver.find('dropdown item').click();
-// TestDriver automatically waits for stability
-```
-</CodeGroup>
-
-<Check>
-  TestDriver handles all timing automatically. No explicit waits, no arbitrary timeouts, no flaky tests.
-</Check>
-
-## Redraw Detection
-
-TestDriver's redraw detection system automatically waits for the UI to stabilize before taking any action.
-
-<Card title="What Redraw Detects" icon="eye">
-  The system monitors multiple stability signals:
-
-  - **Layout Reflows** - Position or size changes
-  - **CSS Animations** - Running animations and transitions
-  - **Network Activity** - Pending XHR/fetch requests
-  - **Visual Changes** - Pixel-level screenshot differences
-  - **Loading Indicators** - Spinners, progress bars, skeleton screens
-</Card>
-
-### How It Works
-
-```mermaid
-sequenceDiagram
-    participant Test as Your Test
-    participant TD as TestDriver
-    participant Monitor as Redraw Monitor
-    participant UI as Application UI
-
-    Test->>TD: find('dropdown item').click()
-    TD->>Monitor: Start monitoring stability
-    Monitor->>UI: Capture initial state
-
-    loop Stability Check
-        Monitor->>UI: Check for changes
-        alt UI is changing
-            UI-->>Monitor: DOM mutation detected
-            Monitor->>Monitor: Reset stability timer
-        else UI is stable
-            UI-->>Monitor: No changes
-            Monitor->>Monitor: Increment stable duration
-        end
-    end
-
-    Monitor->>TD: UI stable for 200ms
-    TD->>UI: Perform click action
-    TD-->>Test: Action completed
-```
-
-### Configurable Stability
-
-Fine-tune stability detection for your application's needs:
-
-```javascript
-// Default stability settings (recommended)
-await testdriver.find('button').click();
-
-// Disable redraw detection for specific actions (advanced)
-await testdriver.find('element', {
-  redraw: {
-    enabled: false // Skip stability detection
-  }
-}).click();
-
-// Disable only screen monitoring (keep network monitoring)
-await testdriver.find('animated element', {
-  redraw: {
-    screenRedraw: false // Skip screen stability, still wait for network
-  }
-}).click();
-```
-
-<Tip>
-  The default redraw settings work for 95% of applications. Only adjust if you have unusually subtle animations or need to bypass stability checks.
-</Tip>
-
-## Network Monitoring
-
-TestDriver waits for network activity to complete before asserting or locating elements:
-
-<AccordionGroup>
-  <Accordion title="Automatic Network Waiting">
-    ```javascript
-    // TestDriver automatically waits for:
-    // 1. Pending XHR/fetch requests to complete
-    // 2. WebSocket messages to be processed
-    // 3. Image/asset loading to finish
-
-    await testdriver.find('submit button').click();
-    // ↑ Triggers API call
-
-    await testdriver.assert('Success message is visible');
-    // ↑ Automatically waits for API response before asserting
-    ```
-
-    No need for manual `waitForResponse` or `waitForLoadState` calls.
-  </Accordion>
-
-  <Accordion title="Loading Indicator Detection">
-    ```javascript
-    // TestDriver detects common loading patterns:
-    await testdriver.find('Load More button').click();
-
-    // Automatically waits for:
-    // - Loading spinner to appear and disappear
-    // - Skeleton screens to be replaced
-    // - Progress bars to complete
-    // - "Loading..." text to disappear
-
-    await testdriver.find('newly loaded content').click();
-    ```
-
-    Common loading indicators are recognized and waited for automatically.
-  </Accordion>
-
-  <Accordion title="Custom Polling for Slow Elements">
-    ```javascript
-    // For elements that take time to appear, use polling
-    async function waitForElement(description, timeoutMs = 60000) {
-      const startTime = Date.now();
-      while (Date.now() - startTime < timeoutMs) {
-        const element = await testdriver.find(description);
-        if (element.found()) return element;
-        await new Promise(r => setTimeout(r, 1000));
-      }
-      throw new Error(`Element "${description}" not found`);
-    }
-    
-    const button = await waitForElement('submit button');
-    await button.click();
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Screen Stability Monitoring
-
-Visual stability is critical for reliable element location:
-
-```javascript
-// TestDriver monitors pixel-level changes
-await testdriver.find('animated element').click();
-
-// Waits for:
-// ✓ CSS animations to complete
-// ✓ Fade-in/fade-out effects to finish
-// ✓ Slide transitions to settle
-// ✓ Scroll animations to stop
-// ✓ Dynamic content to load
-```
-
-<Card title="Example: Accordion Animation" icon="angles-down">
-  ```javascript
-  // Traditional approach - prone to failure
-  await page.click('.accordion-header');
-  await page.waitForTimeout(300); // Hope animation is done
-  await page.click('.accordion-content button'); // Might fail!
-
-  // TestDriver - just works
-  await testdriver.find('accordion header').click();
-  await testdriver.find('button inside accordion content').click();
-  // ✅ Automatically waits for accordion animation to complete
-  ```
-</Card>
-
-## Debugging Element Location
-
-When elements aren't found, TestDriver provides detailed debugging information to help you understand why:
-
-<Steps>
-  <Step title="Check Element Existence">
-    Verify if the element was found before interacting with it.
-
-    ```javascript
-    const element = await testdriver.find('button');
-    if (element.found()) {
-      await element.click();
-    } else {
-      console.log('Button not found on page');
-    }
-    ```
-  </Step>
-
-  <Step title="Review Debug Information">
-    Access detailed debugging data from the element response.
-
-    ```javascript
-    const element = await testdriver.find('submit button');
-    
-    console.log('Found:', element.found());
-    console.log('Similarity:', element.aiResponse?.similarity);
-    console.log('Cache hit:', element.aiResponse?.cacheHit);
-    console.log('Screenshot:', element.screenshotPath);
-    ```
-  </Step>
-
-  <Step title="Analyze Visual Differences">
-    Compare what TestDriver saw vs. what you expected.
-
-    ```javascript
-    const element = await testdriver.find('login button');
-    
-    if (!element.found()) {
-      // Screenshot shows what TestDriver analyzed
-      console.log('Check screenshot:', element.screenshotPath);
-      
-      // Similarity score indicates how close it got
-      console.log('Best match similarity:', element.aiResponse?.similarity);
-      
-      // Review the description for clarity
-      console.log('Search description:', 'login button');
-    }
-    ```
-  </Step>
-
-  <Step title="Refine Your Description">
-    Use debug insights to improve element descriptions.
-
-    ```javascript
-    // Too vague
-    const btn = await testdriver.find('button');
-    
-    // Better - more specific
-    const loginBtn = await testdriver.find('blue login button in header');
-    
-    // Best - unique identifying features
-    const submitBtn = await testdriver.find('submit button with arrow icon');
-    ```
-  </Step>
-</Steps>
-
-## Polling for Dynamic Elements
-
-For elements that may take time to appear, implement polling:
-
-```javascript
-// Standard polling for normal elements
-const timeoutMs = 30000; // 30 seconds
-const startTime = Date.now();
-let results;
-
-while (Date.now() - startTime < timeoutMs) {
-  results = await testdriver.find('search results');
-  if (results.found()) break;
-  await new Promise(r => setTimeout(r, 1000)); // Check every second
-}
-
-if (results.found()) {
-  await results.click();
-}
-```
-
-## Advanced: Redraw Configuration
-
-The redraw system is configurable through [redraw.js](/agent/lib/redraw.js):
-
-```javascript
-// Global redraw settings
-const testdriver = new TestDriver({
-  apiKey: process.env.TD_API_KEY,
-  redraw: {
-    enabled: true,            // Master switch for redraw detection
-    screenRedraw: true,       // Enable screen stability detection
-    networkMonitor: true,     // Enable network activity monitoring
-  }
-});
-```
-
-### Per-Action Configuration
-
-```javascript
-// Override redraw settings for specific actions
-await testdriver.find('fast element', {
-  redraw: {
-    enabled: false // Skip redraw detection entirely
-  }
-}).click();
-
-await testdriver.find('element with animation', {
-  redraw: {
-    screenRedraw: false, // Skip screen stability check
-    networkMonitor: true // Still wait for network to settle
-  }
-}).click();
-```
-
-## Debugging Stability Issues
-
-If you encounter stability issues, TestDriver provides detailed diagnostics:
-
-```javascript
-// Enable verbose logging to see redraw detection in action
-const testdriver = new TestDriver({
-  apiKey: process.env.TD_API_KEY,
-  verbosity: 2 // Show detailed redraw logs
-});
-
-await testdriver.find('element').click();
-// Console output will show:
-// [redraw] Screen diff: 0.15%
-// [redraw] Network activity: 1250 b/s
-// [redraw] Waiting for stability...
-```
-
-## Common Stability Patterns
-
-<AccordionGroup>
-  <Accordion title="Dropdown Menus">
-    ```javascript
-    // Traditional - flaky
-    await page.click('.menu-button');
-    await page.waitForTimeout(200);
-    await page.click('.menu-item');
-
-    // TestDriver - stable
-    await testdriver.find('menu button').click();
-    await testdriver.find('menu item').click();
-    ```
-  </Accordion>
-
-  <Accordion title="Modal Dialogs">
-    ```javascript
-    // Traditional - flaky
-    await page.click('.open-modal');
-    await page.waitForSelector('.modal', { state: 'visible' });
-    await page.waitForTimeout(300); // Wait for animation
-    await page.click('.modal-button');
-
-    // TestDriver - stable
-    await testdriver.find('open modal button').click();
-    await testdriver.find('modal button').click();
-    ```
-  </Accordion>
-
-  <Accordion title="Infinite Scroll">
-    ```javascript
-    // Traditional - flaky
-    await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
-    await page.waitForTimeout(1000);
-    await page.waitForLoadState('networkidle');
-    await page.click('.load-more');
-
-    // TestDriver - stable
-    await testdriver.scroll('down', 1000);
-    await testdriver.find('load more button').click();
-    ```
-  </Accordion>
-
-  <Accordion title="Form Submissions">
-    ```javascript
-    // Traditional - flaky
-    await page.fill('input[name="email"]', 'user@example.com');
-    await page.click('button[type="submit"]');
-    await page.waitForNavigation();
-    await page.waitForTimeout(500);
-
-    // TestDriver - stable
-    await testdriver.find('email input').type('user@example.com');
-    await testdriver.find('submit button').click();
-    await testdriver.assert('success message is visible');
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Best Practices
-
-<Card title="Let TestDriver Handle Timing" icon="clock">
-  Don't:
-  ```javascript
-  await testdriver.find('button').click();
-  await new Promise(resolve => setTimeout(resolve, 1000)); // ❌
-  ```
-
-  Do:
-  ```javascript
-  await testdriver.find('button').click();
-  await testdriver.find('next element').click(); // ✅
-  ```
-
-  Trust TestDriver's automatic stability detection.
-</Card>
-
-<Card title="Use Natural Assertions" icon="check">
-  Don't:
-  ```javascript
-  await testdriver.find('button').click();
-  const element = await testdriver.find('result');
-  expect(element).toBeTruthy(); // ❌ Redundant
-  ```
-
-  Do:
-  ```javascript
-  await testdriver.find('button').click();
-  await testdriver.assert('result is visible'); // ✅ Natural
-  ```
-
-  TestDriver's assert automatically waits for stability.
-</Card>
-
-## Learn More
-
-<CardGroup cols={2}>
-  <Card
-    title="Redraw Implementation"
-    icon="code"
-    href="/agent/lib/redraw.js"
-  >
-    View the redraw detection source code
-  </Card>
-
-  <Card
-    title="Error Handling Guide"
-    icon="triangle-exclamation"
-    href="/v7/guides/error-handling"
-  >
-    Learn about error handling patterns
-  </Card>
-
-  <Card
-    title="Best Practices"
-    icon="star"
-    href="/v7/guides/best-practices"
-  >
-    Testing best practices with TestDriver
-  </Card>
-
-  <Card
-    title="Debugging Guide"
-    icon="bug"
-    href="/v7/guides/debugging"
-  >
-    Debug failing tests effectively
-  </Card>
-</CardGroup>