Implementation:DevExpress Testcafe Selector TypeDefs

Knowledge Sources	DevExpress_Testcafe TestCafe Selector API
Domains	Type_Definitions, Testing, DOM_Querying
Last Updated	2026-02-12 12:00 GMT

Overview

Concrete TypeScript type declarations for TestCafe's Selector API, the primary mechanism for identifying, querying, and inspecting DOM elements in tested pages.

Description

This file declares SelectorOptions (with boundTestRun, timeout, dependencies, and visibilityCheck), the large SelectorAPI interface which mirrors NodeSnapshot properties but wraps them all in Promise<> for async access. SelectorAPI provides a comprehensive set of chainable DOM traversal and filtering methods: nth, withText, withExactText, withAttribute, filter, filterVisible, filterHidden, find, parent, child, sibling, nextSibling, prevSibling (each with overloads accepting index, CSS selector, or predicate function). Additional API includes exists, count, shadowRoot, addCustomDOMProperties, addCustomMethods, and with for option overriding.

Usage

Import these type declarations to get full TypeScript IntelliSense when writing TestCafe tests with Selectors. These types are automatically available in TypeScript test files.

Code Reference

Source Location

• Repository: DevExpress_Testcafe
• File: ts-defs-src/test-api/selector.d.ts
• Lines: 1-476

Signature

interface SelectorOptions {
    boundTestRun?: TestController;
    timeout?: number;
    dependencies?: { [key: string]: any };
    visibilityCheck?: boolean;
}

interface SelectorAPI {
    // Node properties (all Promise-wrapped)
    childElementCount: Promise<number>;
    childNodeCount: Promise<number>;
    textContent: Promise<string>;
    tagName: Promise<string>;
    visible: Promise<boolean>;
    attributes: Promise<{ [name: string]: string }>;
    // ... 30+ more properties

    // Filtering methods
    nth(index: number): Selector;
    withText(text: string | RegExp): Selector;
    withExactText(text: string): Selector;
    withAttribute(attrName: string | RegExp, attrValue?: string | RegExp): Selector;
    filter(cssSelector: string): Selector;
    filter(filterFn: (node: Element, idx: number) => boolean, dependencies?: object): Selector;
    filterVisible(): Selector;
    filterHidden(): Selector;

    // Traversal methods
    find(cssSelector: string): Selector;
    parent(index?: number): Selector;
    child(index?: number): Selector;
    sibling(index?: number): Selector;
    nextSibling(index?: number): Selector;
    prevSibling(index?: number): Selector;
    shadowRoot(): Selector;

    // Counter properties
    count: Promise<number>;
    exists: Promise<boolean>;

    // Extension methods
    addCustomDOMProperties(props: object): Selector;
    addCustomMethods(methods: object, opts?: object): Selector;
    with(options?: SelectorOptions): Selector;
}

interface Selector extends SelectorAPI {
    (...args: any[]): SelectorPromise;
}

interface SelectorPromise extends SelectorAPI, Promise<NodeSnapshot> { }

interface SelectorFactory {
    (init: string | Function | Selector | Snapshot | SelectorPromise, options?: SelectorOptions): Selector;
}

Import

// Automatically available in TestCafe TypeScript test files
// No explicit import needed - available as global type
import { Selector } from 'testcafe';

I/O Contract

Inputs

Name	Type	Required	Description
init	string or Function or Selector or Snapshot	Yes	CSS selector string, filter function, or existing selector
options	SelectorOptions	No	Timeout, visibility check, test run binding, dependencies

Outputs

Name	Type	Description
Selector	SelectorAPI	Chainable selector with filtering, traversal, and property access
SelectorPromise	SelectorAPI & Promise<NodeSnapshot>	Awaitable selector resolving to a DOM snapshot

Usage Examples

import { Selector } from 'testcafe';

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

test('Select elements with typed API', async (t: TestController) => {
    // Create a selector
    const header = Selector('h1');

    // Access properties (all return Promises)
    const text: string = await header.textContent;
    const isVisible: boolean = await header.visible;

    // Chain filtering methods
    const activeItem = Selector('.list-item')
        .withAttribute('data-active', 'true')
        .filterVisible()
        .nth(0);

    // Traverse the DOM
    const parentDiv = Selector('.child').parent('div');
    const firstChild = Selector('.container').child(0);

    // Count and existence
    const itemCount: number = await Selector('.item').count;
    const exists: boolean = await Selector('#optional').exists;

    // Assertions
    await t.expect(header.textContent).eql('Welcome');
    await t.expect(Selector('.items').count).gt(0);
});

Related Pages

• Environment:DevExpress_Testcafe_Node_Runtime