testdriver:assert

<!-- 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"> ```javascript // 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"> ```javascript 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"> ```javascript 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"> ```javascript // 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"> ```javascript // Step 1 await testdriver.assert('step 1 is active'); const nextBtn = await testdriver.find('next button'); await nextBtn.click();

// Step 2
await testdriver.assert('step 2 is active');
await testdriver.assert('step 1 is completed');
await nextBtn.click();

// Step 3
await testdriver.assert('step 3 is active');
await testdriver.assert('step 2 is completed');
```

</Accordion> </AccordionGroup>

Complete Example

import { beforeAll, afterAll, describe, it, expect } from 'vitest';
import TestDriver from 'testdriverai';

describe('Assertions', () => {
  let testdriver;

  beforeAll(async () => {
    client = new TestDriver(process.env.TD_API_KEY);
    await testdriver.auth();
    await testdriver.connect();
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('should validate login flow', async () => {
    await testdriver.focusApplication('Google Chrome');
    
    // Verify initial state
    await testdriver.assert('the login page is displayed');
    await testdriver.assert('username field is empty');
    await testdriver.assert('password field is empty');
    
    // Fill form
    const usernameField = await testdriver.find('username input');
    await usernameField.click();
    await testdriver.type('testuser');
    
    await testdriver.pressKeys(['tab']);
    await testdriver.type('password123');
    
    // Verify fields filled
    await testdriver.assert('username field contains "testuser"');
    await testdriver.assert('password field is not empty');
    
    // Submit
    await testdriver.pressKeys(['enter']);
    
    // Poll for success
    await waitForAssertion(testdriver, 'user dashboard is displayed', 10000);
    
    // Verify logged in state
    await testdriver.assert('welcome message is shown');
    await testdriver.assert('logout button is visible');
    
    // Verify login page is gone
    await testdriver.assert('login form is displayed', false, true);
  });

  it('should show validation errors', async () => {
    // Try empty submission
    const submitBtn = await testdriver.find('submit button');
    await submitBtn.click();
    
    // Verify multiple errors
    const errors = [
      'email field shows error',
      'name field shows error',
      'password field shows error'
    ];
    
    for (const error of errors) {
      const result = await testdriver.assert(error);
      expect(result).toBeTruthy();
    }
    
    // Verify not submitted
    await testdriver.assert('confirmation page is shown', false, true);
  });
});

Related Methods

• extract() - Extract information for detailed assertions
• find() - Locate elements to verify