testdriverai 7.0.0 → 7.1.1

package/docs/v7/api/elements.mdx

@@ -194,11 +194,11 @@ await target.mouseUp();
 
 ### Properties
 
-Element properties provide additional information about located elements:
+Element properties provide additional information about located elements. Properties are available after a successful `find()` call.
 
 #### coordinates
 
-Get the element's coordinates object.
+Get the element's coordinates object containing all position information.
 
 ```javascript
 const coords = element.getCoordinates()
@@ -206,115 +206,217 @@ const coords = element.getCoordinates()
 element.coordinates
 ```
 
-**Returns:** Object with `{ x, y, centerX, centerY }` or `null`
+**Returns:** `Object | null` - Coordinate object with `{ x, y, centerX, centerY }`
 
 **Example:**
 ```javascript
 const button = await testdriver.find('submit button');
 const coords = button.coordinates;
-console.log(`Top-left: (${coords.x}, ${coords.y})`);
-console.log(`Center: (${coords.centerX}, ${coords.centerY})`);
+
+if (coords) {
+  console.log(`Top-left: (${coords.x}, ${coords.y})`);
+  console.log(`Center: (${coords.centerX}, ${coords.centerY})`);
+}
 ```
 
 #### x, y, centerX, centerY
 
-Direct access to coordinate values.
+Direct access to coordinate values. Always available after successful `find()`.
 
 ```javascript
-element.x        // Top-left X coordinate
-element.y        // Top-left Y coordinate  
-element.centerX  // Center X coordinate
-element.centerY  // Center Y coordinate
+element.x        // Top-left X coordinate (number)
+element.y        // Top-left Y coordinate (number)
+element.centerX  // Center X coordinate (number)
+element.centerY  // Center Y coordinate (number)
 ```
 
 **Example:**
 ```javascript
 const button = await testdriver.find('submit button');
+console.log(`Button at: (${button.x}, ${button.y})`);
 console.log(`Button center: (${button.centerX}, ${button.centerY})`);
+
+// Use for custom mouse operations
+await testdriver.click(button.centerX, button.centerY);
+```
+
+#### width, height
+
+Element dimensions in pixels. Available when AI detects element bounds.
+
+```javascript
+element.width   // Width in pixels (number | null)
+element.height  // Height in pixels (number | null)
+```
+
+**Example:**
+```javascript
+const button = await testdriver.find('submit button');
+
+if (button.width && button.height) {
+  console.log(`Button size: ${button.width}x${button.height}px`);
+  
+  // Check if button is large enough
+  if (button.width < 50) {
+    console.warn('Button might be too small');
+  }
+}
+```
+
+#### boundingBox
+
+Complete bounding box information including position and dimensions.
+
+```javascript
+element.boundingBox
+```
+
+**Returns:** `Object | null` - Bounding box with all dimension data
+
+```typescript
+{
+  x: number,        // Top-left X
+  y: number,        // Top-left Y
+  width: number,    // Width in pixels
+  height: number    // Height in pixels
+}
+```
+
+**Example:**
+```javascript
+const element = await testdriver.find('dialog box');
+
+if (element.boundingBox) {
+  const { x, y, width, height } = element.boundingBox;
+  console.log(`Dialog: ${width}x${height} at (${x}, ${y})`);
+  
+  // Calculate if element is in viewport
+  const rightEdge = x + width;
+  const bottomEdge = y + height;
+  console.log(`Element extends to (${rightEdge}, ${bottomEdge})`);
+}
 ```
 
 #### screenshot
 
-Get a base64-encoded screenshot of the element (if available).
+Base64-encoded PNG screenshot of the screen when element was found. Only available in DEBUG mode or when an error occurs.
 
 ```javascript
 element.screenshot
 ```
 
-**Returns:** `string | null` - Base64-encoded image
+**Returns:** `string | null` - Base64-encoded PNG image
 
 **Example:**
 ```javascript
 const element = await testdriver.find('error message');
+
 if (element.screenshot) {
-  console.log('Element screenshot:', element.screenshot);
+  // Save screenshot to file
+  const fs = require('fs');
+  const base64Data = element.screenshot.replace(/^data:image\/\w+;base64,/, '');
+  fs.writeFileSync('element-screenshot.png', Buffer.from(base64Data, 'base64'));
+  console.log('Screenshot saved');
 }
 ```
 
+<Warning>
+  Screenshots can be large. They're automatically excluded from error messages to prevent memory issues.
+</Warning>
+
 #### text
 
-Get text content from the element (if available).
+Text content extracted from the element by AI (if available).
 
 ```javascript
 element.text
 ```
 
-**Returns:** `string | null`
+**Returns:** `string | null` - Element's text content
 
 **Example:**
 ```javascript
 const message = await testdriver.find('notification message');
-console.log('Message text:', message.text);
+
+if (message.text) {
+  console.log('Message says:', message.text);
+  
+  // Use text content in assertions
+  if (message.text.includes('success')) {
+    console.log('Success message detected');
+  }
+}
+
+// Another example - extracting button label
+const button = await testdriver.find('blue button');
+console.log('Button text:', button.text); // "Submit"
 ```
 
-#### confidence
+#### label
 
-Get the AI's confidence score for the element match.
+Accessible label or name of the element (if available). Useful for verifying accessibility.
 
 ```javascript
-element.confidence
+element.label
 ```
 
-**Returns:** `number | null` - Confidence score (0-1)
+**Returns:** `string | null` - Accessible label
 
 **Example:**
 ```javascript
-const element = await testdriver.find('submit button');
-if (element.confidence < 0.8) {
-  console.warn('Low confidence match:', element.confidence);
+const input = await testdriver.find('first input field');
+
+if (input.label) {
+  console.log('Input label:', input.label); // "Email Address"
 }
 ```
 
-#### width, height
+#### confidence
 
-Get element dimensions (if available).
+AI confidence score for the element match (0-1, where 1 is perfect confidence).
 
 ```javascript
-element.width
-element.height
+element.confidence
 ```
 
-**Returns:** `number | null`
-
-#### boundingBox
-
-Get the complete bounding box information.
+**Returns:** `number | null` - Confidence score between 0 and 1
 
+**Example:**
 ```javascript
-element.boundingBox
-```
+const element = await testdriver.find('submit button');
 
-**Returns:** `Object | null` - Bounding box with coordinates and dimensions
+if (element.confidence !== null) {
+  const percentage = (element.confidence * 100).toFixed(1);
+  console.log(`Match confidence: ${percentage}%`);
+  
+  if (element.confidence < 0.8) {
+    console.warn('⚠️ Low confidence match - element might not be correct');
+  } else if (element.confidence > 0.95) {
+    console.log('✅ High confidence match');
+  }
+}
+```
 
-#### label
+<Tip>
+  Confidence scores below 0.8 may indicate the element description was ambiguous or the wrong element was found.
+</Tip>
 
-Get the element's label or accessible name (if available).
+### Property Availability
 
-```javascript
-element.label
-```
+| Property | When Available |
+|----------|---------------|
+| `x`, `y`, `centerX`, `centerY` | ✅ Always after successful `find()` |
+| `coordinates` | ✅ Always after successful `find()` |
+| `width`, `height` | ⚠️ When AI detects element bounds |
+| `boundingBox` | ⚠️ When AI detects element bounds |
+| `text` | ⚠️ When AI extracts text content |
+| `label` | ⚠️ When element has accessible label |
+| `confidence` | ✅ Always after AI element finding |
+| `screenshot` | ⚠️ Only in DEBUG mode or on errors |
 
-**Returns:** `string | null`
+<Note>
+  Properties marked with ⚠️ may be `null` depending on what the AI could detect from the screenshot.
+</Note>
 
 ## Polling for Elements
 

package/docs/v7/api/find.mdx

@@ -314,3 +314,261 @@ describe('Element Finding', () => {
 - [`hover()`](/v7/api/hover) - Hover over elements
 - [`assert()`](/v7/api/assert) - Verify element states
 - [Elements Reference](/v7/api/elements) - Complete Element API
+
+---
+
+## findAll()
+
+Locate **all elements** matching a description, rather than just one.
+
+### Syntax
+
+```javascript
+const elements = await testdriver.findAll(description, options)
+```
+
+### Parameters
+
+<ParamField path="description" type="string" required>
+  Natural language description of elements to find
+</ParamField>
+
+<ParamField path="options" type="object | number">
+  Optional cache options (same as `find()`)
+  
+  <Expandable title="properties">
+    <ParamField path="cacheKey" type="string">
+      Cache key for storing element location
+    </ParamField>
+    
+    <ParamField path="cacheThreshold" type="number" default={-1}>
+      Similarity threshold (0-1) for cache matching. Set to -1 to disable cache.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Returns
+
+`Promise<Element[]>` - Array of Element instances
+
+### Examples
+
+#### Basic Usage
+
+```javascript
+// Find all matching elements
+const buttons = await testdriver.findAll('button');
+console.log(`Found ${buttons.length} buttons`);
+
+// Interact with specific element
+if (buttons.length > 0) {
+  await buttons[0].click(); // Click first button
+}
+
+// Iterate over all
+for (const button of buttons) {
+  console.log(`Button at (${button.x}, ${button.y})`);
+}
+```
+
+#### Finding Multiple Items
+
+```javascript
+// Find all list items
+const items = await testdriver.findAll('list item');
+
+// Find specific item by index
+const thirdItem = items[2];
+await thirdItem.click();
+
+// Check all items
+for (let i = 0; i < items.length; i++) {
+  console.log(`Item ${i + 1}: ${items[i].text || 'No text'}`);
+}
+```
+
+#### With Caching
+
+```javascript
+// Cache element locations for faster subsequent runs
+const menuItems = await testdriver.findAll('menu item', {
+  cacheKey: 'main-menu-items'
+});
+
+// First run: ~2-3 seconds (AI call)
+// Subsequent runs: ~100ms (cache hit)
+```
+
+#### Empty Results
+
+```javascript
+// Returns empty array if nothing found (doesn't throw error)
+const errors = await testdriver.findAll('error message');
+
+if (errors.length === 0) {
+  console.log('No errors found - test passed!');
+} else {
+  console.log(`Found ${errors.length} errors`);
+}
+```
+
+### Differences from find()
+
+| Feature | find() | findAll() |
+|---------|--------|-----------|
+| Return type | Single `Element` | Array of `Element[]` |
+| If nothing found | Throws `ElementNotFoundError` | Returns empty array `[]` |
+| Chainable | ✅ Yes: `await find('button').click()` | ❌ No (returns array) |
+| Use case | One specific element | Multiple similar elements |
+| Cache support | ✅ Yes | ✅ Yes |
+
+### Use Cases
+
+<AccordionGroup>
+  <Accordion title="Table Rows">
+    ```javascript
+    // Find all rows in a table
+    const rows = await testdriver.findAll('table row');
+    
+    // Click every row
+    for (const row of rows) {
+      await row.click();
+      await new Promise(r => setTimeout(r, 500)); // Wait between clicks
+    }
+    
+    // Or click specific row
+    await rows[2].click(); // Click third row
+    ```
+  </Accordion>
+  
+  <Accordion title="Checkboxes/Radio Buttons">
+    ```javascript
+    // Find all checkboxes
+    const checkboxes = await testdriver.findAll('checkbox');
+    
+    // Check all boxes
+    for (const checkbox of checkboxes) {
+      await checkbox.click();
+    }
+    
+    // Or select first unchecked
+    const unchecked = checkboxes[0];
+    await unchecked.click();
+    ```
+  </Accordion>
+  
+  <Accordion title="Navigation Links">
+    ```javascript
+    // Find all navigation links
+    const navLinks = await testdriver.findAll('navigation link');
+    
+    // Validate all are present
+    expect(navLinks.length).toBeGreaterThan(0);
+    
+    // Click specific link by text
+    const homeLink = navLinks.find(link => 
+      link.text?.toLowerCase().includes('home')
+    );
+    
+    if (homeLink) {
+      await homeLink.click();
+    }
+    ```
+  </Accordion>
+  
+  <Accordion title="Conditional Interactions">
+    ```javascript
+    // Check if any error messages exist
+    const errors = await testdriver.findAll('error message');
+    
+    if (errors.length > 0) {
+      console.log(`Found ${errors.length} validation errors`);
+      
+      // Log each error location
+      errors.forEach((error, i) => {
+        console.log(`Error ${i + 1} at (${error.x}, ${error.y})`);
+      });
+    } else {
+      console.log('Form validation passed!');
+    }
+    ```
+  </Accordion>
+</AccordionGroup>
+
+### Complete Example
+
+```javascript
+import { test, expect } from 'vitest';
+import { chrome } from 'testdriverai/presets';
+
+test('select multiple items from list', async (context) => {
+  const { testdriver } = await chrome(context, {
+    url: 'https://example.com/products'
+  });
+  
+  // Find all product cards
+  const products = await testdriver.findAll('product card');
+  
+  expect(products.length).toBeGreaterThan(0);
+  console.log(`Found ${products.length} products`);
+  
+  // Click first 3 products
+  const productsToSelect = Math.min(3, products.length);
+  
+  for (let i = 0; i < productsToSelect; i++) {
+    await products[i].click();
+    console.log(`Selected product ${i + 1}`);
+    await new Promise(r => setTimeout(r, 500)); // Brief pause
+  }
+  
+  // Verify selections
+  const selectedBadges = await testdriver.findAll('selected badge');
+  expect(selectedBadges.length).toBe(productsToSelect);
+});
+```
+
+### Best Practices
+
+<Check>
+  **Handle empty arrays gracefully**
+  
+  ```javascript
+  // ✅ Good - check length first
+  const items = await testdriver.findAll('list item');
+  if (items.length > 0) {
+    await items[0].click();
+  }
+  
+  // ❌ Bad - may throw error
+  const items = await testdriver.findAll('list item');
+  await items[0].click(); // Error if array is empty!
+  ```
+</Check>
+
+<Check>
+  **Use find() for single elements**
+  
+  ```javascript
+  // ✅ Use find() when you need exactly one
+  const submitBtn = await testdriver.find('submit button');
+  await submitBtn.click();
+  
+  // ❌ Unnecessary - findAll() returns array
+  const buttons = await testdriver.findAll('submit button');
+  await buttons[0].click(); // Extra array handling
+  ```
+</Check>
+
+<Check>
+  **Cache for performance**
+  
+  ```javascript
+  // First run - slow (AI call)
+  const items = await testdriver.findAll('menu item', {
+    cacheKey: 'menu-items'
+  });
+  
+  // Subsequent runs - fast (cache hit)
+  // ~10-20x faster than without cache
+  ```
+</Check>

package/docs/v7/api/mouseDown.mdx

@@ -0,0 +1,161 @@
+---
+title: "mouseDown"
+description: "Press the mouse button without releasing it"
+icon: "arrow-pointer"
+---
+
+## Overview
+
+The `mouseDown()` method presses the mouse button at an element's location without releasing it. This is useful for drag operations, custom gestures, or when you need precise control over mouse events. You can either call it on an [`Element`](/v7/core-concepts/elements) instance or use it directly with a selector.
+
+## Syntax
+
+```javascript
+// Mouse down on an element
+await element.mouseDown();
+
+// Mouse down using a selector
+await ai.mouseDown('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 where the mouse button should be pressed |
+
+## Returns
+
+Returns a `Promise<void>` that resolves when the mouse button is pressed.
+
+## Examples
+
+### Basic Drag Operation
+
+```javascript
+// Start dragging an item
+const dragItem = await ai.find('file to drag');
+await dragItem.mouseDown();
+
+// Move to drop target
+const dropTarget = await ai.find('folder to drop into');
+await dropTarget.hover();
+
+// Release
+await ai.mouseUp();
+```
+
+### Drag and Drop with Direct Selectors
+
+```javascript
+await ai.mouseDown('draggable card');
+await ai.hover('drop zone');
+await ai.mouseUp();
+```
+
+### Selecting Multiple Items
+
+```javascript
+import { test } from 'vitest';
+import { chrome } from '@testdriver/sdk';
+
+test('selects multiple items with click and drag', async () => {
+  const { ai } = await chrome('https://app.example.com');
+  
+  // Start selection at first item
+  await ai.mouseDown('first item in grid');
+  
+  // Drag to last item
+  await ai.hover('last item in grid');
+  
+  // Release to complete selection
+  await ai.mouseUp();
+  
+  // Verify multiple items selected
+  const selectedItems = await ai.find('selected items count');
+  expect(selectedItems.text).toContain('5 items selected');
+});
+```
+
+### Custom Drawing Application
+
+```javascript
+test('draws on canvas', async () => {
+  const { ai } = await chrome('https://drawing-app.example.com');
+  
+  // Start drawing
+  await ai.mouseDown('canvas at top-left corner');
+  
+  // Draw a line by moving mouse
+  await ai.hover('canvas at center');
+  await ai.hover('canvas at bottom-right corner');
+  
+  // Stop drawing
+  await ai.mouseUp();
+  
+  // Verify something was drawn
+  const canvas = await ai.exec('document.querySelector("canvas").toDataURL()');
+  expect(canvas).toBeTruthy();
+});
+```
+
+### Long Press Gesture
+
+```javascript
+test('triggers long press menu', async () => {
+  const { ai } = await chrome('https://mobile-app.example.com');
+  
+  // Press and hold
+  await ai.mouseDown('message in chat');
+  
+  // Wait for long-press menu
+  await new Promise(resolve => setTimeout(resolve, 500));
+  
+  // Verify menu appeared before releasing
+  const menu = await ai.find('message options menu');
+  expect(menu).toBeTruthy();
+  
+  // Release
+  await ai.mouseUp();
+});
+```
+
+### Resizing UI Elements
+
+```javascript
+test('resizes panel', async () => {
+  const { ai } = await vscode();
+  
+  // Grab resize handle
+  await ai.mouseDown('sidebar resize handle');
+  
+  // Drag to new position
+  await ai.hover('position 300 pixels from left edge');
+  
+  // Release
+  await ai.mouseUp();
+  
+  // Verify new size
+  const sidebar = await ai.find('sidebar');
+  expect(sidebar.width).toBeGreaterThan(250);
+});
+```
+
+## Important Notes
+
+- Always pair `mouseDown()` with [`mouseUp()`](/v7/api/mouseUp) to complete the gesture
+- The mouse button remains pressed until `mouseUp()` is called
+- Use [`hover()`](/v7/api/hover) to move the mouse while the button is pressed
+- For simple drag operations, consider using `ai()` with a natural language description like `"drag file to folder"`
+
+## Related Methods
+
+- [`mouseUp()`](/v7/api/mouseUp) - Release the mouse button
+- [`hover()`](/v7/api/hover) - Move mouse to element
+- [`click()`](/v7/api/click) - Full click (mouseDown + mouseUp)
+- [`doubleClick()`](/v7/api/doubleClick) - Double-click on element
+- [`rightClick()`](/v7/api/rightClick) - Right-click for context menu