click
Click a DOM element.
It is unsafe to
chain further commands that rely on the subject after .click().
Syntax​
.click()
.click(options)
.click(position)
.click(position, options)
.click(x, y)
.click(x, y, options)
Usage​
Correct Usage
cy.get('[data-cy=submit]').click() // Click on button
cy.focused().click() // Click on el with focus
cy.contains('Welcome').click() // Click on first el containing 'Welcome'
Incorrect Usage
cy.click('[data-cy=submit]') // Errors, cannot be chained off 'cy'
cy.window().click() // Errors, 'window' does not yield DOM element
Arguments​
position (String)
The position where the 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 click.
y (Number)
The distance in pixels from the element's top to issue the click.
options (Object)
Pass in an options object to change the default behavior of .click().
| 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. |
log | true | Displays the command in the Command log |
force | false | Forces the action, disables waiting for actionability |
metaKey | false | Activates the meta key (Windows key or command key for Mac). Aliases: commandKey, cmdKey. |
multiple | false | Serially 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 .click() to resolve before timing out |
waitForAnimations | waitForAnimations | Whether to wait for elements to finish animating before executing the command. |
Yields ​
.click()yields the same subject it was given.- It is unsafe
to chain further commands that rely on the subject after
.click().
Examples​
No Args​
Click a link in a nav​
cy.get('[data-cy=nav] a').click()
Assert on the result of a click​
Chaining further commands off the subject of .click() is unsafe, since the
click can re-render or remove the element. Start a new chain from cy and
assert on what the click changed.
cy.get('[data-cy=open-modal]').click()
cy.get('[data-cy=modal]').should('be.visible')
Wait for the request a click sends​
Register a cy.intercept() before the click, then
cy.wait() on its alias so the test continues only after
the request completes.
cy.intercept('POST', '/api/todos').as('createTodo')
cy.get('[data-cy=save]').click()
cy.wait('@createTodo').its('response.statusCode').should('eq', 201)
Click a button that starts out disabled​
.click() retries its
actionability checks,
including the check that the element is not disabled, until the command times
out. You don't need to assert that the button is enabled before clicking it.
This check reads the element's disabled property. A button marked only with
aria-disabled="true" is not disabled to Cypress, so .click() fires on it
right away. For those buttons, assert on the attribute before clicking.
// waits until the submit button is no longer disabled
cy.get('[data-cy=submit]').click()
// a button disabled with aria-disabled instead
cy.get('[data-cy=next]').should('not.have.attr', 'aria-disabled', 'true')
cy.get('[data-cy=next]').click()
Click one element out of several matches​
When a query matches more than one element, narrow it to the one you want
instead of passing { multiple: true }. Use .first(),
.eq(), or cy.contains() with a
selector and text.
cy.get('[data-cy=todo] [data-cy=delete]').first().click()
cy.get('[data-cy=todo]').eq(2).find('[data-cy=delete]').click()
cy.contains('button', 'Submit').click()
Dismiss what covers an element before clicking it​
When another element covers the one you want to 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 checking out.
cy.get('[data-cy=cookie-banner] [data-cy=accept]').click()
cy.get('[data-cy=checkout]').click()
Position​
Specify a corner of the element to click​
Click the top right corner of the button.
cy.get('[data-cy=submit]').click('topRight')
Click outside an element to dismiss it​
Close a dropdown or popover the way a user would, by clicking an empty area of
the page. Cypress clicks whatever element is at the position you choose, so
target an element and position that are empty in your app. Avoid the top left
corner of body, which in many layouts holds a logo or navigation link that
navigates away.
cy.get('[data-cy=menu-toggle]').click()
cy.get('[data-cy=main-content]').click('topRight')
cy.get('[data-cy=menu]').should('not.exist')
Coordinates​
Specify explicit coordinates relative to the top left corner​
The click below is issued inside of the element (15px from the left and 40px from the top).
cy.get('[data-cy=top-banner]').click(15, 40)
Options​
Control where Cypress scrolls the element before clicking​
Cypress scrolls the element into view before clicking it, aligning it to the top
of its scrollable container by default. If a position: fixed or
position: sticky element such as a header then covers it, Cypress
scrolls past the covering element
until the element is clear.
When that isn't enough, or when you want the element in a predictable spot, pass
scrollBehavior. Center the element in the viewport, or set each axis
separately with a { block, inline } object.
cy.get('[data-cy=row-42] button').click({ scrollBehavior: 'center' })
cy.get('[data-cy=carousel-item]').click({
scrollBehavior: { block: 'center', inline: 'nearest' },
})
Force a click regardless of its actionable state​
Forcing a click overrides the actionable checks Cypress applies and fires the events.
cy.get('[data-cy=close]').as('closeBtn')
cy.get('@closeBtn').click({ force: true })
Force a click with position argument​
cy.get('[data-cy=collapse-sidebar]').click('bottomLeft', { force: true })
Force a click with relative coordinates​
cy.get('[data-cy=footer] [data-cy=next]').click(5, 60, { force: true })
Click every element that matches a selector​
By default, Cypress errors if you try to click multiple elements. When you pass
{ multiple: true }, Cypress clicks each element in turn, gives each click its
own full timeout, and logs each click to the
Command Log.
cy.get('[data-cy=expand-section]').click({ multiple: true })
Click with key combinations​
The .click() command may also be fired with key modifiers to simulate
holding key combinations while clicking, such as ALT + click.
You can also use key combinations during .type(). This offers options to hold down keys across multiple commands. See Key Combinations for more information.
The following keys can be combined with .click() through the options.
| Option | Notes |
|---|---|
altKey | Activates the alt key (option key for Mac). Aliases: optionKey. |
ctrlKey | Activates the control key. Aliases: controlKey. |
metaKey | Activates the meta key (Windows key or command key for Mac). Aliases: commandKey, cmdKey. |
shiftKey | Activates the shift key. |
Shift click​
// execute a SHIFT + click on the first file
cy.get('[data-cy=file]').first().click({
shiftKey: true,
})
Ctrl or Cmd click to select several items​
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]').eq(0).click()
cy.get('[data-cy=file]').eq(2).click(modifier)
cy.get('[data-cy=file].selected').should('have.length', 2)
Notes​
Actionability​
The element must first reach actionability​
.click() is an "action command" that follows all the rules of
Actionability.
Focus​
Focus is given to the first focusable element​
For example, clicking a <span> inside of a <button> gives the focus to the
button, since that's what would happen in a real user scenario.
Cypress starts from the element at the click coordinates and walks up its ancestors to find a focusable element. That element can differ from the subject, for example when a descendant is positioned outside of its parent (per the CSS Object Model). If no ancestor is focusable, Cypress blurs the currently focused element instead, which matches real browser behavior.
Cancellation​
Pointerdown or mousedown cancellation prevents focus​
If the pointerdown or mousedown event has its default action prevented
(e.preventDefault()), Cypress does not give the element focus.
When pointerdown is cancelled, Cypress also skips the mousedown and
mouseup events, following the Pointer Events spec. It still sends pointerup
and click.
Rules​
Requirements ​
.click()requires being chained off a command that yields DOM element(s)..click()requires a single element unless you pass{ multiple: true }..click()cannot be called on a<select>element. Use.select()to change its value.
Assertions ​
.click()automatically waits for the element to reach an actionable state..click()itself is not retried. It fires once when the element is actionable. Assertions chained after.click()are retried until they pass or time out. See Only queries are retried.
Timeouts ​
.click()can time out waiting for the element to reach an actionable state..click()can time out waiting for assertions you've added to pass.
Command Log​
Click the button
cy.get('.action-btn').click()
The commands above will display in the Command Log as:
When clicking on click within the command log, the console outputs the
following:
History​
| Version | Changes |
|---|---|
| 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 |
| 3.5.0 | Added sending mouseover, mousemove, mouseout, pointerdown, pointerup, and pointermove during .click() |