/testdriver-locating-elements

name: testdriver:locating-elements
description: Find UI elements using natural language descriptions

<!-- Generated from locating-elements.mdx. DO NOT EDIT. -->

Locating Single Elements

Use natural language to describe elements. Descriptions should be specific enough to locate the element, but not too-specific that they break with minor UI changes. For example:

await testdriver.find('email input field');
await testdriver.find('first product card in the grid');
await testdriver.find('dropdown menu labeled "Country"');

<Info>TestDriver will cache found elements for improved performance on subsequent calls. Learn more about [element caching here](/v7/caching).</Info>

Debugging Found Elements

After finding an element, you can inspect its properties for debugging:

const button = await testdriver.find('submit button');
console.log(button);

This outputs all element properties:

{
  description: 'submit button',
  found: true,
  x: 150,
  y: 300,
  coordinates: { x: 150, y: 300, centerX: 200, centerY: 320 },
  threshold: 0.8,
  confidence: 0.95,
  similarity: 0.92,
  selector: 'button[type="submit"]',
  cache: {
    hit: true,
    strategy: 'pixel-diff',
    createdAt: '2025-01-15T10:30:00Z',
    diffPercent: 0.02,
    imageUrl: 'https://...'
  }
}

Working with Multiple Elements

Find and interact with multiple elements:

// Find all matching elements
const products = await testdriver.findAll('product card');
console.log(`Found ${products.length} products`);

// Interact with each
for (const product of products) {
  const title = await product.find('title text');
  console.log('Product:', title.text);

  await product.find('add to cart button').click();
}

// Or find specific element
const firstProduct = products[0];
await firstProduct.click();