Handle Touch and Mouse Events in Cypress

This guide shows you how to simulate touch and mouse interactions in Cypress tests, covering everything from simple clicks to complex gestures like pinch and swipe. You’ll learn the commands, event triggering, and best practices to make your tests reliable across desktop and mobile browsers.

What You’ll Need

• A Cypress project set up (Cypress 10 or later recommended).
• Basic familiarity with writing Cypress tests.
• A test application that responds to mouse or touch events (can be a local dev server or a hosted page).

Step-by-Step

1. Start with standard mouse events. Cypress’s click(), dblclick(), rightclick(), and hover() commands cover most mouse interactions. For example, to click a button: cy.get('button').click().
2. Pass options to control the event. Most mouse commands accept an options object. For instance, cy.get('button').click({ force: true }) bypasses actionability checks, and cy.get('a').click({ multiple: true }) clicks all matching elements.
3. Trigger raw mouse events. If you need to fire a specific event like mousedown or mouseup separately, use .trigger('mousedown'). You can pass event properties: cy.get('div').trigger('mousemove', { clientX: 100, clientY: 200 }).
4. Simulate touch events. Cypress does not have built-in touch commands, so you’ll use .trigger() with touch event types. For a tap, fire touchstart and touchend in sequence: cy.get('button').trigger('touchstart').trigger('touchend').
5. Add touch points for multi-touch. For gestures like pinch or rotate, you need multiple touch points. Pass an array of touches in the event properties: cy.get('img').trigger('touchstart', { touches: [{ clientX: 100, clientY: 100 }, { clientX: 200, clientY: 200 }] }).
6. Simulate swipe or scroll. Use touchmove with a series of coordinates. You can chain multiple triggers: cy.get('.carousel').trigger('touchstart', { touches: [{ clientX: 300, clientY: 200 }] }).trigger('touchmove', { touches: [{ clientX: 100, clientY: 200 }] }).trigger('touchend').
7. Use real mouse events for hover. The .trigger('mouseover') can simulate hover, but .hover() is more reliable as it also checks visibility. For dropdowns, cy.get('.menu').trigger('mouseenter') works well.
8. Combine events for drag-and-drop. Cypress doesn’t have a native drag command, but you can simulate it with mouse events: cy.get('#draggable').trigger('mousedown', { which: 1 }).trigger('mousemove', { clientX: 200, clientY: 200 }).trigger('mouseup').
9. Test touch on a viewport. To emulate a mobile device, set the viewport size: cy.viewport('iphone-6'). This changes the dimensions but does not automatically enable touch events; you still need to trigger them manually.
10. Verify the events fired. Use spies or stubs to assert that your event handlers ran. For example, if you have a Vue component with @touchstart="handler", you can use cy.spy() to check it was called.

Common Mistakes

• Forgetting to include touches in touch events. Some browsers require a touches array; without it, the event may not be recognized as a touch event.
• Using click() for touch-only elements. If your app only listens to touch events, a mouse click won’t trigger the expected behavior. You must fire touch events.
• Ignoring actionability checks. Cypress waits for elements to be visible, enabled, and not covered. If your element is animating or off-screen, the command may time out. Use { force: true } if you’re sure it’s safe.
• Not cleaning up between tests. If you trigger events that leave state changes (like a hover state), you might need to reset the DOM or reload the page between tests.

Tips

• Prefer .click() over .trigger('click'). The former runs Cypress’s actionability checks, making tests more robust.
• Use cy.get() with a specific selector to avoid multiple matches, which can cause errors.
• For complex gestures, consider a custom Cypress command. Wrap the sequence of triggers in a Cypress.Commands.add() to reuse it.
• Test both mouse and touch paths if your app supports both, to ensure responsive behavior.
• Use cy.clock() for animations to control time and avoid waiting for transitions to finish.

Troubleshooting

Events not firing? Check that the element is attached and visible. Cypress may refuse to interact with an element that is not in the DOM. Use cy.get(...).should('be.visible') first.

Touch events seem ignored? Ensure your event object includes the touches array. Also, some frameworks (like React) use synthetic events; you may need to trigger both native and synthetic events, e.g., .trigger('touchstart', { force: true }).

Actionability timeout? If Cypress says the element is covered, use { force: true } only if you’re certain it’s a false positive. Otherwise, wait for the element to be unobstructed with cy.get(...).should('be.visible').

Multiple elements matched? Use .first() or .eq() to target a specific one, or refine your selector.

Mouse events not working on mobile viewport? Some mobile browsers translate mouse events to touch events. If your app uses touch handlers, you must fire touch events explicitly.

Frequently Asked Questions

Can I simulate a pinch gesture in Cypress?

Yes, by triggering touchstart with two touch points, then touchmove with the points moving apart, and finally touchend. You’ll need to manually compute the coordinates.

Does Cypress support touch events natively?

No, Cypress doesn’t have built-in commands for touch, but you can use .trigger() to fire any DOM event, including touch events.

How do I simulate a right-click?

Use .rightclick() or .trigger('contextmenu').

Why does .hover() not work on some elements?

It might be because the element is not visible or is covered. Also, some elements require mouseenter and mouseleave events; use .trigger('mouseenter') instead.

Can I test drag-and-drop with Cypress?

Yes, by simulating mousedown, mousemove, and mouseup events. There are also plugins like cypress-drag-drop that simplify this.

Should I use cy.trigger() or cy.get().trigger()?

Both work; the latter is more common because it chains off a subject. cy.trigger() is used when you need to trigger an event on the document or window.

Related

• How to Rank Values with the RANK Function
• Intel 7nm Delay: New Timeline & Impact
• Freeware OCR Program: Best Free Options