Fire DOM Events

Important

This article describes how to fire arbitrary DOM events during test execution. Read the Custom Test Actions guide for information on how to define custom TestController actions.

DOM events occur when users interact with the page. For example, a simple click action consists of three distinct DOM events: mousedown, mouseup, and click. Action methods that come with TestCafe fire DOM events to simulate user interaction.

TestCafe can dispatch arbitrary DOM events.

If you need to perform a page interaction that TestCafe does not support out of the box, break it down into discrete DOM events, and fire events one by one with the t.dispatchEvent method. Save the code as a custom test action to reuse it throughout your test suite.

Events and Constructors

There are many different kinds of DOM events. Some events can only target certain page elements (i.e. submit events can only target <form> elements). Some events have parameters that other events don’t.

Similar events share the same event constructor. Event constructors determine how you can customize the event, and what entities the event can target.

Common Events

TestCafe lets you fire common DOM events without specifying the constructor. If the action that you want to dispatch corresponds to one of the constructors above, TestCafe automatically launches the correct constructor for the event.

MouseEvent()

The MouseEvent constructor fires the following events:

  • mouseup
  • mousedown
  • click
  • dbclick
  • mousemove
  • mouseover
  • mouseleave
  • contextmenu
  • drag
  • dragend
  • dragenter
  • dragexit
  • dragleave
  • dragover
  • dragstart
  • drop

The MouseEvent constructor accepts MouseEvent properties.

The buttons property specifies the primary click button. The default value of the buttons property is 1 (the left button).

The example below fires the mousedown and mouseup events to simulate a 5-second-long left-click action. Note the value of the buttons option.

import { Selector } from 'testcafe';

fixture`Trigger Mouse Events`
    .page('www.example.com');

test('Left-click a button for 5 seconds', async t => {
    const target = Selector('#target');

    await t
        .dispatchEvent(target, 'mousedown')
        .wait(5000)
        .dispatchEvent(target, 'mouseup');
});

The example below simulates a 5-second-long right-click action. Note the value of the buttons option.

import { Selector } from 'testcafe';

fixture`Trigger Mouse Events`
    .page('www.example.com');

test('Right-click a button for 5 seconds', async t => {
    const target  = Selector('#target');
    const options = {
        buttons: 2
    };

    await t
        .dispatchEvent(target, 'mousedown', options)
        .wait(5000)
        .dispatchEvent(target, 'mouseup', options);
});

KeyboardEvent()

The KeyboardEvent constructor fires the following events:

  • keydown
  • keyup
  • keypress

The KeyboardEvent constructor accepts KeyboardEvent Properties.

InputEvent()

The InputEvent constructor fires the following events:

  • input
  • beforeinput

The InputEvent constructor accepts InputEvent Properties.

FocusEvent()

The FocusEvent constructor fires the following events:

  • blur
  • focus
  • focusin
  • focusout

The FocusEvent constructor accepts FocusEvent properties.

PointerEvent()

The PointerEvent Constructor fires the following events:

  • pointerover
  • pointerenter
  • pointerdown
  • pointermove
  • pointerrawupdate
  • pointerup
  • pointercancel
  • pointerout
  • pointerleave

The PointerEvent constructor accepts PointerEvent properties.

Custom Events

The CustomEvent constructor fires custom events with CustomEvent properties.

The example below dispatches a foo event. 

import { Selector } from 'testcafe';

fixture`Custom Events`
    .page('www.example.com');

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

    await t
        .dispatchEvent(target, 'foo')
});

Other Events

To pick a different constructor, define the value of the eventConstructor property.

The following example fires a touchstart TouchEvent:

dsa
import { Selector } from 'testcafe';

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

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

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

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