testdriverai 7.1.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/type.mdx

@@ -12,7 +12,7 @@ Type text or numbers into the currently focused input field with optional delay
 ## Syntax
 
 ```javascript
-await testdriver.type(text, delay)
+await testdriver.type(text, options)
 ```
 
 ## Parameters
@@ -21,8 +21,18 @@ await testdriver.type(text, delay)
   Text to type (can be a string or number)
 </ParamField>
 
-<ParamField path="delay" type="number" default="250">
-  Delay between keystrokes in milliseconds
+<ParamField path="options" type="object | number">
+  Typing options (or legacy delay number)
+  
+  <Expandable title="properties">
+    <ParamField path="delay" type="number" default={250}>
+      Delay between keystrokes in milliseconds
+    </ParamField>
+    
+    <ParamField path="secret" type="boolean" default={false}>
+      If `true`, treats text as sensitive data (won't be logged or stored in debug info/dashcam)
+    </ParamField>
+  </Expandable>
 </ParamField>
 
 ## Returns
@@ -40,10 +50,44 @@ await testdriver.type('hello@example.com');
 // Type numbers
 await testdriver.type(12345);
 
-// Type with custom delay
+// Type with custom delay (legacy syntax)
 await testdriver.type('slow typing', 500); // 500ms between each character
+
+// Type with options object
+await testdriver.type('text', { delay: 500 });
+```
+
+### Password/Secret Handling
+
+```javascript
+// ✅ SECURE - Mark as secret to prevent logging
+const passwordField = await testdriver.find('password input');
+await passwordField.click();
+await testdriver.type('MySecureP@ssw0rd', { secret: true });
+// Password NOT logged in dashcam or debug output
+
+// ❌ INSECURE - Password will be logged
+await testdriver.type('MySecureP@ssw0rd');
+// Password appears in logs, dashcam replay, and debug info
+
+// Use secret for any sensitive data
+await testdriver.find('api key input').click();
+await testdriver.type('sk-1234567890abcdef', { secret: true });
+
+await testdriver.find('credit card input').click();
+await testdriver.type('4111111111111111', { secret: true });
 ```
 
+<Warning>
+  **Always use `secret: true` for passwords and sensitive data!**
+  
+  Without this option, typed text appears in:
+  - Dashcam video replays
+  - TestDriver logs
+  - Debug screenshots
+  - Error messages
+</Warning>
+
 ### Form Filling
 
 ```javascript
@@ -56,9 +100,9 @@ await testdriver.type('user@example.com');
 await testdriver.pressKeys(['tab']);
 await testdriver.type('John Doe');
 
-// Type password
+// Type password securely
 await testdriver.pressKeys(['tab']);
-await testdriver.type('MySecureP@ssw0rd');
+await testdriver.type('MySecureP@ssw0rd', { secret: true });
 ```
 
 ### Clearing and Replacing Text
@@ -135,7 +179,7 @@ await testdriver.type('new search query');
     await testdriver.type('testuser@example.com');
     
     await testdriver.pressKeys(['tab']);
-    await testdriver.type('MyP@ssword123');
+    await testdriver.type('MyP@ssword123', { secret: true });
     
     await testdriver.pressKeys(['enter']);
     ```