> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testdriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# assert()

> Make AI-powered assertions about screen state

## Overview

Make AI-powered assertions about the current screen state using natural language. The AI analyzes the screen and verifies that your assertion is true.

## Syntax

```javascript theme={null}
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 assertion passes, throws error if assertion fails

## Examples

### Basic Assertions

```javascript theme={null}
// 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:

  ```javascript theme={null}
  // ❌ 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**

  Verify state before and after actions:

  ```javascript theme={null}
  // 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:

  ```javascript theme={null}
  // 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:

```javascript theme={null}
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 theme={null}
    // 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 theme={null}
    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 theme={null}
    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 theme={null}
    // 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 theme={null}
    // 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

```javascript theme={null}
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()`](/v7/extract) - Extract information for detailed assertions
* [`find()`](/v7/find) - Locate elements to verify
* [`ai()`](/v7/ai) - Complex AI-driven tasks