@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/find.mdx

@@ -1,859 +1,263 @@
 ---
 title: "find()"
 sidebarTitle: "find"
-description: "Locate UI elements using natural language"
+description: "Locate an element on screen by describing it in plain language."
 icon: "magnifying-glass"
 ---
 
-## Overview
+Describe an element the way a person would, and `find()` locates it on screen. Then act on it:
 
-Find UI elements on the screen with natural language descriptions and AI. This returns an `Element` object. You can interact with the object.
+```javascript
+const signInButton = await testdriver.find('Sign in button below the password field');
+await signInButton.click();
+```
 
-## Syntax
+For writing good descriptions, see [Locate elements](/locating-elements).
 
-```javascript
-const element = await testdriver.find(description)
-const element = await testdriver.find(description, options)
+## Signature
+
+```typescript
+testdriver.find(description: string, options?: FindOptions): ChainableElementPromise
 ```
 
 ## Parameters
 
 <ParamField path="description" type="string" required>
-  Natural language description of the element to find
+  What the element looks like and where it is, such as `'Add to cart button under the TestDriver Hat'`.
 </ParamField>
 
-<ParamField path="options" type="object | number">
-  Optional configuration for finding and caching
-  
+<ParamField path="options" type="object">
   <Expandable title="properties">
-    <ParamField path="cacheKey" type="string">
-      A custom cache key to store the element location. Use this to keep the cache clean when you use dynamic variables in prompts. You can also use it to share the cache between tests.
-    </ParamField>
-    
-    <ParamField path="cacheThreshold" type="number" default={0.05}>
-      The similarity threshold (0-1) for a cache match. A lower value needs more similarity. Set it to -1 to disable the cache.
+    <ParamField path="timeout" type="number" default="10000">
+      How long to keep looking, in milliseconds. `find()` checks the screen every 5 seconds until it finds the element or the time runs out. `0` checks once.
     </ParamField>
-    
-    <ParamField path="timeout" type="number" default={10000}>
-      The maximum time in milliseconds to poll for the element. TestDriver tries again each 5 seconds until it finds the element or the timeout ends. The default is `10000` (10 seconds). Set it to `0` to disable the poll and try one time.
-    </ParamField>
-    
     <ParamField path="confidence" type="number">
-      The minimum confidence threshold (0-1). If the confidence score of the found element is less than this value, the find is a failure (`element.found()` returns `false`). Use this to make sure of good matches in critical test steps.
+      The lowest AI confidence to accept, from 0 to 1. A match below it counts as not found.
     </ParamField>
-    
-    <ParamField path="type" type="string">
-      Element type hint that wraps the description for better matching. Accepted values:
-      - `"text"` — Wraps the prompt as `The text "..."`
-      - `"image"` — Wraps the prompt as `The image "..."`
-      - `"ui"` — Wraps the prompt as `The UI element "..."`
-      - `"any"` — No wrapping, uses the description as-is (default behavior)
+    <ParamField path="verify" type="boolean" default="false">
+      Double-check the result with a second AI call. If the check fails, TestDriver locates the element again with a hint and checks once more. If that also fails, the element is returned as not found. Off by default, because it's slower. Cache hits aren't re-checked. Defaults to the client's [`verify` option](/options#param-verify).
     </ParamField>
-    
-    <ParamField path="zoom" type="boolean" default={false}>
-      A two-phase zoom mode for more precision in full UIs that have many similar elements. It is disabled by default.
+    <ParamField path="zoom" type="boolean | number" default="false">
+      Locate in two passes for more precision. The AI finds the rough area, then locates the element again in a close-up crop of that area. `true` checks one area. A number from 1 to 4 checks up to that many candidate areas. More than one area is an Enterprise feature; on other plans it's treated as `1`.
     </ParamField>
-    
-    <ParamField path="verify" type="boolean" default={false}>
-      This enables AI verification of the found element. When `true`, a second AI call makes sure that the coordinates agree with the correct element. This catches incorrect positions. It is disabled by default for less latency. When you do not set it for each call, it uses the global `verify` option from the [SDK options](/options#ai-and-element-location).
+    <ParamField path="type" type="string" default="any">
+      What kind of element you mean. TestDriver wraps your description before sending it to the AI:
+
+      - `'text'`: `The text "<description>"`
+      - `'image'`: `Image of "<description>"`
+      - `'ui'`: `The UI element "<description>"`
+      - `'any'`: the description as written
     </ParamField>
-    
-    <ParamField path="ai" type="object">
-      AI sampling configuration for this find call (overrides global `ai` config from constructor).
-      
+    <ParamField path="cacheKey" type="string">
+      Store and look up the cached position under this key instead of the client's. See [Caching](/caching).
+    </ParamField>
+    <ParamField path="cache" type="object">
+      Cache settings for this call.
       <Expandable title="properties">
-        <ParamField path="temperature" type="number">
-          Controls randomness. `0` = deterministic. Default: `0` for find verification.
-        </ParamField>
-        
-        <ParamField path="top" type="object">
-          Sampling parameters
-          
+        <ParamField path="thresholds" type="object">
           <Expandable title="properties">
-            <ParamField path="p" type="number">
-              Top-P (nucleus sampling). Range: 0-1.
+            <ParamField path="screen" type="number" default="0.05">
+              How much the screen may differ from the cached run (0 to 1) and still reuse the position. `-1` turns the cache off for this call.
             </ParamField>
-            
-            <ParamField path="k" type="number">
-              Top-K sampling. `1` = most deterministic.
+            <ParamField path="element" type="number" default="0.8">
+              How closely the element must match its cached image (0 to 1).
             </ParamField>
           </Expandable>
         </ParamField>
       </Expandable>
     </ParamField>
+    <ParamField path="ai" type="AIConfig">
+      Accepted, but `find()` doesn't apply it yet. Set the client's [`ai` option](/options#param-ai) instead.
+    </ParamField>
+    <ParamField path="cacheThreshold" type="number">
+      Legacy. Same as `cache.thresholds.screen`.
+    </ParamField>
   </Expandable>
 </ParamField>
 
 ## Returns
 
-`Promise<Element>` - The Element instance that TestDriver found automatically.
-
-## Examples
-
-### Basic Element Finding
+`ChainableElementPromise`. It resolves to an `Element`, and you can also call an action on it directly (see [Chain an action](#chain-an-action)).
 
-```javascript
-// Find by role
-const button = await testdriver.find('submit button');
-const input = await testdriver.find('email input field');
+The element has these methods and properties:
 
-// Find by text content
-const link = await testdriver.find('Contact Us link');
-const heading = await testdriver.find('Welcome heading');
+| Member | What it gives you |
+| --- | --- |
+| `found()` | `true` if the element was located |
+| `click(action?)` | Clicks the element. See [click()](/click). |
+| `hover()`, `doubleClick()`, `rightClick()` | The other mouse actions |
+| `mouseDown()`, `mouseUp()` | Press and release, for dragging. See [mouseDown()](/mouse-down). |
+| `x`, `y` | The point TestDriver clicks, in pixels |
+| `coordinates` | The same point as `{ x, y }`, or `null` if not found |
+| `confidence` | The AI's confidence, from 0 to 1 |
+| `find(description?, options?)` | Locates the element again, optionally with a new description |
+| `toJSON()` | Debug details, such as `reasoning` and whether the result came from the `cache` |
 
-// Find by visual appearance
-const icon = await testdriver.find('red warning icon');
-const image = await testdriver.find('company logo image');
-```
+## Chain an action
 
-### Finding with Context
+You can call an action on `find()` without awaiting it first:
 
 ```javascript
-// Provide location context
-const field = await testdriver.find('username input in the login form');
-const button = await testdriver.find('delete button in the top right corner');
-
-// Describe nearby elements
-const input = await testdriver.find('input field below the email label');
-const checkbox = await testdriver.find('checkbox next to "Remember me"');
-
-// Describe visual position
-const menu = await testdriver.find('hamburger menu icon in the top left');
+await testdriver.find('Sign in button').click();
 ```
 
-### Interacting with Found Elements
-
-```javascript
-// Find and click
-const submitBtn = await testdriver.find('submit button');
-await submitBtn.click();
-
-// Find and verify
-const message = await testdriver.find('success message');
-if (message.found()) {
-  console.log('Success message appeared');
-}
-
-// Find and extract info
-const price = await testdriver.find('product price');
-console.log('Price location:', price.coordinates);
-console.log('Price text:', price.text);
-```
-
-## Element Object
-
-The `Element` object that TestDriver returns gives these:
-
-### Methods
-
-- `found()` - Make a check if TestDriver found the element
-- `click(action)` - Click the element
-- `hover()` - Put the cursor on the element
-- `doubleClick()` - Double-click the element
-- `rightClick()` - Right-click the element
-- `find(newDescription)` - Find the element again with an optional new description
-
-### Properties
+These chain the same way: `hover()`, `doubleClick()`, `rightClick()`, `mouseDown()`, `mouseUp()`, and `found()`.
 
-- `coordinates` - Element position `{x, y, centerX, centerY}`
-- `x`, `y` - Top-left coordinates
-- `centerX`, `centerY` - Center coordinates
-- `text` - Text content (if available)
-- `screenshot` - Base64 screenshot (if available)
-- `confidence` - AI confidence score
-- `width`, `height` - Element dimensions
-- `boundingBox` - Complete bounding box
+## When the element isn't found
 
-See [Elements Reference](/elements) for complete details.
+`find()` doesn't throw when nothing matches. It returns an element whose `found()` is `false` and whose `coordinates` is `null`.
 
-### JSON Serialization
-
-You can serialize elements safely with `JSON.stringify()` for logs and for debug. TestDriver removes circular references automatically:
+Acting on that element throws an `ElementNotFoundError`, so a missing element still fails the test at the action:
 
 ```javascript
-const element = await testdriver.find('login button');
-
-// Safe to stringify - no circular reference errors
-console.log(JSON.stringify(element, null, 2));
-
-// Output includes useful debugging info:
-// {
-//   "description": "login button",
-//   "coordinates": { "x": 100, "y": 200, "centerX": 150, "centerY": 225 },
-//   "found": true,
-//   "threshold": 0.01,
-//   "x": 100,
-//   "y": 200,
-//   "cache": {
-//     "hit": true,
-//     "strategy": "pixel-diff",
-//     "createdAt": "2025-12-09T10:30:00Z",
-//     "diffPercent": 0.0023,
-//     "imageUrl": "https://..."
-//   },
-//   "similarity": 0.98,
-//   "confidence": 0.95,
-//   "selector": "button#login",
-//   "aiResponse": "Found the blue login button..."
-// }
+// Throws ElementNotFoundError if the button wasn't found
+await testdriver.find('Sign in button').click();
 ```
 
-Use this for these:
-- To debug problems with element detection
-- To log the details of the test
-- To share element data between processes
-- To examine the cache performance
-
-## Best Practices
-
-<Check>
-  **Be specific in descriptions**
-  
-  More specific descriptions make the accuracy better:
-  
-  ```javascript
-  // ✅ Good
-  await testdriver.find('blue submit button below the email field');
-  
-  // ❌ Too vague
-  await testdriver.find('button');
-  ```
-</Check>
-
-<Check>
-  **Always check if found**
-  
-  Make sure that TestDriver found the elements before you interact with them:
-  
-  ```javascript
-  const element = await testdriver.find('login button');
-  if (!element.found()) {
-    throw new Error('Login button not found');
-  }
-  await element.click();
-  ```
-</Check>
-
-<Check>
-  **Include visual or positional context**
-  
-  ```javascript
-  // Include color
-  await testdriver.find('red error icon');
-  
-  // Include position
-  await testdriver.find('search button in the top navigation bar');
-  
-  // Include nearby text
-  await testdriver.find('checkbox next to "I agree to terms"');
-  ```
-</Check>
-
-## Confidence Threshold
-
-Set a minimum confidence score for element matches. If the confidence is less than the threshold, `find()` makes the result "not found":
+To handle an element that may not be there, check `found()`:
 
 ```javascript
-// Require at least 90% confidence
-const element = await testdriver.find('submit button', { confidence: 0.9 });
-
-if (!element.found()) {
-  // AI found something but wasn't confident enough
-  throw new Error('Could not confidently locate submit button');
+const banner = await testdriver.find('cookie consent banner', { timeout: 0 });
+if (banner.found()) {
+  await testdriver.find('Accept all cookies button').click();
 }
-
-await element.click();
 ```
 
-Use this for these:
-- Critical test steps. An incorrect click can cause more failures.
-- To tell the difference between similar elements (for example, many buttons)
-- To fail quickly when the UI changed
+`ElementNotFoundError` is exported from `testdriverai`:
 
 ```javascript
-// Combine with timeout for robust polling with confidence gate
-const element = await testdriver.find('success notification', {
-  confidence: 0.85,
-  timeout: 15000,
-});
+import { ElementNotFoundError } from 'testdriverai';
 ```
 
-<Tip>
-  The `confidence` value is a float between 0 and 1 (for example, `0.9` = 90%). The AI returns its confidence with each find result. You can also read this from `element.confidence` after a good find.
-</Tip>
-## Element Type
-
-Use the `type` option to show which kind of element you look for. This puts your description into a more specific prompt for the AI. It makes the match accuracy better, primarily when a description is short or not clear.
-
-```javascript
-// Find text on the page
-const label = await testdriver.find('Sign In', { type: 'text' });
-// AI prompt becomes: The text "Sign In"
-
-// Find an image
-const logo = await testdriver.find('company logo', { type: 'image' });
-// AI prompt becomes: The image "company logo"
-
-// Find a UI element (button, input, checkbox, etc.)
-const btn = await testdriver.find('Submit', { type: 'ui' });
-// AI prompt becomes: The UI element "Submit"
-
-// No wrapping — same as omitting the option
-const el = await testdriver.find('the blue submit button', { type: 'any' });
-```
-
-| Type | Prompt sent to AI |
-|------|----|
-| `"text"` | `The text "..."` |
-| `"image"` | `The image "..."` |
-| `"ui"` | `The UI element "..."` |
-| `"any"` | Original description (no wrapping) |
-
-<Tip>
-  Use this primarily for short descriptions such as `"Submit"` or `"Login"`. In these, the AI can be not sure to look for a button, a link, or visible text. When you give the `type`, the description becomes clear.
-</Tip>
-## Polling for Dynamic Elements
-
-By default, `find()` polls for a maximum of 10 seconds (it tries again each 5 seconds) until it finds the element. You can change this with the `timeout` option:
-
-```javascript
-// Uses default 10s timeout - polls every 5 seconds
-const element = await testdriver.find('login button');
-await element.click();
-
-// Custom timeout - wait up to 30 seconds
-const element = await testdriver.find('login button', { timeout: 30000 });
-await element.click();
-
-// Disable polling - single attempt only
-const element = await testdriver.find('login button', { timeout: 0 });
-```
-
-The `timeout` option:
-- Has a default of `10000` (10 seconds)
-- Tries to find the element again each 5 seconds
-- Stops when it finds the element or the timeout ends
-- Logs the progress during the poll
-- Returns the element (make a check with `element.found()` if it does not throw an error on a failure)
-- Set it to `0` to disable the poll and try one time
-
-## Zoom Mode
-
-Zoom mode is **disabled by default**. It uses a two-phase method for more precision when it finds elements, primarily in full UIs that have many similar elements.
-
-To enable zoom for a specific find call, give `zoom: true`:
-
-```javascript
-// Enable zoom for better precision in crowded UIs
-const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar', { zoom: true });
-await extensionsBtn.click();
-
-// Without zoom (default)
-const largeButton = await testdriver.find('big hero button');
-```
-
-### How Zoom Mode Works
-
-1. **Phase 1**: The AI finds the approximate location of the element.
-2. **Phase 2**: TestDriver makes a 30% crop of the screen around that location.
-3. **Phase 3**: The AI does the precise location on the cropped image.
-4. **Result**: TestDriver changes the coordinates back to the absolute screen position.
-
-This two-phase method gives the AI a higher-resolution view of the target area. It makes the accuracy better when many similar elements are near together.
-
-<Tip>
-  Enable zoom with `zoom: true` when:
-  - You target small elements in full UIs that have many similar elements
-  - You need more precision for UI elements that are near together
-</Tip>
-
-## Verify Mode
+## Examples
 
-Verify mode is **disabled by default**. When it is enabled, a second AI call makes sure that the coordinates from `find()` agree with the correct element. This catches incorrect positions.
+### Wait for something slow to appear
 
 ```javascript
-// Enable verification for critical interactions
-const deleteBtn = await testdriver.find('delete account button', { verify: true });
-await deleteBtn.click();
+const confirmation = await testdriver.find('Order confirmation heading', { timeout: 30000 });
+expect(confirmation.found()).toBe(true);
 ```
 
-### How Verify Mode Works
+### Make the match stricter
 
-1. **Phase 1**: The AI finds the element and returns coordinates.
-2. **Phase 2**: A second AI call looks at the screenshot at those coordinates. It makes sure that the element agrees with the description.
-3. **Result**: If the verification fails, TestDriver tries the find again or marks it "not found".
-
-### Combining Zoom and Verify
-
-For the maximum accuracy, enable `zoom` and `verify` together. Use this for critical interactions. A click on the wrong element can cause more failures:
+Use `confidence` and `verify` where clicking the wrong element is costly:
 
 ```javascript
-// Maximum accuracy: zoom for precision + verify to catch hallucinations
-const element = await testdriver.find('small cancel icon next to the subscription', {
-  zoom: true,
+await testdriver.find('Delete account button', {
+  confidence: 0.9,
   verify: true,
-});
-await element.click();
+}).click();
 ```
 
-## Cache Options
-
-When a test completes correctly, TestDriver caches the result of each `find()`. On later runs, TestDriver uses the cached match again. It does not make a new AI call. This finds the same element much more quickly. The cache is in your [dashboard](https://console.testdriver.ai/cache). TestDriver shares it between runs. Read the [Cache](/cache) page to see how the match, the thresholds, and the invalidation work.
-
-Control the cache to make the performance better, primarily when you use dynamic variables in prompts.
-
-### Custom Cache Key
-
-Use `cacheKey` to keep the cache clean when prompts have variables:
+### Find a small target in a crowded screen
 
 ```javascript
-// ❌ Without cacheKey - creates new cache entry for each email value
-const email = 'user@example.com';
-await testdriver.find(`input for ${email}`); // Cache miss every time
-
-// ✅ With cacheKey - reuses cache regardless of variable
-const email = 'user@example.com';
-await testdriver.find(`input for ${email}`, {
-  cacheKey: 'email-input'
-});
-
-// Also useful for dynamic IDs, names, or other changing data
-const orderId = generateOrderId();
-await testdriver.find(`order ${orderId} status`, {
-  cacheKey: 'order-status'  // Same cache for all orders
-});
+await testdriver.find('extensions puzzle icon in the Chrome toolbar', { zoom: true }).click();
 ```
 
-### Cache Threshold
-
-Control how similar a cached result must be before TestDriver uses it again:
+### Disambiguate a short description
 
 ```javascript
-// Default: 95% similarity required
-await testdriver.find('submit button');
-
-// Strict threshold - 99% similarity required
-await testdriver.find('submit button', {
-  cacheThreshold: 0.01
-});
-
-// Disable cache entirely for this call
-await testdriver.find('submit button', {
-  cacheThreshold: -1
-});
-
-// Combine cacheKey with threshold
-await testdriver.find('submit button', {
-  cacheKey: 'submit-btn',
-  cacheThreshold: 0.01
-});
+// Matches the visible word "Total", not a button or icon
+const totalLabel = await testdriver.find('Total', { type: 'text' });
 ```
 
-<Tip>
-  By default, TestDriver makes a cache key automatically from the SHA-256 hash of your test file. When you change your test file, the hash changes automatically. This makes the old cache entries not valid.
-</Tip>
+### Keep the cache when the description changes
 
-### Manual Polling (Alternative)
-
-If you need custom poll logic:
+A description with a changing value never matches its cached entry. Give it a fixed `cacheKey`:
 
 ```javascript
-async function waitForElement(testdriver, description, timeout = 30000) {
-  const startTime = Date.now();
-  
-  while (Date.now() - startTime < timeout) {
-    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 after ${timeout}ms`);
-}
-
-// Usage
-const button = await waitForElement(testdriver, 'submit button', 10000);
-await button.click();
+const orderId = '1042';
+await testdriver.find(`Order #${orderId} row in the orders table`, {
+  cacheKey: 'order-row',
+}).click();
 ```
 
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Form Fields">
-    ```javascript
-    const emailField = await testdriver.find('email input field');
-    await emailField.click();
-    await testdriver.type('user@example.com');
-    
-    const passwordField = await testdriver.find('password input');
-    await passwordField.click();
-    await testdriver.type('MyP@ssw0rd');
-    ```
-  </Accordion>
-  
-  <Accordion title="Buttons and Links">
-    ```javascript
-    const submitBtn = await testdriver.find('submit button');
-    await submitBtn.click();
-    
-    const cancelLink = await testdriver.find('cancel link');
-    await cancelLink.click();
-    
-    const menuIcon = await testdriver.find('hamburger menu icon');
-    await menuIcon.click();
-    ```
-  </Accordion>
-  
-  <Accordion title="Dynamic Content">
-    ```javascript
-    // Wait for loading to complete
-    let content;
-    for (let i = 0; i < 30; i++) {
-      content = await testdriver.find('results table');
-      if (content.found()) break;
-      await new Promise(r => setTimeout(r, 1000));
-    }
-    
-    // Interact with loaded content
-    const firstRow = await testdriver.find('first row in the results table');
-    await firstRow.click();
-    ```
-  </Accordion>
-  
-  <Accordion title="Complex UI Elements">
-    ```javascript
-    // Modals and dialogs
-    const modal = await testdriver.find('confirmation dialog');
-    if (modal.found()) {
-      const confirmBtn = await testdriver.find('confirm button in the dialog');
-      await confirmBtn.click();
-    }
-    
-    // Dropdown menus
-    const dropdown = await testdriver.find('country dropdown');
-    await dropdown.click();
-    
-    const option = await testdriver.find('United States option');
-    await option.click();
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Complete Example
+### Tighten the cache for one call
 
 ```javascript
-import { beforeAll, afterAll, describe, it, expect } from 'vitest';
-import TestDriver from 'testdriverai';
-
-describe('Element Finding', () => {
-  let testdriver;
-
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
-
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
-
-  it('should find and interact with elements', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Find login form elements
-    const usernameField = await testdriver.find('username input field');
-    expect(usernameField.found()).toBe(true);
-    
-    await usernameField.click();
-    await testdriver.type('testuser');
-    
-    // Find with context
-    const passwordField = await testdriver.find('password input below username');
-    await passwordField.click();
-    await testdriver.type('password123');
-    
-    // Find button
-    const submitBtn = await testdriver.find('green submit button');
-    expect(submitBtn.found()).toBe(true);
-    
-    console.log('Button location:', submitBtn.centerX, submitBtn.centerY);
-    
-    await submitBtn.click();
-    
-    // Wait for success message
-    let successMsg;
-    for (let i = 0; i < 10; i++) {
-      successMsg = await testdriver.find('success notification');
-      if (successMsg.found()) break;
-      await new Promise(r => setTimeout(r, 1000));
-    }
-    
-    expect(successMsg.found()).toBe(true);
-  });
+await testdriver.find('Submit button', {
+  cache: { thresholds: { screen: 0.01, element: 0.9 } },
 });
 ```
 
-## Related Methods
-
-- [`click()`](/click) - Click on found elements
-- [`hover()`](/hover) - Hover over elements
-- [`assert()`](/assert) - Verify element states
-- [Elements Reference](/elements) - Complete Element API
-
----
-
 ## findAll()
 
-Locate **all elements** matching a description, rather than just one.
-
-### Syntax
+Locates every element that matches a description and returns them as an array.
 
-```javascript
-const elements = await testdriver.findAll(description, options)
+```typescript
+testdriver.findAll(description: string, options?: FindAllOptions): Promise<Element[]>
 ```
 
-### Parameters
-
 <ParamField path="description" type="string" required>
-  Natural language description of elements to find
+  What the elements look like, such as `'coffee cup icon'`.
 </ParamField>
 
-<ParamField path="options" type="object | number">
-  Optional cache options (same as `find()`)
-  
+<ParamField path="options" type="object">
   <Expandable title="properties">
     <ParamField path="cacheKey" type="string">
-      Cache key for storing element location
+      Store and look up the cached positions under this key instead of the client's.
     </ParamField>
-    
-    <ParamField path="cacheThreshold" type="number" default={-1}>
-      Similarity threshold (0-1) for cache matching. Set to -1 to disable cache.
+    <ParamField path="cache" type="object">
+      `{ thresholds: { screen } }`. How much the screen may differ from the cached run (0 to 1) and still reuse the positions. Defaults to `0.05`. `-1` turns the cache off for this call.
+    </ParamField>
+    <ParamField path="cacheThreshold" type="number">
+      Legacy. Same as `cache.thresholds.screen`.
     </ParamField>
   </Expandable>
 </ParamField>
 
-### Returns
-
-`Promise<Element[]>` - Array of Element instances
+`findAll()` differs from `find()`:
 
-### Examples
-
-#### Basic Usage
+- It checks the screen once. There's no `timeout`.
+- It returns `[]` when nothing matches. It doesn't throw.
+- It doesn't support `confidence`, `verify`, `zoom`, or `type`.
+- You can't chain an action onto it. Pick an element from the array first.
 
 ```javascript
-// Find all matching elements
-const buttons = await testdriver.findAll('button');
-console.log(`Found ${buttons.length} buttons`);
+const coffeeIcons = await testdriver.findAll('coffee cup icon');
+expect(coffeeIcons.length).toBeGreaterThan(0);
 
-// 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})`);
+for (const icon of coffeeIcons) {
+  await icon.click();
 }
 ```
 
-#### Finding Multiple Items
+See the [find all example](/examples/findall-coffee-icons) for a complete test.
 
-```javascript
-// Find all list items
-const items = await testdriver.findAll('list item');
+## Complete example
 
-// Find specific item by index
-const thirdItem = items[2];
-await thirdItem.click();
+```javascript tests/login.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-// 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)
-```
+describe('Login', () => {
+  it('signs in with valid credentials', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-#### Empty Results
+    // The sandbox login page shows its test password on screen
+    const password = await testdriver.extract('the password');
 
-```javascript
-// Returns empty array if nothing found (doesn't throw error)
-const errors = await testdriver.findAll('error message');
+    await testdriver.find('Username input field').click();
+    await testdriver.type('standard_user');
 
-if (errors.length === 0) {
-  console.log('No errors found - test passed!');
-} else {
-  console.log(`Found ${errors.length} errors`);
-}
-```
+    await testdriver.find('Password input field').click();
+    await testdriver.type(password, { secret: true });
 
-### 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
+    await testdriver.find('Sign in button below the password field').click();
 
-```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'
+    const addToCart = await testdriver.find('Add to Cart button under the TestDriver Hat', {
+      timeout: 30000,
+    });
+    expect(addToCart.found()).toBe(true);
   });
-  
-  // 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>
+## Related
+
+- [Locate elements](/locating-elements): write descriptions that match reliably
+- [click()](/click) and [hover()](/hover): act on what you found
+- [Caching](/caching): how element positions are reused
+- [Element not found example](/examples/element-not-found): handle a missing element