Cypress App

rightclick

Right click a DOM element to test custom context menus and other contextmenu handling in your app.

caution

.rightclick() does not open context menus native to the browser. To confirm your app suppresses the browser's own menu, see Check that your app blocks the native context menu.

Syntax

.rightclick()
.rightclick(options)
.rightclick(position)
.rightclick(position, options)
.rightclick(x, y)
.rightclick(x, y, options)

Usage

Correct Usage

cy.get('[data-cy=file-row]').first().rightclick() // Right click on the first file row
cy.focused().rightclick() // Right click on el with focus
cy.contains('Today').rightclick() // Right click on first el containing 'Today'

Incorrect Usage

cy.rightclick('[data-cy=file-row]') // Errors, cannot be chained off 'cy'
cy.window().rightclick() // Errors, 'window' does not yield DOM element

Arguments

position (String)

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

x (Number)

The distance in pixels from the element's left to issue the right click.

y (Number)

The distance in pixels from the element's top to issue the right click.

options (Object)

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

Option	Default	Description
altKey	false	Activates the alt key (option key for Mac). Aliases: optionKey.
animationDistanceThreshold	animationDistanceThreshold	The distance in pixels an element must exceed over time to be considered animating.
ctrlKey	false	Activates the control key. Aliases: controlKey.
force	false	Forces the action, disables waiting for actionability.
log	true	Displays the command in the Command Log.
metaKey	false	Activates the meta key (Windows key or command key for Mac). Aliases: commandKey, cmdKey.
multiple	false	Serially right click multiple elements.
scrollBehavior	scrollBehavior	Viewport position to where an element should be scrolled before executing the command. Accepts a single alignment, a per-axis { block, inline } object, or false.
shiftKey	false	Activates the shift key.
timeout	defaultCommandTimeout	Time to wait for .rightclick() to resolve before timing out.
waitForAnimations	waitForAnimations	Whether to wait for elements to finish animating before executing the command.

Yields

• .rightclick() yields the same subject it was given.
• It is unsafe to chain further commands that rely on the subject after .rightclick().

Examples

Context menus

Open a custom context menu

Chaining further commands off the subject of .rightclick() is unsafe, since opening a menu can re-render the element. Start a new chain from cy and assert that the menu appeared.

cy.get('[data-cy=file-row]').first().rightclick()
cy.get('[data-cy=context-menu]').should('be.visible')

Choose an item from a context menu

Once the menu opens, find the item you want by its label and click it.

cy.get('[data-cy=file-row]').first().rightclick()
cy.get('[data-cy=context-menu]').contains('Rename').click()
cy.get('[data-cy=rename-input]').should('be.focused')

Close a context menu

Test the way your users close the menu. Many menus close when the user presses Escape. cy.press() sends a native key press, the way a user's keyboard does.

cy.get('[data-cy=file-row]').first().rightclick()
cy.get('[data-cy=context-menu]').should('be.visible')
cy.press(Cypress.Keyboard.Keys.ESC)
cy.get('[data-cy=context-menu]').should('not.exist')

Check that your app blocks the native context menu

.rightclick() never opens the browser's own context menu, so a test can pass even when your app forgets to call preventDefault() and real users see two menus. To check, add a contextmenu listener on the window after the page loads. It runs after your app's own handlers, so the event it receives shows whether one of them called preventDefault().

cy.window().then((win) => {
  win.addEventListener('contextmenu', cy.stub().as('contextmenu'))
})
cy.get('[data-cy=file-row]').first().rightclick()
cy.get('@contextmenu').should('have.been.calledWithMatch', {
  defaultPrevented: true,
})

If your app stops the event from propagating, the window listener never runs. Assert on your app's menu instead.

Position

Specify a corner of the element to right click

Right click the top right corner of the DOM element.

cy.get('[data-cy=file-row]').first().rightclick('topRight')

Coordinates

Specify explicit coordinates relative to the top left corner

The right click below is issued inside of the element (15px from the left and 40px from the top).

cy.get('[data-cy=chart]').rightclick(15, 40)

Right click a point on a canvas or chart

When the target is a region inside one element, such as a bar in a chart drawn on a <canvas>, there is no child element to select. Pass the coordinates of that spot instead.

// the March bar is 120px from the left and 45px from the top of the chart
cy.get('[data-cy=chart]').rightclick(120, 45)
cy.get('[data-cy=context-menu]').should('contain', 'March')

To see the exact spot Cypress right clicked, click the rightclick command in the Command Log to pin its snapshot. A red dot marks the point.

Options

Control where Cypress scrolls the element before right clicking

Cypress scrolls the element into view before right clicking it. To put the element in a predictable spot, such as clear of a sticky header, pass scrollBehavior. Center the element in the viewport, or set each axis separately with a { block, inline } object.

cy.get('[data-cy=row-42]').rightclick({ scrollBehavior: 'center' })
cy.get('[data-cy=carousel-item]').rightclick({
  scrollBehavior: { block: 'center', inline: 'nearest' },
})

Dismiss what covers an element before right clicking it

When another element covers the one you want to right click, deal with it the way a user would before reaching for { force: true }. Forcing skips the checks that would catch a real bug, such as a banner that blocks users from opening the menu.

cy.get('[data-cy=cookie-banner] [data-cy=accept]').click()
cy.get('[data-cy=file-row]').first().rightclick()

Force a right click regardless of its actionable state

Forcing a right click overrides the actionable checks Cypress applies and fires the events at the element.

cy.get('[data-cy=file-row]').first().rightclick({ force: true })

Forcing does not make a disabled element respond. The browser does not deliver mousedown, contextmenu, or mouseup events to a disabled form control, so your app's context menu handler never runs.

Right click every element that matches a selector

By default, Cypress errors if you try to right click multiple elements. When you pass { multiple: true }, Cypress right clicks each element in turn, gives each right click its own full timeout, and logs each right click to the Command Log.

cy.get('[data-cy=file-row]').rightclick({ multiple: true })

Modifier keys

Right click with key combinations

Pass a modifier key option to hold that key while right clicking, such as altKey for Alt + right click. The options table lists each modifier key option and its aliases.

Ctrl or Cmd right click

Many apps check the control key on Windows and Linux and the command key on macOS. Use Cypress.platform to hold the key the app expects.

const modifier =
  Cypress.platform === 'darwin' ? { metaKey: true } : { ctrlKey: true }

cy.get('[data-cy=file-row]').first().rightclick(modifier)
cy.get('[data-cy=context-menu]').should('contain', 'Open in new window')

Ctrl + click on macOS does not fire a contextmenu event

On macOS, users can open a context menu by holding Control and clicking. .click({ ctrlKey: true }) fires a click event with the control key held, not a contextmenu event. To test the context menu a Ctrl + click opens, use .rightclick().

Shift right click to show more options

Some apps add options to the context menu when the user holds Shift while right clicking.

// execute a SHIFT + right click on the first file
cy.get('[data-cy=file-row]').first().rightclick({
  shiftKey: true,
})
cy.get('[data-cy=context-menu]').should('contain', 'Copy as path')

Notes

Actionability

The element must first reach actionability

.rightclick() is an "action command" that follows all the rules of Actionability.

Events

Events fired by a right click

Cypress first moves the mouse to the element, which fires hover events such as pointerover, mouseover, and mousemove. Then .rightclick() fires these events in order:

1. pointerdown
2. mousedown
3. contextmenu
4. pointerup
5. mouseup

Each event carries button: 2. pointerdown, mousedown, and contextmenu carry buttons: 2, and pointerup and mouseup carry buttons: 0, because the right button has been released, as in a real right click. .rightclick() does not fire a click event.

Focus

Focus is given to the first focusable element

Like .click(), .rightclick() gives focus to the first focusable element at the click coordinates or among its ancestors.

Right click or trigger a contextmenu event

Choose between .rightclick() and .trigger('contextmenu')

Both commands wait for the element to reach an actionable state.

• .rightclick() fires the full sequence of events fired by a right click and gives focus to the element, the way a user's right click does.
• .trigger('contextmenu') fires only the contextmenu event and leaves focus where it was. Use it when you need that single event, or to set event properties that .rightclick() does not expose.

Rules

Requirements

• .rightclick() requires being chained off a command that yields DOM element(s).
• .rightclick() requires a single element unless you pass { multiple: true }.
• .rightclick() cannot be called on a <select> element. Use .select() to change its value.

Assertions

• .rightclick() automatically waits for the element to reach an actionable state.
• .rightclick() itself is not retried. It fires once when the element is actionable. Assertions chained after .rightclick() are retried until they pass or time out. See Only queries are retried.

Timeouts

• .rightclick() can time out waiting for the element to reach an actionable state.
• .rightclick() can time out waiting for assertions you've added to pass.

Command Log

Right click the DOM element

cy.get('.rightclick-action-div').rightclick()

The commands above display in the Command Log as:

When you click rightclick in the Command Log, the console outputs the following:

The Mouse Events table lists the contextmenu event last, after the press and release events. Cypress fires it between mousedown and pointerup, as described in Events fired by a right click.

History

Version	Changes
16.2.1	pointerup and mouseup carry buttons: 0
15.20.0	Option scrollBehavior now accepts a per-axis { block, inline } object and the 'start' and 'end' alignments
6.1.0	Added option scrollBehavior
5.0.0	Added options altKey, ctrlKey, metaKey, and shiftKey
3.5.0	.rightclick() command added

See also

• .click()
• .dblclick()
• .trigger()