/testdriver-find

name: testdriver:find
description: Locate UI elements using natural language

<!-- Generated from find.mdx. DO NOT EDIT. -->

Overview

Find UI elements on the screen with natural language descriptions and AI. This returns an `Element` object. You can interact with the object.

Syntax

const element = await testdriver.find(description)
const element = await testdriver.find(description, options)

Parameters

<ParamField path="description" type="string" required> Natural language description of the element to find </ParamField>

<ParamField path="options" type="object | number"> Optional configuration for finding and caching

<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>

<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. </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>

<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>

<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>

<ParamField path="ai" type="object"> AI sampling configuration for this find call (overrides global `ai` config from constructor).

<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

<Expandable title="properties"> <ParamField path="p" type="number"> Top-P (nucleus sampling). Range: 0-1. </ParamField>

<ParamField path="k" type="number"> Top-K sampling. `1` = most deterministic. </ParamField> </Expandable> </ParamField> </Expandable> </ParamField> </Expandable> </ParamField>

Returns

`Promise<Element>` - The Element instance that TestDriver found automatically.

Examples

Basic Element Finding

// Find by role
const button = await testdriver.find('submit button');
const input = await testdriver.find('email input field');

// Find by text content
const link = await testdriver.find('Contact Us link');
const heading = await testdriver.find('Welcome heading');

// Find by visual appearance
const icon = await testdriver.find('red warning icon');
const image = await testdriver.find('company logo image');

Finding with Context

// 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');

Interacting with Found Elements

// 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

• `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 di