testdriver:locating-elements

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

TestDriver will cache found elements for improved performance on subsequent calls. Learn more about element caching here.

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();