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
string
required
Natural language description of what should be true
object
Optional configuration
Show properties
Show properties
object
AI sampling configuration for this assert call (overrides global
ai config from constructor).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
Be specific in assertionsMore 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 changesMake 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 assertionsCombine 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
Form Validation
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');
Page Navigation
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');
Dynamic Content
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');
Visual States
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');
Multi-Step Workflows
Multi-Step Workflows
// 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);
});
});