/testdriver-assert

name: testdriver:assert
description: Make AI-powered assertions about screen state

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

Overview

Make assertions about the screen state with natural language and AI. The AI examines the screen. It makes sure that your assertion is true.

Syntax

await testdriver.assert(assertion)
await testdriver.assert(assertion, options)

Parameters

<ParamField path="assertion" type="string" required> Natural language description of what should be true </ParamField>

<ParamField path="options" type="object"> Optional configuration

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

<Expandable title="properties"> <ParamField path="temperature" type="number"> Controls randomness. `0` = deterministic, higher = more creative. Default: model default. </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<boolean>` - `true` if the assertion passes. It throws an error if the assertion fails.

Examples

Basic Assertions

// Verify page elements
await testdriver.assert('the login page is displayed');
await testdriver.assert('submit button is visible');
await testdriver.assert('error message is shown');

// Verify text content
await testdriver.assert('the page title is "Welcome"');
await testdriver.assert('username field contains "john.doe"');
await testdriver.assert('success message says "Account created"');

// Verify states
await testdriver.assert('the form is empty');
await testdriver.assert('the checkbox is checked');
await testdriver.assert('the dropdown shows "United States"');

// Verify visual appearance
await testdriver.assert('the button is blue');
await testdriver.assert('the loading spinner is displayed');
await testdriver.assert('the modal dialog is open');

Best Practices

<Check> **Be specific in assertions**

More specific assertions are more reliable:

  // ❌ Too vague
  await testdriver.assert('button is visible');
  
  // ✅ Specific
  await testdriver.assert('blue submit button is visible below the form');

</Check>

<Check> **Assert state changes**

Make sure of the state before and after actions:

  // Before
  await testdriver.assert('cart is empty');
  
  // Action
  const addBtn = await testdriver.find('add to cart');
  await addBtn.click();
  
  // After
  await testdriver.assert('cart contains 1 item');

</Check>

<Check> **Use with test framework assertions**

Combine AI assertions with traditional test assertions:

  // AI assertion
  const result = await testdriver.assert('success message is displayed');
  
  // Framework assertion
  expect(result).toBeTruthy();
  
  // Extract for detailed comparison
  const message = await testdriver.extract('the success message text');
  expect(message).toContain('successfully');

</Check>

Polling Assertions

For conditions that may take time to become true:

async function waitForAssertion(testdriver, assertion, timeout = 30000) {
  const startTime = Date.now();
  
  while (Date.now() - startTime < timeout) {
    try {
      await testdriver.assert(assertion);
      return true; // Assertion passed
    } catch (error) {
      // Assertion failed, wait and retry
      await new Promise(r => setTimeout(r, 1000));
    }
  }
  
  throw new Error(`Assertion timeout: "${assertion}"`);
}

// Usage
await waitForAssertion(testdriver, 'page has finished loading', 30000);
await waitForAssertion(testdriver, 'results are displayed', 10000);

Use Cases

<AccordionGroup> <Accordion title="Form Validation">

    // Try to submit empty form
    const submitBtn = await testdriver.find('submit button');
    await submitBtn.click();
    
    // Verify validation errors
    await testdriver.assert('email field shows "required" error');
    await testdriver.assert('password field shows "required" error');
    
    // Verify form not submitted
    await testdriver.assert('still on the form page');

</Accordion>

<Accordion title="Page Navigation">

    const loginBtn = await testdriver.find('login button');
    await loginBtn.click();
    
    // Verify navigation
    await testdriver.assert('user dashboard is displayed');
    await testdriver.assert('welcome message shows user name');
    await testdriver.assert('logout button is visible');

</Accordion>

<Accordion title="Dynamic Content">

    const loadBtn = await testdriver.find('load more button');
    await loadBtn.click();
    
    // Poll for content using helper
    await waitForAssertion(testdriver, 'more than 10 items are shown', 10000);
    await testdriver.assert('load more button is still visible');

</Accordion>

<Accordion title="Visual States">

    // Verify hover effect
    const button = await testdriver.find('primary button');
    await button.hover();
    
    await testdriver.assert('button background is darker');
    
    // Verify button is enabled
    await testdriver.assert('submit button is enabled');

</Accordion>

<Accordion title="Multi-Step Workflows">

    // Step 1
    await testdriver.assert('step 1 is active');
    const nextBtn = await testdriver.find('next button')