testdriver:assert Skill

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

Natural language description of what should be true

Optional configuration

AI sampling configuration for this assert call (overrides global ai config from constructor).

Controls randomness. 0 = deterministic, higher = more creative. Default: model default.

Sampling parameters

Top-P (nucleus sampling). Range: 0-1.

Top-K sampling. 1 = most deterministic.

Returns

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

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

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

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

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

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

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

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

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

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

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