testdriver:assert

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

  <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>

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

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

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

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

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

// 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');
```

// Verify navigation
await testdriver.assert('user dashboard is displayed');
await testdriver.assert('welcome message shows user name');
await testdriver.assert('logout button is visible');
```

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

await testdriver.assert('button background is darker');

// Verify button is enabled
await testdriver.assert('submit button is enabled');
```

// 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');
```

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