/testdriver-making-assertions

name: testdriver:making-assertions
description: Locate elements and verify app state with AI-powered assertions

<!-- Generated from making-assertions.mdx. DO NOT EDIT. -->

After a test runs, make sure that the app did the correct thing. Validation has two parts: to find the elements that you want to check, and to make assertions about the state of your app. TestDriver uses the AI as a judge. It returns a boolean and the reason. This shows if your app is in the correct state.

Locating Elements

Locating Single Elements

Use natural language to describe elements. A description must be specific enough to find the element. But it must not be so specific that it breaks with small 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 caches the found elements for better performance on later calls. Read more about [element caching here](/caching).</Info>

Debugging Found Elements

After TestDriver finds an element, you can look at its properties for debug:

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

Making Assertions

Use AI-powered assertions to verify application state. TestDriver acts as a judge: it evaluates your natural-language statement against the current state of the app and returns a boolean plus reasoning explaining the verdict.

// Verify visibility
await testdriver.assert('login page is displayed');
await testdriver.assert('submit button is visible');
await testdriver.assert('loading spinner is not visible');

// Verify content
await testdriver.assert('page title is "Welcome"');
await testdriver.assert('success message says "Account created"');
await testdriver.assert('error message contains "Invalid email"');

// Verify state
await testdriver.assert('checkbox is checked');
await testdriver.assert('dropdown shows "United States"');
await testdriver.assert('button is disabled');

// Verify visual appearance
await testdriver.assert('submit button is blue');
await testdriver.assert('form has red border');

<Info>Assertions are not cached and always re-evaluated to ensure accuracy.</Info>

Next

<Card title="Adapt" icon="arrows-rotate" href="/performing-actions"> Drive your app forward by performing actions on the elements you've located and validated. </Card>