testdriverai 7.1.4 → 7.2.2

package/docs/v7/features/scalable.mdx

@@ -1,11 +1,226 @@
 ---
-title: "Scalable"
+title: "Scalability"
 description: "From small projects to enterprise test suites with thousands of tests"
 icon: "arrow-up-right-dots"
 ---
 
 TestDriver scales effortlessly from your first test to enterprise suites with thousands of tests running in parallel across multiple platforms.
 
+## Code Snippets for Reusability
+
+Scale your test suite with reusable code snippets to reduce duplication and maintain consistency:
+
+<Tabs>
+  <Tab title="Helper Functions">
+    ```javascript test/helpers/auth.js
+    // Reusable authentication helpers
+    export async function login(testdriver, { email, password }) {
+      await testdriver.find('email input').type(email);
+      await testdriver.find('password input').type(password);
+      await testdriver.find('login button').click();
+      await testdriver.assert('logged in successfully');
+    }
+
+    export async function logout(testdriver) {
+      await testdriver.find('user menu').click();
+      await testdriver.find('logout button').click();
+    }
+    ```
+
+    ```javascript test/checkout.test.js
+    import { login } from './helpers/auth.js';
+
+    test('checkout flow', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+      await login(testdriver, { 
+        email: 'user@example.com',
+        password: 'password123' 
+      });
+      // Continue with checkout test
+    });
+    ```
+  </Tab>
+
+  <Tab title="Page Objects">
+    ```javascript test/pages/LoginPage.js
+    export class LoginPage {
+      constructor(testdriver) {
+        this.testdriver = testdriver;
+      }
+
+      async login(email, password) {
+        await this.testdriver.find('email input').type(email);
+        await this.testdriver.find('password input').type(password);
+        await this.testdriver.find('submit button').click();
+      }
+
+      async assertError(message) {
+        await this.testdriver.assert(`error message shows "${message}"`);
+      }
+    }
+    ```
+
+    ```javascript test/auth.test.js
+    import { LoginPage } from './pages/LoginPage.js';
+
+    test('invalid login shows error', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+      const loginPage = new LoginPage(testdriver);
+      
+      await loginPage.login('invalid@test.com', 'wrong');
+      await loginPage.assertError('Invalid credentials');
+    });
+    ```
+  </Tab>
+
+  <Tab title="Custom Commands">
+    ```javascript test/commands/navigation.js
+    export function addNavigationCommands(testdriver) {
+      testdriver.navigateTo = async (section) => {
+        await testdriver.find(`${section} nav link`).click();
+        await testdriver.assert(`${section} page is loaded`);
+      };
+
+      testdriver.searchFor = async (query) => {
+        await testdriver.find('search input').type(query);
+        await testdriver.find('search button').click();
+        await testdriver.assert('search results are displayed');
+      };
+
+      return testdriver;
+    }
+    ```
+
+    ```javascript test/search.test.js
+    import { addNavigationCommands } from './commands/navigation.js';
+
+    test('search functionality', async (context) => {
+      let { testdriver } = await chrome(context, { url });
+      testdriver = addNavigationCommands(testdriver);
+      
+      await testdriver.searchFor('laptop');
+      // Custom command used
+    });
+    ```
+  </Tab>
+</Tabs>
+
+<Check>
+  Reusable snippets reduce test maintenance time by up to 70% in large test suites.
+</Check>
+
+## Dynamic Variables for Data-Driven Tests
+
+Scale your testing with dynamic data to cover more scenarios:
+
+<Tabs>
+  <Tab title="Environment Variables">
+    ```javascript
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+
+    test('multi-environment testing', async (context) => {
+      const env = process.env.TEST_ENV || 'staging';
+      const urls = {
+        dev: 'https://dev.myapp.com',
+        staging: 'https://staging.myapp.com',
+        production: 'https://myapp.com'
+      };
+
+      const { testdriver } = await chrome(context, { 
+        url: urls[env] 
+      });
+
+      await testdriver.assert('app is running');
+    });
+    ```
+
+    ```bash
+    # Run against different environments
+    TEST_ENV=dev npx vitest run
+    TEST_ENV=staging npx vitest run
+    TEST_ENV=production npx vitest run
+    ```
+  </Tab>
+
+  <Tab title="Test Fixtures">
+    ```javascript test/fixtures/users.js
+    export const testUsers = [
+      { email: 'admin@test.com', role: 'admin' },
+      { email: 'user@test.com', role: 'user' },
+      { email: 'guest@test.com', role: 'guest' }
+    ];
+
+    export const products = [
+      { name: 'Laptop', price: 999 },
+      { name: 'Mouse', price: 29 },
+      { name: 'Keyboard', price: 89 }
+    ];
+    ```
+
+    ```javascript test/permissions.test.js
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+    import { testUsers } from './fixtures/users.js';
+
+    test.each(testUsers)('$role can access dashboard', async ({ email, role }, context) => {
+      const { testdriver } = await chrome(context, { url });
+      
+      await testdriver.find('email input').type(email);
+      await testdriver.find('password input').type('password123');
+      await testdriver.find('login button').click();
+      
+      if (role === 'admin') {
+        await testdriver.assert('admin panel is visible');
+      } else {
+        await testdriver.assert('user dashboard is visible');
+      }
+    });
+    ```
+  </Tab>
+
+  <Tab title="Dynamic Data Generation">
+    ```javascript
+    import { test } from 'vitest';
+    import { chrome } from 'testdriverai/presets';
+    import { faker } from '@faker-js/faker';
+
+    test('user registration with dynamic data', async (context) => {
+      const { testdriver } = await chrome(context, { url });
+
+      // Generate unique test data for each run
+      const userData = {
+        firstName: faker.person.firstName(),
+        lastName: faker.person.lastName(),
+        email: faker.internet.email(),
+        password: faker.internet.password({ length: 12 })
+      };
+
+      await testdriver.find('first name input').type(userData.firstName);
+      await testdriver.find('last name input').type(userData.lastName);
+      await testdriver.find('email input').type(userData.email);
+      await testdriver.find('password input').type(userData.password);
+      await testdriver.find('register button').click();
+
+      await testdriver.assert('registration successful');
+      console.log('Registered user:', userData.email);
+    });
+    ```
+
+    ```bash
+    npm install --save-dev @faker-js/faker
+    ```
+  </Tab>
+</Tabs>
+
+<Card title="Dynamic Variables Best Practices" icon="lightbulb">
+  - **Environment configs:** Store URLs, credentials, and settings in env vars
+  - **Test fixtures:** Maintain reusable test data in separate files
+  - **Data generators:** Use libraries like Faker for unique test data
+  - **Parameterization:** Test multiple scenarios with `test.each()`
+  - **CI/CD integration:** Pass dynamic values via environment variables
+</Card>
+
 ## Works with Vitest
 
 Full integration with Vitest's powerful features:
@@ -25,7 +240,7 @@ export default defineConfig({
 ```
 
 <CardGroup cols={2}>
-  <Card title="Parallel Execution" icon="arrows-split-up-and-left">
+  <Card title="Parallel Execution" icon="layer-group">
     Run multiple tests simultaneously for maximum throughput:
 
     ```bash

package/docs/v7/features/stable.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Stable & Reliable"
+title: "Flake Prevention"
 description: "Anti-flake technology that eliminates test instability"
 icon: "shield-check"
 ---
@@ -51,7 +51,6 @@ TestDriver's redraw detection system automatically waits for the UI to stabilize
 <Card title="What Redraw Detects" icon="eye">
   The system monitors multiple stability signals:
 
-  - **DOM Mutations** - Element additions, removals, or attribute changes
   - **Layout Reflows** - Position or size changes
   - **CSS Animations** - Running animations and transitions
   - **Network Activity** - Pending XHR/fetch requests
@@ -96,19 +95,23 @@ Fine-tune stability detection for your application's needs:
 // Default stability settings (recommended)
 await testdriver.find('button').click();
 
-// Custom stability delay
-await testdriver.find('animated button', {
-  stabilityDelay: 500 // Wait 500ms of stability before acting
+// Disable redraw detection for specific actions (advanced)
+await testdriver.find('element', {
+  redraw: {
+    enabled: false // Skip stability detection
+  }
 }).click();
 
-// Bypass stability (advanced)
-await testdriver.find('element', {
-  stabilityDelay: 0 // Act immediately
+// 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 200ms stability delay works for 95% of applications. Only adjust if you have unusually long animations or need instant actions.
+  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
@@ -150,13 +153,21 @@ TestDriver waits for network activity to complete before asserting or locating e
     Common loading indicators are recognized and waited for automatically.
   </Accordion>
 
-  <Accordion title="Custom Network Conditions">
+  <Accordion title="Custom Polling for Slow Elements">
     ```javascript
-    // For slow networks or long-running requests
-    await testdriver.find('submit button', {
-      timeout: 60000, // Wait up to 60 seconds
-      networkTimeout: 30000 // Allow 30s for network requests
-    }).click();
+    // 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>
@@ -191,135 +202,92 @@ await testdriver.find('animated element').click();
   ```
 </Card>
 
-## Retry Logic
+## Debugging Element Location
 
-TestDriver includes intelligent retry logic that adapts to your application:
+When elements aren't found, TestDriver provides detailed debugging information to help you understand why:
 
 <Steps>
-  <Step title="Initial Attempt">
-    Try to locate the element immediately.
+  <Step title="Check Element Existence">
+    Verify if the element was found before interacting with it.
 
     ```javascript
     const element = await testdriver.find('button');
-    // Attempts location immediately
+    if (element.found()) {
+      await element.click();
+    } else {
+      console.log('Button not found on page');
+    }
     ```
   </Step>
 
-  <Step title="Wait for Stability">
-    If not found, wait for UI stability and retry.
+  <Step title="Review Debug Information">
+    Access detailed debugging data from the element response.
 
     ```javascript
-    // Waits for:
-    // - DOM mutations to stop
-    // - Network requests to complete
-    // - Animations to finish
+    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="Retry with Interval">
-    Continue retrying at regular intervals until timeout.
+  <Step title="Analyze Visual Differences">
+    Compare what TestDriver saw vs. what you expected.
 
     ```javascript
-    await testdriver.find('button', {
-      timeout: 30000,      // Try for up to 30 seconds
-      retryInterval: 500   // Check every 500ms
-    });
+    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="Provide Debug Info">
-    If still not found, provide detailed debugging information.
+  <Step title="Refine Your Description">
+    Use debug insights to improve element descriptions.
 
     ```javascript
-    try {
-      await testdriver.find('missing button');
-    } catch (error) {
-      console.log('Debug screenshot:', error.debugScreenshot);
-      console.log('Similarity score:', error.similarity);
-      console.log('Cache info:', error.cacheInfo);
-    }
+    // 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>
 
-## Configurable Timeouts
-
-Customize retry behavior for different scenarios:
+## Polling for Dynamic Elements
 
-<Tabs>
-  <Tab title="Fast Elements">
-    ```javascript
-    // For elements that appear quickly
-    await testdriver.find('header logo', {
-      timeout: 5000 // 5 seconds (faster failure)
-    });
-    ```
-  </Tab>
-
-  <Tab title="Slow Elements">
-    ```javascript
-    // For elements that take time to load
-    await testdriver.find('search results', {
-      timeout: 30000, // 30 seconds
-      retryInterval: 1000 // Check every second
-    });
-    ```
-  </Tab>
+For elements that may take time to appear, implement polling:
 
-  <Tab title="Critical Elements">
-    ```javascript
-    // For absolutely critical elements
-    await testdriver.find('payment confirmation', {
-      timeout: 60000, // 1 minute
-      retryInterval: 2000, // Check every 2 seconds
-      stabilityDelay: 1000 // Wait 1 second of stability
-    });
-    ```
-  </Tab>
-</Tabs>
-
-## Real-World Stability Improvements
-
-Compare flake rates before and after TestDriver:
-
-<CardGroup cols={2}>
-  <Card title="Before TestDriver" icon="triangle-exclamation">
-    ```
-    Test Suite: E2E Tests
-    Total: 100 tests
-    Passed: 87
-    Failed: 13
-
-    Flaky tests:
-    - login_test (timing)
-    - dropdown_test (animation)
-    - modal_test (async content)
-    - search_test (debounce)
-
-    Flake rate: 13%
-    CI reruns needed: 3-5x
-    ```
-  </Card>
-
-  <Card title="After TestDriver" icon="circle-check">
-    ```
-    Test Suite: E2E Tests
-    Total: 100 tests
-    Passed: 100
-    Failed: 0
-
-    Flaky tests: None
-
-    Flake rate: 0%
-    CI reruns needed: 0
-    Stable builds: 100%
-    ```
-  </Card>
-</CardGroup>
+```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
+}
 
-<Check>
-  **Result: 100% stability** - Eliminated all flaky tests without changing test code.
-</Check>
+if (results.found()) {
+  await results.click();
+}
+```
 
 ## Advanced: Redraw Configuration
 
@@ -330,13 +298,9 @@ The redraw system is configurable through [redraw.js](/agent/lib/redraw.js):
 const testdriver = new TestDriver({
   apiKey: process.env.TD_API_KEY,
   redraw: {
-    enabled: true,
-    stabilityDelay: 200,      // Default stability wait (ms)
-    maxStabilityWait: 5000,   // Maximum time to wait for stability
-    checkInterval: 50,        // How often to check for stability
-    networkIdle: true,        // Wait for network idle
-    domIdle: true,            // Wait for DOM mutations to stop
-    animationIdle: true,      // Wait for CSS animations
+    enabled: true,            // Master switch for redraw detection
+    screenRedraw: true,       // Enable screen stability detection
+    networkMonitor: true,     // Enable network activity monitoring
   }
 });
 ```
@@ -347,14 +311,14 @@ const testdriver = new TestDriver({
 // Override redraw settings for specific actions
 await testdriver.find('fast element', {
   redraw: {
-    enabled: false // Skip redraw detection
+    enabled: false // Skip redraw detection entirely
   }
 }).click();
 
-await testdriver.find('slow element', {
+await testdriver.find('element with animation', {
   redraw: {
-    stabilityDelay: 1000, // Wait longer for stability
-    networkIdle: true
+    screenRedraw: false, // Skip screen stability check
+    networkMonitor: true // Still wait for network to settle
   }
 }).click();
 ```
@@ -364,22 +328,17 @@ await testdriver.find('slow element', {
 If you encounter stability issues, TestDriver provides detailed diagnostics:
 
 ```javascript
-try {
-  await testdriver.find('unstable element', {
-    debug: true // Enable debug logging
-  });
-} catch (error) {
-  console.log('Stability info:', error.stabilityInfo);
-  // Output:
-  // {
-  //   domMutations: 15,
-  //   layoutReflows: 3,
-  //   networkRequests: 2,
-  //   animations: ['fade-in', 'slide-up'],
-  //   waitedMs: 5000,
-  //   stableMs: 150
-  // }
-}
+// 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
@@ -445,13 +404,13 @@ try {
 ## Best Practices
 
 <Card title="Let TestDriver Handle Timing" icon="clock">
-  **Don't:**
+  Don't:
   ```javascript
   await testdriver.find('button').click();
   await new Promise(resolve => setTimeout(resolve, 1000)); // ❌
   ```
 
-  **Do:**
+  Do:
   ```javascript
   await testdriver.find('button').click();
   await testdriver.find('next element').click(); // ✅
@@ -461,14 +420,14 @@ try {
 </Card>
 
 <Card title="Use Natural Assertions" icon="check">
-  **Don't:**
+  Don't:
   ```javascript
   await testdriver.find('button').click();
   const element = await testdriver.find('result');
   expect(element).toBeTruthy(); // ❌ Redundant
   ```
 
-  **Do:**
+  Do:
   ```javascript
   await testdriver.find('button').click();
   await testdriver.assert('result is visible'); // ✅ Natural