cypress/docs/source/api/commands/_trigger.md

title, comments

title	comments
trigger	false

Trigger an event on a DOM element.

Syntax

.trigger(eventName)
.trigger(eventName, position)
.trigger(eventName, options)
.trigger(eventName, x, y)
.trigger(eventName, position, options)
.trigger(eventName, x, y, options)

Usage

.trigger() requires being chained off another cy command that yields a DOM element.

{% fa fa-check-circle green %} Valid Usage

cy.get('a').trigger('mousedown') // Trigger mousedown event on link

{% fa fa-exclamation-triangle red %} Invalid Usage

cy.trigger('touchstart')             // Errors, cannot be chained off 'cy'
cy.location().trigger('mouseleave')  // Errors, 'location' does not yield DOM element

Arguments

{% fa fa-angle-right %} eventName (String)

The name of the event to be triggered on the DOM element.

{% fa fa-angle-right %} position (String)

The position where the event should be triggered. The center position is the default position. Valid positions are topLeft, top, topRight, left, center, right, bottomLeft, bottom, and bottomRight.

{% fa fa-angle-right %} x (Number)

The distance in pixels from element's left to trigger the event.

{% fa fa-angle-right %} y (Number)

The distance in pixels from element's top to trigger the event.

{% fa fa-angle-right %} options (Object)

Pass in an options object to change the default behavior of .trigger().

Option	Default	Notes
bubbles	true	Whether the event bubbles
cancelable	true	Whether the event is cancelable
interval	16	Interval which to retry triggering the event
log	true	Whether to display command in Command Log
timeout	{% url defaultCommandTimeout configuration#Timeouts %}	Total time to retry triggering the event

You can also include arbitrary event properties (e.g. clientX, shiftKey) and they will be attached to the event. Passing in coordinate arguments (clientX, pageX, etc) will override the position coordinates.

Yields

.trigger() yields the DOM subject chained from the previous command.

Timeout

.trigger() will wait until the element is in an 'interactable' state for the duration of the {% url defaultCommandTimeout configuration#Timeouts %} or the duration of the timeout specified in the command's options.

Examples

Mouse Events

Trigger a mouseover on the button

The DOM element must be in an "interactable" state prior to the triggered event happening (it must be visible and not disabled).

cy.get('button').trigger('mouseover') // yields 'button'

Drag and Drop

{% note info %} {% url 'Check out our example recipe triggering mouse and drag events to test dragging and dropping' 'https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/drag_n_drop_spec.js' %} {% endnote %}

Change Event

Interact with a range input (slider)

To interact with a range input (slider), we need to set its value and then trigger the appropriate event to signal it has changed.

Below we invoke jQuery's val() method to set the value, then trigger the change event.

Note that some implementations may rely on the input event instead, which is fired as a user moves the slider, but is not supported by some browsers.

cy.get('input[type=range]').as('range')
  .invoke('val', 25)
  .trigger('change')

cy.get('@range').siblings('p').should('have.text', '25')

Position

Trigger a mousedown on the top right of a button

cy.get('button').trigger('mousedown', 'topRight')

Coordinates

Specify explicit coordinates relative to the top left corner

cy.get('button').trigger('contextmenu', 15, 40)

Options

Specify that the event should not bubble

By default, the event will bubble up the DOM tree. This will prevent the event from bubbling.

cy.get('button').trigger('mouseover', { bubbles: false })

Specify the exact clientX and clientY the event should have

This overrides the default auto-positioning based on the element itself. Useful for events like mousemove where you need the position to be outside the element itself.

cy.get('button').trigger('mousemove', {clientX: 200, clientY: 300})

Notes

What event should I fire?

cy.trigger is meant to be a low-level utility that makes triggering events easier than manually constructing and dispatching them. Since any arbitrary event can be triggered, Cypress tries not to make any assumptions about how it should be triggered. This means you'll need to know the implementation details (which may be in a 3rd party library) of the event handler(s) receiving the event and provide the necessary properties.

Command Log

Trigger a mouseover event on the first button

cy.get('button').first().trigger('mouseover')

The commands above will display in the command log as:

When clicking on trigger within the command log, the console outputs the following:

See also

• {% url .blur() blur %}
• {% url .check() check %}
• {% url .click() click %}
• {% url .focus() focus %}
• {% url .select() select %}
• {% url .submit() submit %}
• {% url .type() type %}
• {% url .uncheck() uncheck %}