Implementation:DevExpress Testcafe NativeAutomation Input

Knowledge Sources	DevExpress_Testcafe TestCafe Docs
Domains	Browser Automation, Input Simulation, CDP Integration
Last Updated	2026-02-12 12:00 GMT

Overview

NativeAutomationInput and CDPEventDescriptor translate high-level TestCafe input actions (mouse clicks, key presses, touch gestures) into Chrome DevTools Protocol Input.dispatch* event payloads.

Description

These two classes form the input simulation layer of TestCafe's native automation:

• NativeAutomationInput (src/native-automation/client/input.ts, 77 lines) is the public-facing input controller. It wraps a DispatchEventFn callback (which ultimately calls the CDP Input domain methods) and exposes semantic methods: mouseDown, mouseUp, keyDown, keyUp, executeEventSequence, executeInsertText, and createMouseMoveEvent. When running on a touch device (detected via hammerhead's feature detection), mouse events are transparently converted to touch events.

• CDPEventDescriptor (src/native-automation/client/event-descriptor.ts, 155 lines) is a static helper that builds the exact option objects expected by the CDP Input.dispatchMouseEvent, Input.dispatchKeyEvent, and Input.dispatchTouchEvent methods. It handles iframe coordinate translation by recursively querying parent frames for their top-left offset via the hammerhead message sandbox. It also provides convenience factory methods (keyDown, keyUp, delay) for building event sequences.

Usage

Use NativeAutomationInput inside the native automation client-side driver whenever a test action requires synthesising browser input events. The class is instantiated once per automation session with the appropriate dispatch function, and its methods are called by the action pipeline (click, type, drag, etc.).

Code Reference

Source Location

• Repository: DevExpress_Testcafe
• File (Input): src/native-automation/client/input.ts
• Lines: 1-77
• File (EventDescriptor): src/native-automation/client/event-descriptor.ts
• Lines: 1-155

Signature

// NativeAutomationInput (src/native-automation/client/input.ts)
export default class NativeAutomationInput {
    private readonly _dispatchEventFn: DispatchEventFn;

    constructor (dispatchEventFn: DispatchEventFn);

    public async mouseDown (options: any): Promise<void>;
    public async mouseUp (options: any): Promise<void>;
    public keyDown (options: SimulatedKeyInfo): Promise<void>;
    public keyUp (options: SimulatedKeyInfo): Promise<void>;
    public executeEventSequence (eventSequence: any[]): Promise<void>;
    public async executeInsertText (text: string): Promise<any>;
    public async createMouseMoveEvent (
        currPosition: AxisValuesData<number>,
        modifiers: Modifiers,
    ): Promise<any>;
}

// CDPEventDescriptor (src/native-automation/client/event-descriptor.ts)
export default class CDPEventDescriptor {
    public static createKeyDownOptions (options: SimulatedKeyInfo): any;
    public static createKeyUpOptions (options: SimulatedKeyInfo): any;
    public static async createMouseEventOptions (type: string, options: any): Promise<any>;
    public static async createTouchEventOptions (type: string, options: any): Promise<any>;
    public static delay (delay: number): any;
    public static keyDown (keyInfo: SimulatedKeyInfo): any;
    public static keyUp (keyInfo: SimulatedKeyInfo): any;
}

Import

import NativeAutomationInput from '../native-automation/client/input';
import CDPEventDescriptor from '../native-automation/client/event-descriptor';

I/O Contract

NativeAutomationInput Constructor

Parameter	Type	Description
dispatchEventFn	DispatchEventFn	Object with single(type, options) and sequence(events) methods that forward events to CDP

Key Method Inputs

Method	Parameter	Type	Description
mouseDown / mouseUp	options	any	Object containing options.clientX, options.clientY, options.button, and modifier flags
keyDown / keyUp	options	SimulatedKeyInfo	Key information including keyCode, keyProperty, modifiers, commands, and isNewLine
executeInsertText	text	string	Text to insert via the CDP Input.insertText method
createMouseMoveEvent	currPosition	AxisValuesData<number>	Target {x, y} coordinates for the mouse move
createMouseMoveEvent	modifiers	Modifiers	Active keyboard modifiers (ctrl, alt, shift, meta)

Key Method Outputs

Method	Return Type	Description
mouseDown / mouseUp	Promise<void>	Dispatches mouse or touch event to CDP
keyDown / keyUp	Promise<void>	Dispatches keyboard event to CDP
executeEventSequence	Promise<void>	Dispatches an ordered array of events sequentially
createMouseMoveEvent	Promise<{type, options}>	Returns a CDP mouse-move event descriptor (does not dispatch it)

CDPEventDescriptor Output Shapes

Factory Method	Output Fields
createKeyDownOptions	'rawKeyDown', modifiers, windowsVirtualKeyCode, key, commands, text }
createKeyUpOptions	{ type: 'keyUp', modifiers, key, windowsVirtualKeyCode }
createMouseEventOptions	{ x, y, modifiers, button, type, clickCount: 1, force: 0.5 }
createTouchEventOptions	{ modifiers, touchPoints: [{x, y}], type }

Usage Examples

import NativeAutomationInput from '../native-automation/client/input';
import CDPEventDescriptor from '../native-automation/client/event-descriptor';

// Create the input controller with a dispatch function
const input = new NativeAutomationInput(dispatchEventFn);

// Simulate a mouse click at position (100, 200)
await input.mouseDown({ options: { clientX: 100, clientY: 200, button: 'left' } });
await input.mouseUp({ options: { clientX: 100, clientY: 200, button: 'left' } });

// Simulate typing a key
await input.keyDown({ keyCode: 65, keyProperty: 'a', modifiers: 0, commands: [], isNewLine: false });
await input.keyUp({ keyCode: 65, keyProperty: 'a', modifiers: 0, commands: [] });

// Insert text directly
await input.executeInsertText('Hello, World!');

// Build a mouse-move event descriptor for an event sequence
const moveEvent = await input.createMouseMoveEvent({ x: 150, y: 250 }, {});

// Build and dispatch a complete event sequence
const sequence = [
    CDPEventDescriptor.keyDown(keyInfo),
    CDPEventDescriptor.delay(50),
    CDPEventDescriptor.keyUp(keyInfo),
];
await input.executeEventSequence(sequence);

Related Pages

• Environment:DevExpress_Testcafe_Node_Runtime
• DevExpress_Testcafe_NativeAutomation_Entry - Main native automation entry point that owns the automation session
• DevExpress_Testcafe_NativeAutomation_ResourceInjector - Script injection that sets up the client-side environment where input is dispatched