tessl/npm-testcafe

Automated browser testing for the modern web development stack.

—

Pending

Overview

Eval results

Files

Assertions

Name: tessl/npm-testcafe
Author: tessl

TestCafe provides a comprehensive assertion system for verifying application state, element properties, and expected behaviors. All assertions automatically wait for conditions to be met within a timeout period.

Capabilities

Basic Assertions

Core assertion methods for equality, truthiness, and value comparison.

/**
 * Creates an assertion for a value
 * @param actual - Value or selector to assert against
 * @returns Assertion object with available assertion methods
 */
expect(actual: any): Assertion;

interface Assertion {
    /**
     * Asserts deep equality between actual and expected values
     * @param expected - Expected value for comparison
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    eql(expected: any, message?: string): Promise<void>;
    
    /**
     * Asserts values are not deeply equal
     * @param unexpected - Value that should not match actual
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notEql(unexpected: any, message?: string): Promise<void>;
    
    /**
     * Asserts value is truthy
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    ok(message?: string): Promise<void>;
    
    /**
     * Asserts value is falsy
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notOk(message?: string): Promise<void>;
}

Usage Examples:

import { Selector } from 'testcafe';

fixture('Basic Assertions')
    .page('https://example.com');

test('Equality assertions', async t => {
    const heading = Selector('h1');
    const button = Selector('#submit-button');
    
    // Check element text
    await t.expect(heading.innerText).eql('Welcome');
    await t.expect(heading.innerText).notEql('Goodbye');
    
    // Check element existence
    await t.expect(button.exists).ok();
    await t.expect(Selector('#nonexistent').exists).notOk();
    
    // Check element visibility
    await t.expect(button.visible).ok();
    
    // Custom error messages
    await t.expect(heading.innerText).eql('Welcome', 'Page heading should be "Welcome"');
});

String Assertions

Assertions for string content including contains, match, and type checking.

interface Assertion {
    /**
     * Asserts string contains expected substring
     * @param expected - Substring that should be present
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    contains(expected: string, message?: string): Promise<void>;
    
    /**
     * Asserts string does not contain substring
     * @param unexpected - Substring that should not be present
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notContains(unexpected: string, message?: string): Promise<void>;
    
    /**
     * Asserts string matches regular expression
     * @param re - Regular expression pattern to match
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    match(re: RegExp, message?: string): Promise<void>;
    
    /**
     * Asserts string does not match regular expression
     * @param re - Regular expression pattern that should not match
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notMatch(re: RegExp, message?: string): Promise<void>;
    
    /**
     * Asserts value is of expected type
     * @param typeName - Expected type name ('string', 'number', 'boolean', etc.)
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    typeOf(typeName: string, message?: string): Promise<void>;
    
    /**
     * Asserts value is not of specified type
     * @param typeName - Type name that should not match
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notTypeOf(typeName: string, message?: string): Promise<void>;
}

Usage Examples:

test('String assertions', async t => {
    const errorMessage = Selector('.error-message');
    const userEmail = Selector('#user-email');
    
    // Check text contains substring
    await t.expect(errorMessage.innerText).contains('Invalid');
    await t.expect(errorMessage.innerText).notContains('Success');
    
    // Check text matches pattern
    await t.expect(userEmail.value).match(/^[\w\.-]+@[\w\.-]+\.\w+$/);
    await t.expect(userEmail.value).notMatch(/invalid-pattern/);
    
    // Check value types
    const itemCount = await Selector('#item-count').innerText;
    await t.expect(parseInt(itemCount)).typeOf('number');
    await t.expect(itemCount).typeOf('string');
});

Numeric Assertions

Assertions for numeric comparisons including greater than, less than, and within ranges.

interface Assertion {
    /**
     * Asserts number is greater than expected value
     * @param expected - Value that actual should exceed
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    gt(expected: number, message?: string): Promise<void>;
    
    /**
     * Asserts number is greater than or equal to expected value
     * @param expected - Minimum value (inclusive)
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    gte(expected: number, message?: string): Promise<void>;
    
    /**
     * Asserts number is less than expected value
     * @param expected - Value that actual should be below
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    lt(expected: number, message?: string): Promise<void>;
    
    /**
     * Asserts number is less than or equal to expected value
     * @param expected - Maximum value (inclusive)
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    lte(expected: number, message?: string): Promise<void>;
    
    /**
     * Asserts number is within specified range
     * @param start - Range start value (inclusive)
     * @param finish - Range end value (inclusive)
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    within(start: number, finish: number, message?: string): Promise<void>;
    
    /**
     * Asserts number is not within specified range
     * @param start - Range start value (inclusive)
     * @param finish - Range end value (inclusive)
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notWithin(start: number, finish: number, message?: string): Promise<void>;
}

Usage Examples:

test('Numeric assertions', async t => {
    const price = Selector('.price');
    const quantity = Selector('#quantity');
    const progress = Selector('.progress-bar');
    
    // Compare numbers
    const priceValue = parseFloat(await price.innerText.replace('$', ''));
    await t.expect(priceValue).gt(0);
    await t.expect(priceValue).gte(9.99);
    await t.expect(priceValue).lt(1000);
    await t.expect(priceValue).lte(999.99);
    
    // Check ranges
    const quantityValue = parseInt(await quantity.value);
    await t.expect(quantityValue).within(1, 100);
    
    // Check progress percentage
    const progressWidth = (await progress.boundingClientRect).width;
    const containerWidth = (await progress.parent().boundingClientRect).width;
    const progressPercent = (progressWidth / containerWidth) * 100;
    await t.expect(progressPercent).within(0, 100);
});

Element State Assertions

Specialized assertions for DOM element states and properties.

interface Assertion {
    /**
     * Asserts element exists in DOM
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    exists(message?: string): Promise<void>;
    
    /**
     * Asserts element is visible on page
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    visible(message?: string): Promise<void>;
    
    /**
     * Asserts element is hidden or not visible
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    hidden(message?: string): Promise<void>;
    
    /**
     * Asserts element has keyboard focus
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    focused(message?: string): Promise<void>;
    
    /**
     * Asserts checkbox or radio button is checked
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    checked(message?: string): Promise<void>;
    
    /**
     * Asserts checkbox or radio button is not checked
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notChecked(message?: string): Promise<void>;
    
    /**
     * Asserts option element is selected
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    selected(message?: string): Promise<void>;
    
    /**
     * Asserts option element is not selected
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notSelected(message?: string): Promise<void>;
}

Usage Examples:

test('Element state assertions', async t => {
    const modal = Selector('#modal');
    const checkbox = Selector('#terms-checkbox');
    const dropdown = Selector('#country-select');
    const textInput = Selector('#username');
    
    // Element visibility
    await t.expect(modal.exists).ok();
    await t.expect(modal.visible).ok();
    await t.expect(Selector('#hidden-element').hidden).ok();
    
    // Form element states
    await t.click(checkbox);
    await t.expect(checkbox.checked).ok();
    
    await t.click(textInput);
    await t.expect(textInput.focused).ok();
    
    // Select element options
    await t.click(dropdown);
    await t.click(dropdown.find('option[value="us"]'));
    await t.expect(dropdown.find('option[value="us"]').selected).ok();
    await t.expect(dropdown.find('option[value="uk"]').notSelected).ok();
});

Collection Assertions

Assertions for arrays, collections, and element counts.

interface Assertion {
    /**
     * Asserts collection contains specified item
     * @param expected - Item that should be present in collection
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    contains(expected: any, message?: string): Promise<void>;
    
    /**
     * Asserts collection does not contain specified item
     * @param unexpected - Item that should not be present in collection
     * @param message - Optional custom error message
     * @returns Promise that resolves if assertion passes
     */
    notContains(unexpected: any, message?: string): Promise<void>;
}

Usage Examples:

test('Collection assertions', async t => {
    const menuItems = Selector('.menu li');
    const tableRows = Selector('table tbody tr');
    const selectedOptions = Selector('#multi-select option:checked');
    
    // Element count assertions
    await t.expect(menuItems.count).eql(5);
    await t.expect(menuItems.count).gt(3);
    await t.expect(tableRows.count).gte(1);
    
    // Check if collections contain specific items
    const menuTexts = [];
    const menuCount = await menuItems.count;
    for (let i = 0; i < menuCount; i++) {
        menuTexts.push(await menuItems.nth(i).innerText);
    }
    
    await t.expect(menuTexts).contains('Home');
    await t.expect(menuTexts).notContains('Admin');
    
    // Multiple selection assertions
    await t.expect(selectedOptions.count).gte(1);
});

Custom Assertions

Create custom assertion logic using client functions.

/**
 * Use client functions for custom assertions
 * @param clientFn - Client function returning value to assert
 * @returns Assertion chain for the returned value
 */
expect(clientFn: ClientFunction): Assertion;

Usage Examples:

import { ClientFunction } from 'testcafe';

test('Custom assertions', async t => {
    // Custom client function for assertion
    const getLocalStorageItem = ClientFunction((key) => {
        return localStorage.getItem(key);
    });
    
    const getCurrentUrl = ClientFunction(() => window.location.href);
    
    const getElementCount = ClientFunction((selector) => {
        return document.querySelectorAll(selector).length;
    });
    
    // Assert localStorage values
    await t.expect(getLocalStorageItem('userToken')).ok();
    await t.expect(getLocalStorageItem('theme')).eql('dark');
    
    // Assert current URL
    await t.expect(getCurrentUrl()).contains('/dashboard');
    
    // Assert dynamic element counts
    await t.expect(getElementCount('.notification')).gt(0);
    await t.expect(getElementCount('.error')).eql(0);
});

Assertion Options

Control assertion behavior with timeout and other options.

/**
 * Configure assertion timeout
 * @param timeout - Maximum wait time in milliseconds
 * @returns Modified assertion with custom timeout
 */
within(timeout: number): Assertion;

Usage Examples:

test('Assertion timeouts', async t => {
    const slowElement = Selector('#slow-loading-element');
    const quickElement = Selector('#quick-element');
    
    // Wait longer for slow elements
    await t.expect(slowElement.exists).ok().within(10000); // 10 seconds
    
    // Quick timeout for elements that should appear fast
    await t.expect(quickElement.visible).ok().within(1000); // 1 second
    
    // Default timeout (configurable globally)
    await t.expect(Selector('#normal-element').exists).ok();
});

Install with Tessl CLI