How to Handle Touch and Mouse Events in Cypress

Use Cypress .click() when you want to test a normal, browser-like click, including its actionability checks and default behavior. Use .trigger() when your test needs to dispatch a particular event such as touchstart, mousemove, or mouseup with the properties your event handler reads. A triggered event invokes listeners; it does not reproduce every browser default action or emulate a physical touchscreen. Cypress click documentation · Cypress trigger documentation.

Choose the right Cypress interaction

Test goal	Use	What to keep in mind
Test a user clicking a button or link	.click()	Cypress waits for actionability and fires browser-like events. The click can rerender or remove the target, so query again afterward.
Exercise a particular event listener	.trigger('eventName', options)	Provide the event type and any properties the handler expects. This is low-level event dispatch, not a complete browser gesture.
Test a widget-specific mouse drag handler	A sequence of mousedown, mousemove, and mouseup	Coordinates and button fields depend on the widget implementation.
Test real device or browser touch behavior	Use a suitable browser/device automation setup for the behavior under test	.trigger('touchstart') alone does not establish that a real touch gesture was reproduced.

Cypress action commands include .click(), .dblclick(), .rightclick(), .type(), and others. Cypress checks that an element is ready to receive the action, including whether it is visible, enabled, attached, not animating, and not covered. See the interaction guide. .trigger() also participates in Cypress command behavior, but its key use is dispatching a named event with explicit options.

Set up a small, runnable example

These examples assume a Cypress project with a page at /events containing a button marked data-cy="open-modal", a modal marked data-cy="modal", and a draggable element marked data-cy="draggable". Put the spec in your project’s configured end-to-end spec folder, for example cypress/e2e/events.cy.js, then run Cypress using the project’s normal command.

describe('mouse and touch event handling', () => {
  beforeEach(() => {
    cy.visit('/events')
  })

  it('opens a modal with an ordinary click', () => {
    cy.get('[data-cy=open-modal]').click()
    // Query again: the click may have caused a rerender.
    cy.get('[data-cy=modal]').should('be.visible')
  })

  it('dispatches the mouse sequence expected by a sortable widget', () => {
    cy.get('[data-cy=draggable]').trigger('mousedown', {
      which: 1,
      pageX: 600,
      pageY: 100,
    })

    cy.get('[data-cy=draggable]').trigger('mousemove', {
      which: 1,
      pageX: 600,
      pageY: 600,
    })

    cy.get('[data-cy=draggable]').trigger('mouseup')
    cy.get('[data-cy=drag-result]').should('contain', 'complete')
  })
})

The drag fields above follow Cypress’s documented jQuery UI Sortable example; they are not universal requirements. Match the target application or widget’s actual listeners and assertions.

Test ordinary mouse clicks with .click()

Start with a fresh query, perform the action, then assert on the resulting application state in a new chain:

cy.get('[data-cy=save]').click()
cy.get('[data-cy=save-status]').should('have.text', 'Saved')

.click() accepts a DOM element yielded by a Cypress command and normally acts on a single element. Cypress documents that clicks include mouse and pointer events; its API history records additional pointer and mouse events in version 3.5.0. Treat that as history, not as a statement of the current Cypress version. Cypress also notes that if pointerdown is cancelled, it skips mousedown and mouseup, while still sending pointerup and click.

Click positions, coordinates, modifiers, and multiple elements

By default, Cypress clicks the center. You can choose a named position or coordinates relative to the element, and use supported modifier keys when your app has modifier-click behavior:

// Named position
cy.get('[data-cy=menu]').click('topRight')

// Coordinates relative to the element
cy.get('[data-cy=canvas]').click(20, 40)

// Modifier click
cy.get('[data-cy=file]').click({ shiftKey: true })

// Ctrl on Windows/Linux, Command on macOS
const modifier = Cypress.platform === 'darwin'
  ? { metaKey: true }
  : { ctrlKey: true }
cy.get('[data-cy=second-file]').click(modifier)

// Click each matching element in sequence when that is the intended test
cy.get('[data-cy=expand]').click({ multiple: true })

Supported named positions are topLeft, top, topRight, left, center, right, bottomLeft, bottom, and bottomRight. Click options include altKey, ctrlKey, metaKey, and shiftKey; aliases are documented in the API reference. Use .select() to change a select element rather than clicking the <select> itself.

Dispatch a specific mouse event with .trigger()

Use .trigger() when the code under test listens for a particular event or sequence. The handler determines which fields matter. A listener may inspect coordinates, buttons, pointer information, or another event property, so inspect the implementation and pass the values it actually consumes.

cy.get('[data-cy=canvas]').trigger('mousemove', {
  eventConstructor: 'MouseEvent',
  clientX: 120,
  clientY: 80,
})

A widget that reacts only to a press, movement, and release may need all three events:

const item = '[data-cy=draggable]'

cy.get(item).trigger('mousedown', {
  which: 1,
  pageX: 120,
  pageY: 80,
})
cy.get(item).trigger('mousemove', {
  which: 1,
  pageX: 180,
  pageY: 140,
})
cy.get(item).trigger('mouseup')

cy.get('[data-cy=drop-zone]').should('contain', 'Item')

Use the event constructor and coordinate fields that fit the handler and Cypress API. A handler listening for pointer events is different from one listening for mouse events; sending the wrong family will not exercise it. The options and default behavior are described in the trigger reference.

Handle touch-specific event handlers

If application code has a handler for a touch event, trigger the event name it uses and provide the properties the handler reads. For example, a simplified handler might update state on touchstart; a test can verify that path:

// Example assumes the app's handler accepts this event and updates status.
cy.get('[data-cy=touch-target]').trigger('touchstart')
cy.get('[data-cy=touch-status]').should('have.text', 'started')

This verifies that the test dispatched an event and the application responded to it. It does not prove that a physical touchscreen, mobile browser gesture recognizer, scrolling behavior, or device-generated touch sequence works. For those claims, run the relevant test in an environment that provides the browser/device behavior you need to validate. Do not replace a touch test with a mouse click unless the product behavior intentionally treats them as equivalent.

Keep actionability checks meaningful

For user-facing tests, leave normal actionability checks enabled. If .click() fails, Cypress may be waiting for the target to become visible, enabled, attached, stationary, or uncovered. That failure can reveal a real usability issue.

{ force: true } deliberately skips checks such as visibility, disabled state, detachment, animation, and coverage, and fires at the chosen element. Use it only when bypassing those checks is the explicit purpose of the test:

cy.get('[data-cy=offscreen-control]').click({ force: true })

A forced event can make a test pass without showing that a user could actually reach the control. For detached elements, changing the test to query the element again is usually the right fix. After a click that can rerender the page, start a new query chain rather than relying on the old subject.

Debug common failures

Symptom	Likely cause	Fix
.click() times out or says the element cannot be interacted with	The element may be hidden, disabled, detached, animating, or covered.	Inspect the Cypress command log and DOM at the action. Wait on a meaningful app signal, remove an overlay, or correct the selector/state. Use force only when bypassing actionability is intentional.
The event listener runs, but the expected browser behavior does not happen	.trigger() dispatched an event but did not perform the browser’s full default action.	Use the corresponding Cypress action command when the goal is ordinary user behavior, or explicitly implement/assert the handler path being tested.
Drag handler ignores the sequence	The event family, order, coordinates, button field, or target does not match what the widget expects.	Inspect listeners and the widget docs; send the expected down/move/up sequence and required fields. Do not assume one drag recipe works for every library.
Touch test passes but mobile gesture still fails	A synthetic event dispatch does not establish full device or browser touch emulation.	Keep the unit/integration event-handler test, and add a test in the browser/device environment needed for the actual gesture.
An assertion after click behaves inconsistently	The click may have replaced or removed the subject element.	Start a new chain and query the resulting state, such as cy.get('[data-cy=modal]').
A click fires on an element marked only with aria-disabled="true"	ARIA state alone is not the native disabled property Cypress checks for form controls.	Assert the intended accessibility/application behavior, and make the application’s disabled interaction behavior explicit. Do not assume the ARIA attribute prevents event dispatch.

Performance, reliability, and maintenance

• Prefer the shortest faithful interaction. A normal click is easier to maintain than a hand-built event sequence when the user action is simply a click.
• Use stable selectors. Application-owned attributes such as data-cy make tests less dependent on styling and layout.
• Assert outcomes, not just dispatch. Verify the visible state or application result after the event so the test covers behavior.
• Re-query after state changes. Cypress retries queries, but an action itself fires once; query the new DOM after an action that may rerender.
• Use coordinates only when relevant. Coordinate-dependent tests can become fragile when layout changes; use them where position is part of the behavior under test.
• Keep forced actions rare. They skip useful checks and may hide a real blocker for users.

For current configuration and browser-specific behavior, consult Cypress’s official API and interaction guide because documentation and implementations can evolve.

Or skip the browser setup

If the task is to capture a page image for documentation, a report, or visual review, ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns an image or PDF; it does not replace Cypress interaction tests.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Before capture, cookie banners are accepted and removed, along with supported newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Its MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card.

FAQ

Does .click() send pointer events?

Yes. Cypress documents mouse and pointer events for clicks. The precise sequence includes browser behavior such as skipping some mouse events when pointerdown is cancelled.

Can I use .trigger() to test touch?

You can dispatch a touch event to exercise a listener. That alone does not validate a physical touch device or full mobile browser gesture behavior.

Should I use { force: true } to fix a failing click?

Only if bypassing actionability is the test’s purpose. Otherwise, identify why the element is not actionable and fix the app state or test timing.

Why should I query again after clicking?

The action may cause the application to replace or remove the clicked element. A fresh query targets the current DOM.