{
"doc": {
"id": "app/core-concepts/interacting-with-elements",
"title": "Interacting with Elements",
"description": "Learn how Cypress determines if an element is actionable, how to debug when elements are not actionable, and how to ignore Cypress' actionability checks.",
"section": "app",
"source_path": "/llm/markdown/app/core-concepts/interacting-with-elements.md",
"version": "48b03b5502f7aea1d0454750cce208f775403542",
"updated_at": "2026-05-20T19:00:20.270Z",
"headings": [
{
"id": "app/core-concepts/interacting-with-elements#interacting-with-elements",
"text": "Interacting with Elements",
"level": 1
},
{
"id": "app/core-concepts/interacting-with-elements#what-youll-learn",
"text": "What you'll learn",
"level": 5
},
{
"id": "app/core-concepts/interacting-with-elements#visibility",
"text": "Visibility",
"level": 2
},
{
"id": "app/core-concepts/interacting-with-elements#default-behavior",
"text": "Default Behavior",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#an-element-is-considered-hidden-if",
"text": "An element is considered hidden if:",
"level": 4
},
{
"id": "app/core-concepts/interacting-with-elements#experimental-fast-visibility",
"text": "Experimental Fast Visibility",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#limitations",
"text": "Limitations",
"level": 4
},
{
"id": "app/core-concepts/interacting-with-elements#common-compatibility-issues",
"text": "Common Compatibility Issues",
"level": 4
},
{
"id": "app/core-concepts/interacting-with-elements#actionability",
"text": "Actionability",
"level": 2
},
{
"id": "app/core-concepts/interacting-with-elements#disability",
"text": "Disability",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#detached",
"text": "Detached",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#readonly",
"text": "Readonly",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#animations",
"text": "Animations",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#covering",
"text": "Covering",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#scrolling",
"text": "Scrolling",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#coordinates",
"text": "Coordinates",
"level": 3
},
{
"id": "app/core-concepts/interacting-with-elements#debugging",
"text": "Debugging",
"level": 2
},
{
"id": "app/core-concepts/interacting-with-elements#forcing",
"text": "Forcing",
"level": 2
}
]
},
"chunks": [
{
"id": "app/core-concepts/interacting-with-elements#what-youll-learn",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "What you'll learn",
"heading_level": 5,
"content_markdown": "##### What you'll learn\n\n* How Cypress determines if an element is actionable\n* How to debug when elements are not actionable\n* How to ignore Cypress' actionability checks\n\nLearn how [UI Coverage](/llm/markdown/ui-coverage/get-started/introduction.md) highlights areas where interactive elements have not been tested. Understand coverage gaps, inform your testing strategy, and ship high-quality code with confidence.\n",
"section": "app",
"anchors": [
"what-youll-learn"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 73
},
{
"id": "app/core-concepts/interacting-with-elements#visibility",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Visibility",
"heading_level": 2,
"content_markdown": "## Visibility\n\n### Default Behavior\n\nCypress checks a lot of things to determine an element's visibility. The following calculations factor in CSS translations and transforms.\n\n#### An element is considered hidden if:\n\n* Its `width` or `height` is `0`.\n* Its CSS property (or ancestors) is `visibility: hidden`.\n* Its CSS property (or ancestors) is `display: none`.\n* Its CSS property is `position: fixed` and it's offscreen or covered up.\n* Any of its ancestors **hides overflow**\\*\n * AND that ancestor has a `width` or `height` of `0`\n * AND an element between that ancestor and the element is `position: absolute`\n* Any of its ancestors **hides overflow**\\*\n * AND that ancestor or an ancestor between it and that ancestor is its offset parent\n * AND it is positioned outside that ancestor's bounds\n* Any of its ancestors **hides overflow**\\*\n * AND the element is `position: relative`\n * AND it is positioned outside that ancestor's bounds\n\n\\***hides overflow** means it has `overflow: hidden`, `overflow-x: hidden`, `overflow-y: hidden`, `overflow: scroll`, or `overflow: auto`\n\n**Opacity**\n\nElements where the CSS property (or ancestors) is `opacity: 0` are considered hidden when [asserting on the element's visibility directly](/llm/markdown/app/references/assertions.md#Visibility).\n\nHowever elements where the CSS property (or ancestors) is `opacity: 0` are considered actionable and any commands used to interact with the hidden element will perform the action.\n\n### Experimental Fast Visibility\n\nYou can enable a faster visibility detection algorithm using [`experimentalFastVisibility`](/llm/markdown/app/references/experiments.md#Experimental-Fast-Visibility).\n\nThis algorithm is more accurate and less resource-intensive than the default behavior, but it has slightly different semantics.\n\nWhen `experimentalFastVisibility` is enabled, an element is considered hidden if:\n\n* Its `width` or `height` is `0`\n* Its computed CSS properties prevent it from being clicked on or visible:\n * `visibility: hidden`\n * `opacity: 0`\n * `display: none`\n * `pointer-events: none`\n* It is positioned fully outside of the browser viewport\n * _this is a known compatibility issue with the legacy visibility algorithm_ when it comes to asserting visibility. It will be addressed during the course of this experiment.\n* It is fully covered or clipped by another element\n\nKeep up-to-date with the progress of this experiment in the [Cypress repository](https://github.com/cypress-io/cypress/issues/33043).\n\n#### Limitations\n\nExperimental fast visibility is an experimental feature that is still under development. It uses different semantics from the legacy visibility algorithm, and does not yet fully support all testing scenarios.\n\n* Shadow DOM is not yet supported. Tests that interact with Shadow DOM elements may fail or behave incorrectly.\n* Elements outside of the browser's viewport are not yet correctly identified as visible. Scroll elements into view before testing.\n\n#### Common Compatibility Issues\n\nWhen enabling fast visibility, you may encounter differences in how elements are detected. The fast algorithm provides more geometrically accurate visibility detection, which may reveal that elements previously considered visible are actually hidden.\n\n**Elements Outside Viewport**\n\nElements positioned outside the viewport are now correctly identified as hidden. Scroll elements into view before testing:\n\n```\n// Beforecy.get('.off-screen-element').should('be.visible')// Aftercy.get('.off-screen-element').scrollIntoView().should('be.visible')\n```\n\n**Covered Elements**\n\nElements covered by other elements are now correctly identified as hidden. Test the covering element or the user interaction that reveals the covered element:\n\n```\n// Test the user action that reveals the elementcy.get('.toggle-button').click()cy.get('.covered-element').should('be.visible')\n```\n\n**Zero-Dimension Containers**\n\nContainers with zero dimensions are now correctly identified as hidden. Test the child element instead of the container:\n\n```\n// Test the child element that should be visiblecy.get('.zero-dimension-container .child-element').should('be.visible')\n```\n\n**Elements with `pointer-events: none`**\n\nElements with `pointer-events: none` may be detected as hidden when they are visible. Do not assert visibility on elements with `pointer-events: none`, as they cannot be interacted with.\n\n**Important:** If tests fail after enabling fast visibility, the fast algorithm is likely correct and tests should be updated to match the actual behavior.\n",
"section": "app",
"anchors": [
"visibility"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 817
},
{
"id": "app/core-concepts/interacting-with-elements#default-behavior",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Default Behavior",
"heading_level": 3,
"content_markdown": "### Default Behavior\n\nCypress checks a lot of things to determine an element's visibility. The following calculations factor in CSS translations and transforms.\n\n#### An element is considered hidden if:\n\n* Its `width` or `height` is `0`.\n* Its CSS property (or ancestors) is `visibility: hidden`.\n* Its CSS property (or ancestors) is `display: none`.\n* Its CSS property is `position: fixed` and it's offscreen or covered up.\n* Any of its ancestors **hides overflow**\\*\n * AND that ancestor has a `width` or `height` of `0`\n * AND an element between that ancestor and the element is `position: absolute`\n* Any of its ancestors **hides overflow**\\*\n * AND that ancestor or an ancestor between it and that ancestor is its offset parent\n * AND it is positioned outside that ancestor's bounds\n* Any of its ancestors **hides overflow**\\*\n * AND the element is `position: relative`\n * AND it is positioned outside that ancestor's bounds\n\n\\***hides overflow** means it has `overflow: hidden`, `overflow-x: hidden`, `overflow-y: hidden`, `overflow: scroll`, or `overflow: auto`\n\n**Opacity**\n\nElements where the CSS property (or ancestors) is `opacity: 0` are considered hidden when [asserting on the element's visibility directly](/llm/markdown/app/references/assertions.md#Visibility).\n\nHowever elements where the CSS property (or ancestors) is `opacity: 0` are considered actionable and any commands used to interact with the hidden element will perform the action.\n",
"section": "app",
"anchors": [
"default-behavior"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 292
},
{
"id": "app/core-concepts/interacting-with-elements#an-element-is-considered-hidden-if",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "An element is considered hidden if:",
"heading_level": 4,
"content_markdown": "#### An element is considered hidden if:\n\n* Its `width` or `height` is `0`.\n* Its CSS property (or ancestors) is `visibility: hidden`.\n* Its CSS property (or ancestors) is `display: none`.\n* Its CSS property is `position: fixed` and it's offscreen or covered up.\n* Any of its ancestors **hides overflow**\\*\n * AND that ancestor has a `width` or `height` of `0`\n * AND an element between that ancestor and the element is `position: absolute`\n* Any of its ancestors **hides overflow**\\*\n * AND that ancestor or an ancestor between it and that ancestor is its offset parent\n * AND it is positioned outside that ancestor's bounds\n* Any of its ancestors **hides overflow**\\*\n * AND the element is `position: relative`\n * AND it is positioned outside that ancestor's bounds\n\n\\***hides overflow** means it has `overflow: hidden`, `overflow-x: hidden`, `overflow-y: hidden`, `overflow: scroll`, or `overflow: auto`\n\n**Opacity**\n\nElements where the CSS property (or ancestors) is `opacity: 0` are considered hidden when [asserting on the element's visibility directly](/llm/markdown/app/references/assertions.md#Visibility).\n\nHowever elements where the CSS property (or ancestors) is `opacity: 0` are considered actionable and any commands used to interact with the hidden element will perform the action.\n",
"section": "app",
"anchors": [
"an-element-is-considered-hidden-if"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 261
},
{
"id": "app/core-concepts/interacting-with-elements#experimental-fast-visibility",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Experimental Fast Visibility",
"heading_level": 3,
"content_markdown": "### Experimental Fast Visibility\n\nYou can enable a faster visibility detection algorithm using [`experimentalFastVisibility`](/llm/markdown/app/references/experiments.md#Experimental-Fast-Visibility).\n\nThis algorithm is more accurate and less resource-intensive than the default behavior, but it has slightly different semantics.\n\nWhen `experimentalFastVisibility` is enabled, an element is considered hidden if:\n\n* Its `width` or `height` is `0`\n* Its computed CSS properties prevent it from being clicked on or visible:\n * `visibility: hidden`\n * `opacity: 0`\n * `display: none`\n * `pointer-events: none`\n* It is positioned fully outside of the browser viewport\n * _this is a known compatibility issue with the legacy visibility algorithm_ when it comes to asserting visibility. It will be addressed during the course of this experiment.\n* It is fully covered or clipped by another element\n\nKeep up-to-date with the progress of this experiment in the [Cypress repository](https://github.com/cypress-io/cypress/issues/33043).\n\n#### Limitations\n\nExperimental fast visibility is an experimental feature that is still under development. It uses different semantics from the legacy visibility algorithm, and does not yet fully support all testing scenarios.\n\n* Shadow DOM is not yet supported. Tests that interact with Shadow DOM elements may fail or behave incorrectly.\n* Elements outside of the browser's viewport are not yet correctly identified as visible. Scroll elements into view before testing.\n\n#### Common Compatibility Issues\n\nWhen enabling fast visibility, you may encounter differences in how elements are detected. The fast algorithm provides more geometrically accurate visibility detection, which may reveal that elements previously considered visible are actually hidden.\n\n**Elements Outside Viewport**\n\nElements positioned outside the viewport are now correctly identified as hidden. Scroll elements into view before testing:\n\n```\n// Beforecy.get('.off-screen-element').should('be.visible')// Aftercy.get('.off-screen-element').scrollIntoView().should('be.visible')\n```\n\n**Covered Elements**\n\nElements covered by other elements are now correctly identified as hidden. Test the covering element or the user interaction that reveals the covered element:\n\n```\n// Test the user action that reveals the elementcy.get('.toggle-button').click()cy.get('.covered-element').should('be.visible')\n```\n\n**Zero-Dimension Containers**\n\nContainers with zero dimensions are now correctly identified as hidden. Test the child element instead of the container:\n\n```\n// Test the child element that should be visiblecy.get('.zero-dimension-container .child-element').should('be.visible')\n```\n\n**Elements with `pointer-events: none`**\n\nElements with `pointer-events: none` may be detected as hidden when they are visible. Do not assert visibility on elements with `pointer-events: none`, as they cannot be interacted with.\n\n**Important:** If tests fail after enabling fast visibility, the fast algorithm is likely correct and tests should be updated to match the actual behavior.\n",
"section": "app",
"anchors": [
"experimental-fast-visibility"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 523
},
{
"id": "app/core-concepts/interacting-with-elements#limitations",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Limitations",
"heading_level": 4,
"content_markdown": "#### Limitations\n\nExperimental fast visibility is an experimental feature that is still under development. It uses different semantics from the legacy visibility algorithm, and does not yet fully support all testing scenarios.\n\n* Shadow DOM is not yet supported. Tests that interact with Shadow DOM elements may fail or behave incorrectly.\n* Elements outside of the browser's viewport are not yet correctly identified as visible. Scroll elements into view before testing.\n",
"section": "app",
"anchors": [
"limitations"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 95
},
{
"id": "app/core-concepts/interacting-with-elements#common-compatibility-issues",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Common Compatibility Issues",
"heading_level": 4,
"content_markdown": "#### Common Compatibility Issues\n\nWhen enabling fast visibility, you may encounter differences in how elements are detected. The fast algorithm provides more geometrically accurate visibility detection, which may reveal that elements previously considered visible are actually hidden.\n\n**Elements Outside Viewport**\n\nElements positioned outside the viewport are now correctly identified as hidden. Scroll elements into view before testing:\n\n```\n// Beforecy.get('.off-screen-element').should('be.visible')// Aftercy.get('.off-screen-element').scrollIntoView().should('be.visible')\n```\n\n**Covered Elements**\n\nElements covered by other elements are now correctly identified as hidden. Test the covering element or the user interaction that reveals the covered element:\n\n```\n// Test the user action that reveals the elementcy.get('.toggle-button').click()cy.get('.covered-element').should('be.visible')\n```\n\n**Zero-Dimension Containers**\n\nContainers with zero dimensions are now correctly identified as hidden. Test the child element instead of the container:\n\n```\n// Test the child element that should be visiblecy.get('.zero-dimension-container .child-element').should('be.visible')\n```\n\n**Elements with `pointer-events: none`**\n\nElements with `pointer-events: none` may be detected as hidden when they are visible. Do not assert visibility on elements with `pointer-events: none`, as they cannot be interacted with.\n\n**Important:** If tests fail after enabling fast visibility, the fast algorithm is likely correct and tests should be updated to match the actual behavior.\n",
"section": "app",
"anchors": [
"common-compatibility-issues"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 249
},
{
"id": "app/core-concepts/interacting-with-elements#actionability",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Actionability",
"heading_level": 2,
"content_markdown": "## Actionability\n\nSome commands in Cypress are for interacting with the DOM such as:\n\n* [`.click()`](/llm/markdown/api/commands/click.md)\n* [`.dblclick()`](/llm/markdown/api/commands/dblclick.md)\n* [`.rightclick()`](/llm/markdown/api/commands/rightclick.md)\n* [`.type()`](/llm/markdown/api/commands/type.md)\n* [`.clear()`](/llm/markdown/api/commands/clear.md)\n* [`.check()`](/llm/markdown/api/commands/check.md)\n* [`.uncheck()`](/llm/markdown/api/commands/uncheck.md)\n* [`.select()`](/llm/markdown/api/commands/select.md)\n* [`.trigger()`](/llm/markdown/api/commands/trigger.md)\n* [`.selectFile()`](/llm/markdown/api/commands/selectfile.md)\n\nWe call these \"action commands.\" These actions simulate a user interacting with your application. Under the hood, Cypress fires the events a browser would fire thus causing your application's event bindings to fire.\n\nPrior to issuing any of the commands, we check the current state of the DOM and take some actions to ensure the DOM element is \"ready\" to receive the action.\n\nCypress will watch the DOM - re-running the queries that yielded the current subject - until an element passes all of these checks for the duration of the [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) (described in depth in the [Implicit Assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Implicit-Assertions) core concept guide).\n\n**_Checks and Actions Performed_**\n\n* [Scroll the element into view.](#Scrolling)\n* [Ensure the element is not hidden.](#Visibility)\n* [Ensure the element is not disabled.](#Disability)\n* [Ensure the element is not detached.](#Detached)\n* [Ensure the element is not readonly.](#Readonly)\n* [Ensure the element is not animating.](#Animations)\n* [Ensure the element is not covered.](#Covering)\n* [Scroll the page if still covered by an element with fixed position.](#Scrolling)\n* [Fire the event at the desired coordinates.](#Coordinates)\n\nWhenever Cypress cannot interact with an element, it could fail at any of the above steps. You will usually get an error explaining why the element was not found to be actionable.\n\n### Disability\n\nCypress checks whether the `disabled` property is `true` on a [form control](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled) element, such as `button` or `input`. Setting a `disabled` attribute on other elements will have no effect on a user's ability to interact with them, and won't impact Cypress actionability checks.\n\n### Detached\n\nCypress checks whether an element you are making assertions on is still within the `document` of the application under test.\n\nWhen many applications rerender the DOM, they actually remove the DOM element and insert a new DOM element in its place with the newly change attributes. This is why it's important not to chain _action commands_ together - cypress can re-run queries to locate the fresh element, but it will [never re-run commands](/llm/markdown/app/core-concepts/retry-ability.md).\n\n### Readonly\n\nCypress checks whether an element's `readonly` property is set during [.type()](/llm/markdown/api/commands/type.md).\n\n### Animations\n\nCypress will automatically determine if an element is animating and wait until it stops.\n\nTo calculate whether an element is animating we take a sample of the last positions it was at and calculate the element's slope. You might remember this from 8th grade algebra. 😉\n\nTo calculate whether an element is animating we check the current and previous positions of the element itself. If the distance exceeds the [`animationDistanceThreshold`](/llm/markdown/app/references/configuration.md#Actionability), then we consider the element to be animating.\n\nWhen coming up with this value, we did a few experiments to find a speed that \"feels\" too fast for a user to interact with. You can always [increase or decrease this threshold](/llm/markdown/app/references/configuration.md#Actionability).\n\nYou can also turn off our checks for animations with the configuration option [`waitForAnimations`](/llm/markdown/app/references/configuration.md#Actionability).\n\n### Covering\n\nWe also ensure that the element we're attempting to interact with isn't covered by a parent element.\n\nFor instance, an element could pass all of the previous checks, but a giant dialog could be covering the entire screen making interacting with the element impossible for any real user.\n\nWhen checking to see if the element is covered we always check its center coordinates.\n\nIf a _child_ of the element is covering it - that's okay. In fact we'll automatically issue the events we fire to that child.\n\nImagine you have a button:\n\n```\n\n```\n\nOftentimes either the `` or `` element is covering the exact coordinate we're attempting to interact with. In those cases, the event fires on the child. We even note this for you in the [Command Log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log).\n\n### Scrolling\n\nBefore interacting with an element, we will _always_ scroll it into view (including any of its parent containers). Even if the element was visible without scrolling, we perform the scrolling algorithm in order to reproduce the same behavior every time the command is run.\n\nThis scrolling logic only applies to [commands that are actionable above](#Actionability). **We do not scroll elements** into view when using DOM commands such as [cy.get()](/llm/markdown/api/commands/get.md) or [.find()](/llm/markdown/api/commands/find.md).\n\nBy default, the scrolling algorithm works by scrolling the top, leftmost point of the element we issued the command on to the top, leftmost scrollable point of its scrollable container.\n\nAfter scrolling the element, if we determine that it is still being covered up, we will continue to scroll and \"nudge\" the page until it becomes visible. This most frequently happens when you have `position: fixed` or `position: sticky` navigation elements which are fixed to the top of the page.\n\nOur algorithm _should_ always be able to scroll until the element is not covered.\n\nTo change the position in the viewport to where we scroll an element, you can use the [`scrollBehavior`](/llm/markdown/app/references/configuration.md#Actionability) configuration option. This can be useful if the element is covered up when aligned to the top of the viewport, or if you just prefer the element to be centered during scrolling of action commands. Accepted values are `'center'`, `'top'`, `'bottom'`, `'nearest'`, and `false`, with `false` disabling scrolling altogether.\n\n### Coordinates\n\nAfter we verify the element is actionable, Cypress will then fire all of the appropriate events and corresponding default actions. Usually these events' coordinates are fired at the center of the element, but most commands enable you to change the position it's fired to.\n\n```\ncy.get('button').click({ position: 'topLeft' })\n```\n\nThe coordinates we fired the event at will generally be available when clicking the command in the [Command Log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log).\n\nAdditionally we'll display a red \"hitbox\" - which is a dot indicating the coordinates of the event.\n",
"section": "app",
"anchors": [
"actionability"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 1280
},
{
"id": "app/core-concepts/interacting-with-elements#disability",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Disability",
"heading_level": 3,
"content_markdown": "### Disability\n\nCypress checks whether the `disabled` property is `true` on a [form control](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled) element, such as `button` or `input`. Setting a `disabled` attribute on other elements will have no effect on a user's ability to interact with them, and won't impact Cypress actionability checks.\n",
"section": "app",
"anchors": [
"disability"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 60
},
{
"id": "app/core-concepts/interacting-with-elements#detached",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Detached",
"heading_level": 3,
"content_markdown": "### Detached\n\nCypress checks whether an element you are making assertions on is still within the `document` of the application under test.\n\nWhen many applications rerender the DOM, they actually remove the DOM element and insert a new DOM element in its place with the newly change attributes. This is why it's important not to chain _action commands_ together - cypress can re-run queries to locate the fresh element, but it will [never re-run commands](/llm/markdown/app/core-concepts/retry-ability.md).\n",
"section": "app",
"anchors": [
"detached"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 100
},
{
"id": "app/core-concepts/interacting-with-elements#animations",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Animations",
"heading_level": 3,
"content_markdown": "### Animations\n\nCypress will automatically determine if an element is animating and wait until it stops.\n\nTo calculate whether an element is animating we take a sample of the last positions it was at and calculate the element's slope. You might remember this from 8th grade algebra. 😉\n\nTo calculate whether an element is animating we check the current and previous positions of the element itself. If the distance exceeds the [`animationDistanceThreshold`](/llm/markdown/app/references/configuration.md#Actionability), then we consider the element to be animating.\n\nWhen coming up with this value, we did a few experiments to find a speed that \"feels\" too fast for a user to interact with. You can always [increase or decrease this threshold](/llm/markdown/app/references/configuration.md#Actionability).\n\nYou can also turn off our checks for animations with the configuration option [`waitForAnimations`](/llm/markdown/app/references/configuration.md#Actionability).\n",
"section": "app",
"anchors": [
"animations"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 169
},
{
"id": "app/core-concepts/interacting-with-elements#covering",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Covering",
"heading_level": 3,
"content_markdown": "### Covering\n\nWe also ensure that the element we're attempting to interact with isn't covered by a parent element.\n\nFor instance, an element could pass all of the previous checks, but a giant dialog could be covering the entire screen making interacting with the element impossible for any real user.\n\nWhen checking to see if the element is covered we always check its center coordinates.\n\nIf a _child_ of the element is covering it - that's okay. In fact we'll automatically issue the events we fire to that child.\n\nImagine you have a button:\n\n```\n\n```\n\nOftentimes either the `` or `` element is covering the exact coordinate we're attempting to interact with. In those cases, the event fires on the child. We even note this for you in the [Command Log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log).\n",
"section": "app",
"anchors": [
"covering"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 183
},
{
"id": "app/core-concepts/interacting-with-elements#scrolling",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Scrolling",
"heading_level": 3,
"content_markdown": "### Scrolling\n\nBefore interacting with an element, we will _always_ scroll it into view (including any of its parent containers). Even if the element was visible without scrolling, we perform the scrolling algorithm in order to reproduce the same behavior every time the command is run.\n\nThis scrolling logic only applies to [commands that are actionable above](#Actionability). **We do not scroll elements** into view when using DOM commands such as [cy.get()](/llm/markdown/api/commands/get.md) or [.find()](/llm/markdown/api/commands/find.md).\n\nBy default, the scrolling algorithm works by scrolling the top, leftmost point of the element we issued the command on to the top, leftmost scrollable point of its scrollable container.\n\nAfter scrolling the element, if we determine that it is still being covered up, we will continue to scroll and \"nudge\" the page until it becomes visible. This most frequently happens when you have `position: fixed` or `position: sticky` navigation elements which are fixed to the top of the page.\n\nOur algorithm _should_ always be able to scroll until the element is not covered.\n\nTo change the position in the viewport to where we scroll an element, you can use the [`scrollBehavior`](/llm/markdown/app/references/configuration.md#Actionability) configuration option. This can be useful if the element is covered up when aligned to the top of the viewport, or if you just prefer the element to be centered during scrolling of action commands. Accepted values are `'center'`, `'top'`, `'bottom'`, `'nearest'`, and `false`, with `false` disabling scrolling altogether.\n",
"section": "app",
"anchors": [
"scrolling"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 312
},
{
"id": "app/core-concepts/interacting-with-elements#coordinates",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Coordinates",
"heading_level": 3,
"content_markdown": "### Coordinates\n\nAfter we verify the element is actionable, Cypress will then fire all of the appropriate events and corresponding default actions. Usually these events' coordinates are fired at the center of the element, but most commands enable you to change the position it's fired to.\n\n```\ncy.get('button').click({ position: 'topLeft' })\n```\n\nThe coordinates we fired the event at will generally be available when clicking the command in the [Command Log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log).\n\nAdditionally we'll display a red \"hitbox\" - which is a dot indicating the coordinates of the event.\n",
"section": "app",
"anchors": [
"coordinates"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 117
},
{
"id": "app/core-concepts/interacting-with-elements#debugging",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Debugging",
"heading_level": 2,
"content_markdown": "## Debugging\n\nIt can be difficult to debug problems when elements are not considered actionable by Cypress.\n\nAlthough you _should_ see a nice error message, nothing beats visually inspecting and poking at the DOM yourself to understand the reason why.\n\nWhen you use the [Command Log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) to hover over a command, you'll notice that we will always scroll the element the command was applied to into view. Please note that this is _NOT_ using the same algorithms that we described above.\n\nIn fact we only ever scroll elements into view when actionable commands are running using the above algorithms. We _do not_ scroll elements into view on regular DOM queries like [`cy.get()`](/llm/markdown/api/commands/get.md) or [`.find()`](/llm/markdown/api/commands/find.md).\n\nThe reason we scroll an element into view when hovering over a snapshot is to help you to see which element(s) were found by that corresponding command. It's a purely visual feature and does not necessarily reflect what your page looked like when the command ran.\n\nIn other words, you cannot get a correct visual representation of what Cypress \"saw\" when looking at a previous snapshot.\n\nThe only way for you to \"see\" and debug why Cypress thought an element was not visible is to use a `debugger` statement.\n\nWe recommend placing `debugger` or using the [`.debug()`](/llm/markdown/api/commands/debug.md) command directly BEFORE the action.\n\nMake sure your Developer Tools are open and you can get pretty close to \"seeing\" the calculations Cypress is performing.\n\nYou can also [bind to Events](/llm/markdown/api/cypress-api/catalog-of-events.md) that Cypress fires as it's working with your element. Using a debugger with these events will give you a much lower level view into how Cypress works.\n\n```\n// break on a debugger before the action commandcy.get('button').debug().click()\n```\n",
"section": "app",
"anchors": [
"debugging"
],
"path": "/llm/json/chunked/app/core-concepts/interacting-with-elements.json",
"token_estimate": 373
},
{
"id": "app/core-concepts/interacting-with-elements#forcing",
"doc_id": "app/core-concepts/interacting-with-elements",
"heading": "Forcing",
"heading_level": 2,
"content_markdown": "## Forcing\n\nWhile the above checks are super helpful at finding situations that would prevent your users from interacting with elements - sometimes they can get in the way!\n\nSometimes it's not worth trying to \"act like a user\" to get a robot to do the exact steps a user would to interact with an element.\n\nImagine you have a nested navigation structure where the user must hover over and move the mouse in a very specific pattern to reach the desired link.\n\nIs this worth trying to replicate when you're testing?\n\nMaybe not! For these scenarios, we give you an escape hatch to bypass all of the checks above and force events to happen!\n\nYou can pass `{ force: true }` to most action commands.\n\n```\n// force the click and all subsequent events// to fire even if this element isn't considered 'actionable'cy.get('button').click({ force: true })\n```\n\n**What's the difference?**\n\nWhen you force an event to happen we will:\n\n* Continue to perform all default actions\n* Forcibly fire the event at the element\n\nWe will NOT perform these:\n\n* Scroll the element into view\n* Ensure it is visible\n* Ensure it is not disabled\n* Ensure it is not detached\n* Ensure it is not readonly\n* Ensure it is not animating\n* Ensure it is not covered\n* Fire the event at a descendent\n\nIn summary, `{ force: true }` skips the checks, and it will always fire the event at the desired element.\n\n**force `.select()` disabled options**\n\nPassing `{ force: true }` to [.select()](/llm/markdown/api/commands/select.md) will not override the actionability checks for selecting a disabled `