perf: experimental "fast mode" for visibility checks #32801

cacieprins · 2025-10-22T15:26:24Z

Closes Experimental "Fast" Visibility #33044

Additional details

This is a DRAFT proposal

In order to verify performance improvements, this adds a "stress test" e2e test to the driver that simulates interacting with extremely large virtual scrolling lists. This test should probably not be run with "legacy" visibility, as it immediately causes the browser to eat up all available memory and crash. This fixture works perfectly fine outside of Cypress.

This introduces an experimentalFastVisibility option, that switches our visibility detections to an alternative algorithm. This algorithm has some caveats, but it is much faster than the current visibility algorithm.

Cypress uses this visibility algorithm not just for visibility assertions, but also for every interaction that requires "interactability." It's memory intensive and can cause unnecessary layout thrashing due to repeated access of CSS properties that require layout recaulcation.

The "fast" visibility algorithm:

Assumes body and html are always visible; this is in line with current visibility behavior
Uses the built-in checkVisibility method as first pass, with all options enabled. The following states are considered hidden by this method:

The element does not have an associated box
The element is not being rendered because it or one of its ancestors has set content-visibility to hidden
It has an opacity of 0
The value of its visibility property makes it invisible
content-visibility CSS value is auto, and its derived value prevents the element from being rendered

If the element is an <option> or <optgroup>, it defers to the visibility of the parent <select> element. If there is no parent <select> element (an invalid DOM tree state), the element is considered hidden.
If the element is still considered visible, it performs a more comprehensive check with an adaptive point sampling algorithm

The point sampling algorithm:

Implements a visibleAtPoint check, which uses document.elementFromPoint to determine which element is at the top of the render context at that point. If the element at that point is the subject element or a child of the subject element, the subject element is considered visible at that point.
From the bounding rectangle of the subject element, it checks the four corners and center. If any of these points are visible, the subject element is considered visible.
If none of these points are visible, it divides the bounding rectangle in to four sub-rectangles, and performs the same sampling on them.
The sampling algorithm returns true if any part of the element is visible, but for performance constraints it will only subdivide to a limited depth, and will stop subdividing if the sampling rectangles fall below 1px in both dimensions.

Benefits over the legacy algorithm:

Constant-time in the best case, and bounded exponential in the worst case (point sampling on a fully hidden element)
Detects when an element is fully covered by positioned elements outside its ancestor tree
Can be tweaked to provide access to threshold-based visibility
Could be extended to require a minimum visible size for an element to be considered actionable tap events, to test conformation with UX guidelines regarding the size of touch targets
Does not crash when running the virtual scroll stress tests

Caveats:

Elements that are outside the bounds of the browser viewport will always be considered hidden with this algorithm
Elements with pointer-events:none either explicit or inherited will always be considered hidden
<option> elements that are not a direct child of <select> or <optgroup> elements are not considered visible
<optgroup> elements that are not a direct child of <select> or <optgroup> elements are not considered visible
Certain other edge cases that are considered hidden to this algorithm may be visible to the user, especially when it comes to elements that have a 0 height or width and have visible children. In these cases, it may be better to assert visibility on the visible children rather than the containing element.
Shadow dom support is unknown at this time
Some of the current visibility.cy.ts tests fail because the subject element is either off-screen, or covered by an absolute/fixed element that is not an ancestor.
If even 1px of the subject element is visible, it will be considered visible. Potential consideration: configurable threshold?

Future performance improvements:

Memoize elementFromPoint calls
delete old records from memoization maps to reduce memory footprint
Use requestAnimationFrame to measure the BoundingClientRect of the subject element; this is difficult due to how the visibility & interactability checks are currently wired through jquery selectors, which prevents this method from being async

Steps to test

How has the user experience changed?

PR Tasks

Have tests been added/updated?
Has a PR for user-facing changes been opened in cypress-documentation? Experimental fast visibility cypress-documentation#6337
Have API changes been updated in the type definitions?

cypress · 2025-10-23T17:48:51Z

cypress Run #67940

Run Properties: Passed #67940 • b5ba8885ef: add i18n copy for experimentalFastVisibility, documented as a step to take in cf...

Project	`cypress`
Branch Review	`visibility-performance`
Run status	`Passed #67940`
Run duration	`17m 34s`
Commit	`b5ba8885ef: add i18n copy for experimentalFastVisibility, documented as a step to take in cf...`
Committer	`Cacie Prins`
View all properties for this run ↗︎

Test results
Failures	`0`
Flaky	`2`
Pending	`10`
Skipped	`0`
Passing	`640`
View all changes introduced in this branch ↗︎

UI Coverage `0%`
Untested elements	`4`
Tested elements	`0`

Accessibility `100%`
Failed rules	`0 critical` `0 serious` `0 moderate` `0 minor`
Failed elements	`0`

…resolving circular dependencies

jennifer-shehane · 2025-12-10T18:20:10Z

cli/CHANGELOG.md

+**Performance:**
+
+- Introduced a new `experimentalFastVisibility` experiment. Enabling this experiment changes how Cypress performs visibility checks and assertions. Read more about [experimental fast visibility](https://on.cypress.io/experiments/#experimental-fast-visibility). Addresses [#33044](https://github.com/cypress-io/cypress/issues/33044). Addressed in [#32801](https://github.com/cypress-io/cypress/pull/32801).


There used to be some guidance on this, that I cannot find atm. But we put Performance at the top, above Features (since they usually impact generally everyone).

https://github.com/cypress-io/cypress/blob/develop/guides/writing-the-cypress-changelog.md#writing-guidelines (if we remember to do it correctly 😅 )

jennifer-shehane

@cacieprins Some notes to possibly address

jennifer-shehane · 2025-12-10T18:35:24Z

packages/driver/src/dom/visibility/fastIsHidden.ts

+  if (isBody(subject) || isHTML(subject)) {
+    return false
+  }


Seems this could be moved out of both functions and ad the top of the isHidden definition. Not a big deal though

jennifer-shehane · 2025-12-10T18:46:09Z

packages/driver/cypress/e2e/dom/visibility.cy.ts

+            // Chromium consider these elements visible, but Firefox considers them hidden. Should defer to browser
+            // behavior, maybe?


What was the decision here. Comment makes it sound undecided

I think the decision should be to defer to the browser behavior based on what we discussed. Based on the logic it looks like that is what is happening and the comment just needs to be cleaned up?

jennifer-shehane · 2025-12-10T18:47:11Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

@@ -0,0 +1,330 @@
+# Fast Visibility Algorithm Migration Guide
+
+_(note: this file or content similar to it will be added to cy docs, when language / details are finalized)_


Can remove this note

jennifer-shehane · 2025-12-10T18:48:07Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+- **Significantly faster** visibility calculations for complex DOM structures
+- **Reduced CPU usage** during test execution


I might mention here that one would get benefit even if they are not explicitly doing a lot of 'visible' assertions.

jennifer-shehane · 2025-12-10T18:49:12Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+module.exports = {
+  e2e: {
+    experimentalFastVisibility: true
+  }
+}


Is this only available in e2e? I think it's a global setting right?

jennifer-shehane · 2025-12-10T18:49:48Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+Run your existing test suite to identify any failures:
+
+```bash
+npm run test


Suggested change

npm run test

npm run cypress run

wouldn't this be npx cypress run @jennifer-shehane ?

jennifer-shehane · 2025-12-10T18:50:54Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+This allows you to gradually migrate specs while keeping failing ones working.
+
+### Step 5: Fix Tests with Visibility-Related Failures
+For specs that fail due to visibility algorithm differences, update the test expectations to match the correct behavior (see solutions below).


I might mention: correct behavior = visually look at it and see if it is visible or not!

jennifer-shehane · 2025-12-10T18:53:06Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+### Issue 7: Shadow DOM incompatibilities
+
+**Problem:**: Elements inside shadow DOMs may not be detected properly as visible or hidden.
+
+**Solution:**: Test shadow dom components in isolation with component testing, and only test if the public interface of the shadow dom component is visible. You wouldn't assert on the visibility of the browser's default video play controls by querying its shadow dom: you would assert on the properties of the video element itself.


What is the result of passing shadow dom in? Will it give false results of visible or hidden? Can we not error in some way so people don't do this? (Determining if something is shadow dom is not exactly the most performant either probably, so I suspect not)

from my testing, I don't think it will work at all, so if you assert something isn't visible it will always be true and if you assert something is visible it will always be false. Is that correct, @cacieprins ?

jennifer-shehane · 2025-12-10T18:53:24Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+  e2e: {
+    experimentalFastVisibility: false // Disable fast visibility
+  }


again specifies as e2e

jennifer-shehane · 2025-12-10T18:54:32Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+- **Some compatibility differences exist** - when tests fail, the fast algorithm is likely correct and tests should be updated
+- **Performance benefits are significant** - especially for applications with many DOM elements or complex layouts
+
+By following this migration guide, you can resolve compatibility issues and benefit from faster, more accurate visibility detection while understanding the current limitations.


I would have expected the force: true option to be mentioned in here at some point. I don't like it's use myself, but a lot of people lean back on using it.

jennifer-shehane

Need to add the descriptions for the App UI in Settings.

… take in cfg/options.ts

AtofStryker · 2025-12-11T22:37:03Z

cli/CHANGELOG.md

+**Performance:**
+
+- Introduced a new `experimentalFastVisibility` experiment. Enabling this experiment changes how Cypress performs visibility checks and assertions. Read more about [experimental fast visibility](https://on.cypress.io/experiments/#experimental-fast-visibility). Addresses [#33044](https://github.com/cypress-io/cypress/issues/33044). Addressed in [#32801](https://github.com/cypress-io/cypress/pull/32801).


https://github.com/cypress-io/cypress/blob/develop/guides/writing-the-cypress-changelog.md#writing-guidelines (if we remember to do it correctly 😅 )

AtofStryker · 2025-12-11T22:45:53Z

packages/driver/cypress/e2e/dom/visibility.cy.ts

+            // Chromium consider these elements visible, but Firefox considers them hidden. Should defer to browser
+            // behavior, maybe?


I think the decision should be to defer to the browser behavior based on what we discussed. Based on the logic it looks like that is what is happening and the comment just needs to be cleaned up?

AtofStryker · 2025-12-11T22:46:42Z

packages/driver/cypress/e2e/dom/visibility_shadow_dom.cy.ts

-          this.attachShadow({ mode: 'open' })
-          this.style.display = 'block'
-        }
+  // #TODO: support shadow dom in fast visibility algorithm


do we have a feature issue we can link here?

currently this doesn't work AT ALL with shadow DOM, right? In other words, asserting any type of visibility on a shadow DOM element will fail?

AtofStryker · 2025-12-11T22:52:43Z

packages/driver/src/cypress/assertions/assert.ts

+import $dom from '../../dom'
+import $ from 'jquery'
+
+export const selectors = {


worth freezing these in Object.freeze or is that overkill?

AtofStryker · 2025-12-11T22:58:34Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+Run your existing test suite to identify any failures:
+
+```bash
+npm run test


wouldn't this be npx cypress run @jennifer-shehane ?

AtofStryker · 2025-12-11T23:04:58Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+| **[overflow-scroll-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Element outside clip-path polygon | ✅ Yes | ❌ No | ❌ No | Child element of polygon clip-path parent |
+| **[overflow-scroll-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Element outside clip-path inset | ✅ Yes | ❌ No | ❌ No | Child element of `clip-path: inset(25% 25% 25% 25%)` |
+| **[viewport-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Absolutely positioned element outside of the viewport | ✅ Yes | ❌ No | ❌ No | Elements that are outside of the viewport must be scrolled to before the fast algorithm will consider them visible. This is aligned with scroll-container visibility. |
+| **[z-index-coverage](../../../cypress/fixtures/visibility/positioning.html)** | Covered by higher z-index element |  ✅ Yes | ❌ No | ❌ No | Element covered by another element with higher z-index |


Suggested change

| **[z-index-coverage](../../../cypress/fixtures/visibility/positioning.html)** | Covered by higher z-index element | ✅ Yes | ❌ No | ❌ No | Element covered by another element with higher z-index |

| **[z-index-coverage](../../../cypress/fixtures/visibility/positioning.html)** | Covered by higher z-index element | ✅ Yes | ❌ No | ❌ No | Element covered by another element with higher z-index |

AtofStryker · 2025-12-11T23:05:06Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+| **[overflow-scroll-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Element outside clip-path inset | ✅ Yes | ❌ No | ❌ No | Child element of `clip-path: inset(25% 25% 25% 25%)` |
+| **[viewport-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Absolutely positioned element outside of the viewport | ✅ Yes | ❌ No | ❌ No | Elements that are outside of the viewport must be scrolled to before the fast algorithm will consider them visible. This is aligned with scroll-container visibility. |
+| **[z-index-coverage](../../../cypress/fixtures/visibility/positioning.html)** | Covered by higher z-index element |  ✅ Yes | ❌ No | ❌ No | Element covered by another element with higher z-index |
+| **[clip-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Element clipped by CSS clip property |  ✅ Yes | ❌ No | ❌ No | Element with `clip: rect(0, 0, 0, 0)` or similar clipping |


Suggested change

| **[clip-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Element clipped by CSS clip property | ✅ Yes | ❌ No | ❌ No | Element with `clip: rect(0, 0, 0, 0)` or similar clipping |

| **[clip-scenarios](../../../cypress/fixtures/visibility/overflow.html)** | Element clipped by CSS clip property | ✅ Yes | ❌ No | ❌ No | Element with `clip: rect(0, 0, 0, 0)` or similar clipping |

AtofStryker · 2025-12-11T23:05:30Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+
+### Issue 7: Shadow DOM incompatibilities
+
+**Problem:**: Elements inside shadow DOMs may not be detected properly as visible or hidden.


Suggested change

**Problem:**: Elements inside shadow DOMs may not be detected properly as visible or hidden.

**Problem:**: Elements inside shadow DOM may not be detected properly as visible or hidden.

AtofStryker · 2025-12-11T23:05:45Z

packages/driver/src/dom/visibility/MIGRATION_GUIDE.md

+
+**Problem:**: Elements inside shadow DOMs may not be detected properly as visible or hidden.
+
+**Solution:**: Test shadow dom components in isolation with component testing, and only test if the public interface of the shadow dom component is visible. You wouldn't assert on the visibility of the browser's default video play controls by querying its shadow dom: you would assert on the properties of the video element itself.


Suggested change

**Solution:**: Test shadow dom components in isolation with component testing, and only test if the public interface of the shadow dom component is visible. You wouldn't assert on the visibility of the browser's default video play controls by querying its shadow dom: you would assert on the properties of the video element itself.

**Solution:**: Test shadow DOM components in isolation with component testing, and only test if the public interface of the shadow DOM component is visible. You wouldn't assert on the visibility of the browser's default video play controls by querying its shadow dom: you would assert on the properties of the video element itself.

AtofStryker · 2025-12-11T23:07:01Z

packages/driver/src/dom/visibility/fastIsHidden.ts

+import { unwrap, wrap, isJquery } from '../jquery'
+const { isOption, isOptgroup, isBody, isHTML } = $elements
+
+const DEBUG = false


guessing this is just a local thing to leverage? can we leverage the debug library to set in the browser? I'm fine with either but maybe a comment

jennifer-shehane assigned cacieprins Oct 22, 2025

cacieprins and others added 28 commits October 27, 2025 15:26

migrate visibility tests to static fixtures

0aef8dc

clean up the html a little bit, remove ref to experimentalFastVisibility

f1c8f3d

Delete packages/driver/cypress/e2e/dom/visibility-migration.md

6115697

Update visibility.ts

35defae

fix assertion

a3c5abb

Merge branch 'develop' into refactor/visibility-tests

70e4ad9

fix incomplete

eb84c4b

stress test for visibility

232183a

splits up visibility into multiple files for easier grokking

2ceca61

middle of refactoring to un-hide the recursion

32d5466

notes to help with visibility efficiencyn

8460439

revert splitting - these fns are too interconnected to split without …

3be1d37

…resolving circular dependencies

impl new experimental visibility algo

23fd4d6

new experimental useFastVisibility config option

f89bb55

check four corners of rect instead of just center

bd41339

num-tests-in-memory=0

298691b

rm ref virtuoso

f08c2ac

rename file to be in line with its export

d824663

clean up jquery unwrapping

914b3cc

some more cleanup

70791be

Delete visibility-algorithm.dot

d139bbd

Delete visibility-algorithm.svg

36b314c

rm unused export

ea82d81

Update fastIsHidden.ts

7b6b16a

edit

41a5210

enable fast visibility mode in visibility related e2e tests

f921b18

enable clip-path test for fast visibility

2d1c827

memoize visibleAtPoint

d494872

cacieprins added 3 commits November 12, 2025 14:02

update algo diff

e522065

correct entries

d090287

Merge branch 'develop' into visibility-performance

a4d115e

cacieprins mentioned this pull request Dec 2, 2025

Visibility Performance #33043

Open

cacieprins and others added 8 commits December 4, 2025 13:55

Merge branch 'develop' into visibility-performance

9069b31

revert jquery typechanges

3eebf47

more ts fix

90a62bb

various fix

35d1a8f

Merge branch 'develop' into visibility-performance

41c6ce2

note firefox inconsistency vs chromium with 0-dim els

d55ed45

add cfg key to system test snapshot

e4e9b81

ts

f8b1b6f

cacieprins force-pushed the visibility-performance branch from ac255b8 to f8b1b6f Compare December 10, 2025 14:44

cacieprins added 6 commits December 10, 2025 10:21

more ff discrepancy

489ad8e

Merge branch 'develop' into visibility-performance

aa5ffb7

quick fix memo

0737530

fix regression with chained assertions

2a50449

fix jqueried ref, fix obj key in memoization

ab3b42b

manual chck for primitives instead of checking for "object" typeof

477c05c

cacieprins marked this pull request as ready for review December 10, 2025 17:18

cacieprins requested a review from brian-mann as a code owner December 10, 2025 17:18

changelog

578f3d5

jennifer-shehane self-requested a review December 10, 2025 18:17

jennifer-shehane reviewed Dec 10, 2025

View reviewed changes

jennifer-shehane requested changes Dec 10, 2025

View reviewed changes

add i18n copy for experimentalFastVisibility, documented as a step to…

b5ba888

… take in cfg/options.ts

AtofStryker self-requested a review December 11, 2025 21:04

AtofStryker reviewed Dec 11, 2025

View reviewed changes

jennifer-shehane self-requested a review December 12, 2025 19:04

		Performance:

		- Introduced a new `experimentalFastVisibility` experiment. Enabling this experiment changes how Cypress performs visibility checks and assertions. Read more about [experimental fast visibility](https://on.cypress.io/experiments/#experimental-fast-visibility). Addresses [#33044](https://github.com/cypress-io/cypress/issues/33044). Addressed in [#32801](https://github.com/cypress-io/cypress/pull/32801).

		// Chromium consider these elements visible, but Firefox considers them hidden. Should defer to browser
		// behavior, maybe?

		@@ -0,0 +1,330 @@
		# Fast Visibility Algorithm Migration Guide

		_(note: this file or content similar to it will be added to cy docs, when language / details are finalized)_

		- Significantly faster visibility calculations for complex DOM structures
		- Reduced CPU usage during test execution

	\| [z-index-coverage](../../../cypress/fixtures/visibility/positioning.html) \| Covered by higher z-index element \| ✅ Yes \| ❌ No \| ❌ No \| Element covered by another element with higher z-index \|
	\| [z-index-coverage](../../../cypress/fixtures/visibility/positioning.html) \| Covered by higher z-index element \| ✅ Yes \| ❌ No \| ❌ No \| Element covered by another element with higher z-index \|

	\| [clip-scenarios](../../../cypress/fixtures/visibility/overflow.html) \| Element clipped by CSS clip property \| ✅ Yes \| ❌ No \| ❌ No \| Element with `clip: rect(0, 0, 0, 0)` or similar clipping \|
	\| [clip-scenarios](../../../cypress/fixtures/visibility/overflow.html) \| Element clipped by CSS clip property \| ✅ Yes \| ❌ No \| ❌ No \| Element with `clip: rect(0, 0, 0, 0)` or similar clipping \|


		### Issue 7: Shadow DOM incompatibilities

		Problem:: Elements inside shadow DOMs may not be detected properly as visible or hidden.


		Problem:: Elements inside shadow DOMs may not be detected properly as visible or hidden.

		Solution:: Test shadow dom components in isolation with component testing, and only test if the public interface of the shadow dom component is visible. You wouldn't assert on the visibility of the browser's default video play controls by querying its shadow dom: you would assert on the properties of the video element itself.

perf: experimental "fast mode" for visibility checks #32801

Are you sure you want to change the base?

perf: experimental "fast mode" for visibility checks #32801

Conversation

cacieprins commented Oct 22, 2025 • edited by AtofStryker Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional details

Steps to test

How has the user experience changed?

PR Tasks

Uh oh!

cypress bot commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jennifer-shehane left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jennifer-shehane left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cacieprins commented Oct 22, 2025 •

edited by AtofStryker

Loading

cypress bot commented Oct 23, 2025 •

edited

Loading