@testdriverai/agent 7.8.0-test.38

package/docs/v7/redraw.mdx

@@ -0,0 +1,216 @@
+---
+title: "Redraw"
+sidebarTitle: "Redraw"
+description: "Wait for the screen to stabilize after interactions"
+icon: "rotate"
+mode: "wide"
+---
+
+## Overview
+
+The redraw system waits for the screen to stabilize after an interaction before continuing. It detects when animations, page loads, and network requests have settled, preventing actions from being performed on a changing screen.
+
+<Note>
+  **Redraw is disabled by default since v7.3.** Enable it explicitly if your tests interact with applications that have significant animations or loading states.
+</Note>
+
+## How It Works
+
+Redraw uses a **two-phase detection** approach:
+
+1. **Change Detection** — Compare the current frame to the initial screenshot taken right after the action. If the pixel diff exceeds 0.1%, the screen has changed.
+2. **Stability Detection** — Compare consecutive frames using z-score analysis. When the diff between frames drops below 0.1% or the z-score is negative (current diff is below average), the screen has settled.
+
+The screen is considered **settled** when both phases complete: the screen changed from the initial state AND consecutive frames are now stable.
+
+```mermaid
+flowchart TD
+    A[Action performed] --> B{Phase 1: Change Detection\ndiffFromInitial > 0.1%?}
+    B -- "Yes (screen changed)" --> C{Phase 2: Stability\nz-score < 0 or\ndiffPercent < 0.1%?}
+    C -- "Yes (frames stable)" --> D[Screen settled ✓]
+    B -- "No (waiting...)" --> B
+    C -- "No (waiting...)" --> C
+```
+
+### Polling
+
+The system polls at **500ms intervals**, comparing screenshot frames. This reduces WebSocket traffic while still providing responsive detection.
+
+### Pixel Comparison
+
+Uses [pixelmatch](https://github.com/mapbox/pixelmatch) for per-pixel comparison with a threshold of `0.1` for pixel sensitivity. A frame diff above **0.1% of total pixels** indicates the screen has changed.
+
+### Z-Score Analysis
+
+Screen stability uses statistical analysis of the last **10 measurements**:
+
+1. Calculate the mean and standard deviation of consecutive frame diffs
+2. Compute the z-score: `(currentDiff - mean) / stddev`
+3. Screen is stable when `diffPercent < 0.1%` or `z-score < 0` (current diff is below the average)
+
+This approach adapts to the specific animation patterns of your application rather than using a fixed threshold.
+
+## Per-Command Timeouts
+
+Each command type has a specific redraw timeout:
+
+| Command | Timeout | Reason |
+|---------|---------|--------|
+| `click` | 5000ms | Page navigations, modal openings |
+| `hover` (within click) | 5000ms | Same as click |
+| `hover` (standalone) | 2500ms | Tooltip animations |
+| `scroll` | 5000ms | Lazy-loaded content |
+| `type` | 5000ms | Autocomplete, validation |
+| `pressKeys` | 5000ms | Keyboard shortcuts may trigger changes |
+| `focusApplication` | 1000ms | Window focus animations |
+
+If the timeout is reached before the screen settles, the command continues anyway. The timeout event is available via the `redraw:complete` event.
+
+## Configuration
+
+### Constructor Options
+
+```javascript
+const testdriver = new TestDriver({
+  // Shorthand: enable/disable
+  redraw: true,    // enable with defaults
+  redraw: false,   // disable (default since v7.3)
+
+  // Full configuration
+  redraw: {
+    enabled: true,
+    screenRedraw: true,       // enable screen pixel diff detection
+    networkMonitor: false,    // enable network settling detection
+  },
+});
+```
+
+<ParamField path="redraw" type="RedrawConfig | boolean" default={false}>
+  Redraw configuration. Pass `true`/`false` for shorthand, or an object for fine-grained control.
+
+  <Expandable title="properties">
+    <ParamField path="enabled" type="boolean" default={false}>
+      Enable or disable the redraw system. Default changed to `false` in v7.3.
+    </ParamField>
+    
+    <ParamField path="screenRedraw" type="boolean" default={true}>
+      Enable pixel-diff-based screen change detection. If both `screenRedraw` and `networkMonitor` are `false`, redraw auto-disables.
+    </ParamField>
+    
+    <ParamField path="networkMonitor" type="boolean" default={false}>
+      Enable network traffic monitoring for settling detection. Monitors WebSocket traffic on the sandbox to detect when network activity subsides.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Per-Command Override
+
+Override redraw settings for individual commands:
+
+```javascript
+// Enable redraw for a specific click
+await testdriver.find('load more').click({
+  redraw: { enabled: true },
+});
+
+// Disable redraw for a fast interaction
+await testdriver.find('checkbox').click({
+  redraw: false,
+});
+```
+
+## Network Settling
+
+When `networkMonitor` is enabled, the system also monitors sandbox network traffic:
+
+- Polls for `totalBytesReceived` and `totalBytesSent` from the sandbox
+- Keeps the last **60 measurements**
+- Calculates z-scores for both RX and TX byte rates
+- Network is **settled** when both RX and TX z-scores are negative (traffic is below average)
+- Has a **10-second timeout** for network polling
+- Non-critical: network errors are logged but never throw
+
+The final settling condition requires **both** screen AND network to be settled (when both are enabled).
+
+## Events
+
+The redraw system emits events through the SDK emitter. See [Events](/v7/events) for the full event reference.
+
+| Event | Description |
+|---|---|
+| `redraw:status` | Emitted on each poll with current screen diff, network stats, and timeout info |
+| `redraw:complete` | Emitted when redraw resolves (settled or timed out) |
+
+```javascript
+testdriver.emitter.on('redraw:status', (status) => {
+  console.log(`Screen: ${status.redraw.text}`);
+  console.log(`Network: ${status.network.text}`);
+  console.log(`Timeout: ${status.timeout.text}`);
+});
+
+testdriver.emitter.on('redraw:complete', (result) => {
+  if (result.isTimeout) {
+    console.warn(`Redraw timed out after ${result.timeElapsed}ms`);
+  } else {
+    console.log(`Screen settled in ${result.timeElapsed}ms`);
+  }
+});
+```
+
+## When to Use Redraw
+
+**Enable redraw when:**
+- Testing single-page applications (SPAs) with route transitions
+- Interacting with pages that lazy-load content on scroll
+- Clicking buttons that trigger animations or modals
+- Testing apps with significant network-driven UI updates
+
+**Keep redraw disabled when:**
+- Tests are already stable without it
+- You want faster test execution
+- Your application has minimal animations
+- You're using explicit waits or assertions instead
+
+## Types
+
+```typescript
+interface RedrawConfig {
+  enabled?: boolean;              // Default: false (since v7.3)
+  screenRedraw?: boolean;         // Default: true
+  networkMonitor?: boolean;       // Default: false
+}
+
+interface RedrawStatusEvent {
+  redraw: {
+    enabled: boolean;
+    settled: boolean;
+    hasChangedFromInitial: boolean;
+    consecutiveFramesStable: number;
+    diffFromInitial: number;
+    diffFromLast: number;
+    text: string;
+  };
+  network: {
+    enabled: boolean;
+    settled: boolean;
+    rxBytes: number;
+    txBytes: number;
+    text: string;
+  };
+  timeout: {
+    isTimeout: boolean;
+    elapsed: number;
+    max: number;
+    text: string;
+  };
+}
+
+interface RedrawCompleteEvent {
+  screenSettled: boolean;
+  hasChangedFromInitial: boolean;
+  consecutiveFramesStable: number;
+  networkSettled: boolean;
+  isTimeout: boolean;
+  timeElapsed: number;
+}
+```

package/docs/v7/reusable-code.mdx

@@ -0,0 +1,249 @@
+---
+title: "Reusable Code Snippets"
+description: "Build maintainable test suites with reusable code patterns"
+icon: "recycle"
+---
+
+As your test suite grows, you'll want to extract common patterns into reusable code. This keeps tests DRY, readable, and easy to maintain.
+
+## Helper Functions
+
+The simplest approach is extracting common actions into helper functions. Create a `helpers/` directory for shared utilities:
+
+```javascript test/helpers/auth.js
+export async function login(testdriver, { email, password }) {
+  const emailInput = await testdriver.find('email input');
+  await emailInput.click();
+  await testdriver.type(email);
+  
+  const passwordInput = await testdriver.find('password input');
+  await passwordInput.click();
+  await testdriver.type(password);
+  
+  const loginButton = await testdriver.find('login button');
+  await loginButton.click();
+  
+  const result = await testdriver.assert('user is logged in');
+  return result;
+}
+
+export async function logout(testdriver) {
+  const userMenu = await testdriver.find('user menu');
+  await userMenu.click();
+  
+  const logoutButton = await testdriver.find('logout button');
+  await logoutButton.click();
+}
+```
+
+<Warning>
+**Avoid hardcoding dynamic values in element descriptions.** Element selectors should describe the *type* of element, not specific content that might change.
+
+**❌ Bad:** `await testdriver.find('profile name TestDriver in the top right')`  
+**✅ Good:** `await testdriver.find('user profile name in the top right')`
+
+Hardcoded values like usernames, product names, or prices will cause tests to fail when the data changes. Use generic descriptions that work regardless of the specific content displayed.
+</Warning>
+
+Now import and use these helpers in any test:
+
+```javascript test/checkout.test.mjs
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { login } from './helpers/auth.js';
+
+describe("Checkout", () => {
+  it("should complete checkout as logged in user", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({
+      url: 'https://shop.example.com',
+    });
+
+    // Use the helper
+    await login(testdriver, { 
+      email: 'user@example.com', 
+      password: 'password123' 
+    });
+
+    // Continue with checkout steps...
+    const cartButton = await testdriver.find('cart button');
+    await cartButton.click();
+  });
+});
+```
+
+## Page Objects
+
+For larger test suites, the Page Object pattern encapsulates all interactions with a specific page or component:
+
+```javascript test/pages/LoginPage.js
+export class LoginPage {
+  constructor(testdriver) {
+    this.td = testdriver;
+  }
+
+  async enterEmail(email) {
+    const input = await this.td.find('email input');
+    await input.click();
+    await this.td.type(email);
+  }
+
+  async enterPassword(password) {
+    const input = await this.td.find('password input');
+    await input.click();
+    await this.td.type(password);
+  }
+
+  async submit() {
+    const button = await this.td.find('submit button');
+    await button.click();
+  }
+
+  async login(email, password) {
+    await this.enterEmail(email);
+    await this.enterPassword(password);
+    await this.submit();
+  }
+
+  async assertError(message) {
+    return await this.td.assert(`error message shows "${message}"`);
+  }
+
+  async assertLoggedIn() {
+    return await this.td.assert('user dashboard is visible');
+  }
+}
+```
+
+Use the page object in your tests:
+
+```javascript test/auth.test.mjs
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { LoginPage } from './pages/LoginPage.js';
+
+describe("Authentication", () => {
+  it("should show error for invalid credentials", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({
+      url: 'https://app.example.com/login',
+    });
+
+    const loginPage = new LoginPage(testdriver);
+    
+    await loginPage.login('invalid@test.com', 'wrongpassword');
+    
+    const hasError = await loginPage.assertError('Invalid credentials');
+    expect(hasError).toBeTruthy();
+  });
+
+  it("should redirect to dashboard on success", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({
+      url: 'https://app.example.com/login',
+    });
+
+    const loginPage = new LoginPage(testdriver);
+    
+    await loginPage.login('valid@test.com', 'correctpassword');
+    
+    const isLoggedIn = await loginPage.assertLoggedIn();
+    expect(isLoggedIn).toBeTruthy();
+  });
+});
+```
+
+## Shared Test Fixtures
+
+Create reusable fixtures for common test setup scenarios:
+
+```javascript test/fixtures/index.js
+export const testUsers = {
+  admin: { email: 'admin@example.com', password: 'admin123' },
+  regular: { email: 'user@example.com', password: 'user123' },
+  guest: { email: 'guest@example.com', password: 'guest123' },
+};
+
+export const testUrls = {
+  staging: 'https://staging.example.com',
+  production: 'https://example.com',
+};
+
+export async function setupAuthenticatedSession(testdriver, user = testUsers.regular) {
+  const emailInput = await testdriver.find('email input');
+  await emailInput.click();
+  await testdriver.type(user.email);
+  
+  const passwordInput = await testdriver.find('password input');
+  await passwordInput.click();
+  await testdriver.type(user.password);
+  
+  const loginButton = await testdriver.find('login button');
+  await loginButton.click();
+  
+  await testdriver.assert('user is logged in');
+}
+```
+
+```javascript test/admin.test.mjs
+import { describe, expect, it } from "vitest";
+import { TestDriver } from "testdriverai/lib/vitest/hooks.mjs";
+import { testUsers, testUrls, setupAuthenticatedSession } from './fixtures/index.js';
+
+describe("Admin Panel", () => {
+  it("should access admin settings", async (context) => {
+    const testdriver = TestDriver(context);
+    
+    await testdriver.provision.chrome({
+      url: `${testUrls.staging}/login`,
+    });
+
+    await setupAuthenticatedSession(testdriver, testUsers.admin);
+
+    const settingsLink = await testdriver.find('admin settings link');
+    await settingsLink.click();
+    
+    const result = await testdriver.assert('admin settings panel is visible');
+    expect(result).toBeTruthy();
+  });
+});
+```
+
+## Suggested Project Structure
+
+<FileTree>
+  <Folder name="test" defaultOpen>
+    <Folder name="fixtures" defaultOpen>
+      <File name="index.js" />
+    </Folder>
+    <Folder name="helpers" defaultOpen>
+      <File name="auth.js" />
+      <File name="navigation.js" />
+      <File name="forms.js" />
+    </Folder>
+    <Folder name="pages" defaultOpen>
+      <File name="LoginPage.js" />
+      <File name="DashboardPage.js" />
+      <File name="CheckoutPage.js" />
+    </Folder>
+    <Folder name="specs" defaultOpen>
+      <File name="auth.test.mjs" />
+      <File name="checkout.test.mjs" />
+      <File name="search.test.mjs" />
+    </Folder>
+  </Folder>
+</FileTree>
+
+| Folder | Purpose |
+|--------|---------|
+| `fixtures/` | Test data and setup utilities |
+| `helpers/` | Reusable helper functions |
+| `pages/` | Page object classes |
+| `specs/` | Test files |
+
+<Tip>
+Start simple with helper functions. Only introduce page objects when you find yourself duplicating the same element interactions across multiple tests.
+</Tip>

package/docs/v7/right-click.mdx

@@ -0,0 +1,123 @@
+---
+title: "rightClick"
+description: "Perform a right-click action to open context menus"
+icon: "bars"
+---
+
+## Overview
+
+The `rightClick()` method performs a right-click action on an element, typically used to open context menus. You can either call it on an [`Element`](/v7/core-concepts/elements) instance or use it directly with a selector.
+
+## Syntax
+
+```javascript
+// Right-click on an element
+await element.rightClick();
+
+// Right-click using a selector
+await ai.rightClick('selector');
+```
+
+## Parameters
+
+When called on an `Element`, no parameters are required.
+
+When called directly on the AI client:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `selector` | `string` | The selector describing the element to right-click |
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the right-click action completes.
+
+## Examples
+
+### Right-Click to Open Context Menu
+
+```javascript
+const fileItem = await ai.find('README.md file');
+await fileItem.rightClick();
+
+// Select menu option
+await ai.click('Delete from context menu');
+```
+
+### Direct Right-Click with Selector
+
+```javascript
+await ai.rightClick('image in the gallery');
+await ai.click('Save image as');
+```
+
+### VS Code Context Menu
+
+```javascript
+import { test } from 'vitest';
+import { vscode } from '@testdriver/sdk';
+
+test('renames a file via context menu', async () => {
+  const { ai } = await vscode();
+  
+  // Right-click on a file
+  await ai.rightClick('test.js in the file explorer');
+  
+  // Click rename option
+  await ai.click('Rename');
+  
+  // Type new name
+  await ai.type('test.spec.js');
+  await ai.pressKeys('Enter');
+  
+  // Verify rename
+  const renamedFile = await ai.find('test.spec.js in the file explorer');
+  expect(renamedFile).toBeTruthy();
+});
+```
+
+### Browser Context Menu
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from '@testdriver/sdk';
+
+test('opens link in new tab', async () => {
+  const { ai } = await chrome('https://example.com');
+  
+  // Right-click on a link
+  await ai.rightClick('Documentation link');
+  
+  // Select "Open in new tab"
+  await ai.click('Open link in new tab');
+});
+```
+
+### Custom Context Menu in Web App
+
+```javascript
+test('uses custom context menu', async () => {
+  const { ai } = await chrome('https://app.example.com');
+  
+  // Right-click on custom element
+  await ai.rightClick('project item in the list');
+  
+  // Wait for custom menu to appear
+  await ai.find('custom context menu');
+  
+  // Click menu option
+  await ai.click('Duplicate project');
+  
+  // Verify duplication
+  const duplicatedProject = await ai.find('project item (copy)');
+  expect(duplicatedProject).toBeTruthy();
+});
+```
+
+## Related Methods
+
+- [`click()`](/v7/click) - Single click on an element
+- [`doubleClick()`](/v7/double-click) - Double-click on an element
+- [`mouseDown()`](/v7/mouse-down) - Press mouse button without releasing
+- [`mouseUp()`](/v7/mouse-up) - Release mouse button
+- [`hover()`](/v7/hover) - Move mouse over element without clicking