t.dispatchEvent Method

t.dispatchEvent(target, eventName[, options]) → this | Promise<any>

Important

TestCafe can not execute the t.dispatchEvent method in Internet Explorer, since IE does not support event constructors.

Fires a DOM event at the specified target. Use the t.dispatchEvent method to perform custom page actions.

Parameter Type Description
target Function | String | Selector | Snapshot | Promise Event target. See Select event targets.
eventName String Event name. See the MDN list of common browser events.
options (optional) Object A set of event parameters. See Options.

Select event targets

Use the selector parameter to identify the target of a DOM event.

You can pass any of the following objects as a selector:

  • A CSS selector string.

    test('My Test', async t => {
    
        // Click will be performed on the first element
        // that matches the CSS selector.
        await t.click('#submit-button');
    });
    
  • A selector.

    import { Selector } from 'testcafe';
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    const lastItem = Selector('.toc-item:last-child');
    
    test('My Test', async t => {
    
        // Click will be performed on the element selected by
        // the 'getLastItem' selector.
        await t.click(lastItem);
    });
    
  • A client-side function that returns a DOM element.

    test('My Test', async t => {
    
        // Click will be performed on the element returned by the function,
        // which is the third child of the document's body.
        await t.click(() => document.body.children[2]);
    });
    
  • A DOM node snapshot.

    import { Selector } from 'testcafe';
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    test('My Test', async t => {
        const topMenuSnapshot = await Selector('#top-menu');
    
        // Click will be performed on the element whose snapshot
        // is specified. This is an element with the '#top-menu' ID.
        await t.click(topMenuSnapshot);
    });
    
  • A Promise returned by a selector.

    import { Selector } from 'testcafe';
    
    const submitButton = Selector('#submit-button');
    
    fixture `My fixture`
        .page `http://www.example.com/`;
    
    test('My Test', async t => {
    
        // Click will be performed on the element specified by the selector
        // as soon as the promise is resolved.
        await t.click(submitButton());
    });
    

TestCafe waits for the target element to become visible before it executes an action. If this does not happen within the selector timeout, the test fails.

TestCafe cannot interact with background elements. If a different element overlaps the action target, TestCafe waits for this element to disappear. If this does not happen within the selector timeout, TestCafe performs the action with the element on top of the original target. Learn more about stacking and z-index on MDN.

Note

The upload action is an exception to this rule — it does not check the visibility of the target input.

eventName

Browser event name.

TestCafe knows which events correspond to the following five event constructors:

  1. MouseEvent()
  2. KeyboardEvent()
  3. InputEvent()
  4. FocusEvent()
  5. PointerEvent()
  • If the value of the eventName parameter matches an event that TestCafe is aware of, TestCafe invokes one of the constructors above.
  • If the value of the eventName parameter does not match an event that TestCafe is aware of, TestCafe invokes the CustomEvent constructor.
  • Modify the eventConstructor option to launch a particular event constructor.

Read the Custom Events Guide for more information on event constructors.

Options

The options object stores event properties. Most properties are constructor-specific. Event Interface Properties apply to ALL event types.

All DOM events bubble and are cancelable unless you override these parameters.

Explicit Constructor Assignment

The eventConstructor option determines the constructor that TestCafe uses to fire the event.

The following example fires a non-cancelable, non-bubbling TouchEvent.

dsa
import { Selector } from 'testcafe';

fixture`Dispatch Events`
    .page('./index.html');

test('Dispatch a TouchEvent', async t => {
    const target = Selector('#target');

    const eventArgs = {
        cancelable: false,
        bubbles:    false
    };

    const options = Object.assign(
        { eventConstructor: 'TouchEvent' },
        eventArgs
    );

    await t
        .dispatchEvent(target, 'touchstart', options)
});