or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdconfiguration.mddevice-management.mdelement-interaction.mdelement-selection.mdindex.mdsynchronization.mdweb-view-testing.md
tile.json

assertions.mddocs/

Assertions

Comprehensive assertion system for validating element states, properties, and behaviors with detailed error reporting and support for native, web, and system elements.

Capabilities

Basic Element Assertions

Core assertions for element existence, visibility, and basic state validation.

/**
 * Create assertion context for native element
 * @param element - Native element to assert against
 * @returns Assertion interface for native elements
 */
function expect(element: NativeElement): Expect;

interface Expect {
  /**
   * Assert element is visible to user
   * @param pct - Minimum visibility percentage (defaults to 75%)
   */
  toBeVisible(pct?: number): Promise<void>;
  
  /**
   * Assert element exists in UI hierarchy
   */
  toExist(): Promise<void>;
  
  /**
   * Assert element is focused (has input focus)
   */
  toBeFocused(): Promise<void>;
  
  /**
   * Negate any assertion
   */
  not: Expect;
}

Usage Examples:

// Basic visibility assertion
await expect(element(by.id('welcome_message'))).toBeVisible();

// Custom visibility threshold
await expect(element(by.id('partial_element'))).toBeVisible(25);

// Element existence
await expect(element(by.id('hidden_element'))).toExist();

// Focus state
await expect(element(by.id('active_input'))).toBeFocused();

// Negated assertions
await expect(element(by.id('error_message'))).not.toBeVisible();
await expect(element(by.id('deleted_item'))).not.toExist();

Content Assertions

Validate element text content, labels, and identifiers.

/**
 * Assert element has specific text content
 * @param text - Expected text content
 */
function toHaveText(text: string): Promise<void>;

/**
 * Assert element has specific accessibility label
 * @param label - Expected accessibility label
 */
function toHaveLabel(label: string): Promise<void>;

/**
 * Assert element has specific test ID
 * @param id - Expected test identifier
 */
function toHaveId(id: string): Promise<void>;

Usage Examples:

// Text content validation
await expect(element(by.id('username_display'))).toHaveText('john.doe@example.com');
await expect(element(by.id('error_label'))).toHaveText('Invalid email format');

// Accessibility label validation
await expect(element(by.id('close_button'))).toHaveLabel('Close dialog');

// Test ID validation
await expect(element(by.text('Submit'))).toHaveId('submit_form_button');

Value Assertions

Validate input values, toggle states, and control positions.

/**
 * Assert element has specific value
 * @param value - Expected value (string, number, boolean, etc.)
 */
function toHaveValue(value: any): Promise<void>;

/**
 * Assert toggle element state (switches, checkboxes)
 * @param value - Expected toggle state (true for on/checked, false for off/unchecked)
 */
function toHaveToggleValue(value: boolean): Promise<void>;

/**
 * Assert slider position within tolerance
 * @param position - Expected position (0-1 scale)
 * @param tolerance - Optional tolerance for position matching
 */
function toHaveSliderPosition(position: number, tolerance?: number): Promise<void>;

Usage Examples:

// Input field values
await expect(element(by.id('email_input'))).toHaveValue('user@example.com');
await expect(element(by.id('age_input'))).toHaveValue('25');

// Toggle controls
await expect(element(by.id('enable_notifications'))).toHaveToggleValue(true);
await expect(element(by.id('dark_mode_toggle'))).toHaveToggleValue(false);

// Slider positions
await expect(element(by.id('volume_slider'))).toHaveSliderPosition(0.75);
await expect(element(by.id('brightness_slider'))).toHaveSliderPosition(0.5, 0.1);

Deprecated Assertions

Legacy assertion methods maintained for backward compatibility.

/**
 * @deprecated Use .not.toBeVisible() instead
 * Assert element is not visible
 */
function toBeNotVisible(): Promise<void>;

/**
 * @deprecated Use .not.toExist() instead
 * Assert element does not exist
 */
function toNotExist(): Promise<void>;

/**
 * @deprecated Use .not.toBeFocused() instead
 * Assert element is not focused
 */
function toBeNotFocused(): Promise<void>;

Web Element Assertions

Specialized assertions for web view elements with DOM-specific validation.

/**
 * Create assertion context for web element
 * @param webElement - Web element to assert against
 * @returns Assertion interface for web elements
 */
function expect(webElement: WebElement): WebExpect;

interface WebExpect {
  /**
   * Assert web element has specific text content
   * @param text - Expected text content
   */
  toHaveText(text: string): Promise<void>;
  
  /**
   * Assert web element exists in DOM tree
   */
  toExist(): Promise<void>;
  
  /**
   * Negate web element assertion
   */
  not: WebExpect;
}

Usage Examples:

// Web element text content
await expect(web().element(by.web.id('page_title'))).toHaveText('Welcome to Our App');

// Web element existence
await expect(web().element(by.web.className('error-message'))).toExist();
await expect(web().element(by.web.id('loading_spinner'))).not.toExist();

Secured Web Element Assertions (iOS Only)

Assertions for secured web elements with enhanced security context.

/**
 * Create assertion context for secured web element (iOS only)
 * @param securedWebElement - Secured web element to assert against
 * @returns Assertion interface for secured web elements
 */
function expect(securedWebElement: SecuredWebElement): SecuredWebExpect;

interface SecuredWebExpect {
  /**
   * Assert secured web element exists in DOM tree
   */
  toExist(): Promise<void>;
  
  /**
   * Negate secured web element assertion
   */
  not: SecuredWebExpect;
}

Usage Examples:

// Secured web element existence (iOS only)
await expect(web().element(by.web.type('textField')).asSecured()).toExist();
await expect(web().element(by.web.label('Secure Input')).asSecured()).not.toExist();

System Element Assertions

Assertions for system-level UI elements like permission dialogs and system alerts.

/**
 * Create assertion context for system element
 * @param systemElement - System element to assert against
 * @returns Assertion interface for system elements
 */
function expect(systemElement: SystemElement): SystemExpect;

interface SystemExpect {
  /**
   * Assert system element exists at system level
   */
  toExist(): Promise<void>;
  
  /**
   * Negate system element assertion
   */
  not: SystemExpect;
}

Usage Examples:

// System dialog assertions
await expect(system.element(by.system.label('Allow Location Access'))).toExist();
await expect(system.element(by.system.label('Permission Denied'))).not.toExist();

Assertion Error Handling

Understanding and handling assertion failures with detailed error information.

Common Error Scenarios:

// Element not found errors
try {
  await expect(element(by.id('missing_element'))).toBeVisible();
} catch (error) {
  console.log('Assertion failed:', error.message);
  // Error includes element matcher details and current screen state
}

// Timeout errors with waitFor
try {
  await waitFor(element(by.id('delayed_element')))
    .toBeVisible()
    .withTimeout(5000);
} catch (error) {
  console.log('Element did not become visible within timeout');
}

// Multiple elements without index
try {
  await expect(element(by.type('Button'))).toHaveText('Submit');
} catch (error) {
  // Use more specific matcher or atIndex()
  await expect(element(by.type('Button')).atIndex(0)).toHaveText('Submit');
}

Best Practices

Assertion Selection

Choose appropriate assertions based on validation goals:

// Use toExist() for presence validation
await expect(element(by.id('optional_feature'))).toExist();

// Use toBeVisible() for user-visible validation  
await expect(element(by.id('status_message'))).toBeVisible();

// Use toHaveText() for content validation
await expect(element(by.id('welcome_text'))).toHaveText('Welcome, John!');

// Use toHaveValue() for input validation
await expect(element(by.id('email_field'))).toHaveValue('test@example.com');

Timing Considerations

Handle asynchronous UI changes with proper waiting:

// Wait for element to appear before assertion
await waitFor(element(by.id('loading_complete')))
  .toBeVisible()
  .withTimeout(10000);

// Wait for element to disappear
await waitFor(element(by.id('loading_spinner')))
  .not.toBeVisible()
  .withTimeout(5000);

// Assert final state after waiting
await expect(element(by.id('success_message'))).toBeVisible();

Partial Visibility

Use visibility percentages for elements that may be partially obscured:

// Allow partially visible elements
await expect(element(by.id('bottom_sheet'))).toBeVisible(50);

// Require fully visible elements
await expect(element(by.id('critical_button'))).toBeVisible(100);

// Default 75% visibility threshold
await expect(element(by.id('standard_element'))).toBeVisible();

Negative Assertions

Use negative assertions to verify absence or hidden states:

// Verify error states are cleared
await expect(element(by.id('error_banner'))).not.toBeVisible();

// Verify elements are removed from DOM
await expect(element(by.id('temporary_popup'))).not.toExist();

// Verify focus moved away
await expect(element(by.id('previous_input'))).not.toBeFocused();

Types

interface Expect {
  toBeVisible(pct?: number): Promise<void>;
  toExist(): Promise<void>;
  toBeFocused(): Promise<void>;
  toHaveText(text: string): Promise<void>;
  toHaveLabel(label: string): Promise<void>;
  toHaveId(id: string): Promise<void>;
  toHaveValue(value: any): Promise<void>;
  toHaveToggleValue(value: boolean): Promise<void>;
  toHaveSliderPosition(position: number, tolerance?: number): Promise<void>;
  not: Expect;
  
  // Deprecated methods
  toBeNotVisible(): Promise<void>;
  toNotExist(): Promise<void>;
  toBeNotFocused(): Promise<void>;
}

interface WebExpect {
  toHaveText(text: string): Promise<void>;
  toExist(): Promise<void>;
  not: WebExpected;
}

interface SecuredWebExpect {
  toExist(): Promise<void>;
  not: SecuredWebExpect;
}

interface SystemExpect {
  toExist(): Promise<void>;
  not: SystemExpect;
}