add migration guide, additional edge cases, behavior table

Author: cacieprins

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

@@ -1,6 +1,37 @@
 // @ts-ignore
 const { $, dom } = Cypress
 
+/**
+ * Most of the tests in here are declarative. Due to the range of visibility scenarios, test case
+ * understandability is paramount. These test cases are defined declaratively *in the fixture html
+ * file, and are iterated upon with the helper functions in the `visibility scenarios` describe block.
+ *
+ * CSS for test cases are inlined into the DOM purposefully, to ensure easy reference and debugging.
+ *
+ * Test case elements that are expected to be visible typically have a `lightgreen` background color,
+ * while test case elements that are expected to be hidden typically have a `lightcoral` background color.
+ * This helps to quickly identify if a given element's assertions are in-line with browser behavior.
+ *
+ * A test case where the visibility behavior is expected to be identical between the legacy and fast
+ * algorithms:
+ *
+ * <div class="testCase"
+ *   cy-expect="visible"
+ *   cy-label="helpful description for the assertion"
+ *   style="height: 100px; width: 100px;">
+ * </div>
+ *
+ * A test case where the visibility behavior is expected to be different between the legacy and fast
+ * algorithms (note the css of the example does not accurately reflect this visibility behavior):
+ *
+ * <div class="testCase"
+ *   cy-legacy-expect="visible"
+ *   cy-fast-expect="hidden"
+ *   cy-label="helpful description for the assertion"
+ *   style="height: 100px; width: 100px;">
+ * </div>
+ */
+
 describe('src/cypress/dom/visibility', {
   slowTestThreshold: 500,
 }, () => {
@@ -268,9 +299,11 @@ describe('src/cypress/dom/visibility', {
             'visibility-property',
             'display-property',
             'opacity-property',
-            'input-elements',
             'table-elements',
             'box-interactions',
+            'style-filters',
+            'contain-property',
+            'pointer-events-none',
           ])
         })
 
@@ -307,7 +340,8 @@ describe('src/cypress/dom/visibility', {
             'overflow-relative-positioning',
             'overflow-flex-container',
             'overflow-complex-scenarios',
-            'clip-path-scenarios',
+            'clip-scenarios',
+            'viewport-scenarios',
           ])
         })
 
@@ -324,6 +358,8 @@ describe('src/cypress/dom/visibility', {
             'fixed-positioning-with-zero-dimensions',
             'position-absolute-scenarios',
             'position-sticky-scenarios',
+            'positioning-cousin-coverage',
+            'z-index-coverage',
           ])
         })
 
@@ -364,7 +400,6 @@ describe('src/cypress/dom/visibility', {
           })
 
           it('has a parent with `display: none`', function () {
-            cy.visit('/fixtures/visibility/basic-css-properties.html')
             prepareFixtureSection('display-property')
             cy.get('[cy-section="display-property"] .testCase[cy-expect="hidden"] span').then(($el) => {
               reasonIs($el, 'This element `<span.testCase>` is not visible because its parent `<div.testCase>` has CSS property: `display: none`')

packages/driver/cypress/fixtures/visibility/basic-css-properties.html

@@ -36,12 +36,12 @@ <h3>Opacity Property</h3>
     </div>
   </div>
 
-  <div class="test-section" cy-section="input-elements">
-    <h3>Input Elements</h3>
-    <input class="testCase" cy-expect="hidden" cy-label="Hidden input" type="hidden" value="hidden input">
-    <input class="testCase" cy-expect="visible" cy-label="Visible input" type="text" value="visible input">
+  <div class="test-section" cy-section="style-filters">
+    <h3>Style Filters</h3>
+    <!-- while opacity(0) renders the element as fully transparent, it is still considered visible: it has a box model, and it is clickable -->
+    <div class="testCase" cy-expect="visible" cy-label="Hidden by style filter: opacity(0)" style="filter: opacity(0);">Hidden by style filter: opacity(0)</div>
   </div>
-  
+
   <div class="test-section" cy-section="table-elements">
     <h3>Table Elements</h3>
     <table>
@@ -63,5 +63,30 @@ <h3>Table Elements</h3>
       </span>
     </div>
   </div>
+
+  <div class="test-section" cy-section="pointer-events-none">
+    <h3>Pointer Events: None</h3>
+    <div class="testCase" cy-legacy-expect="visible" cy-fast-expect="hidden" cy-label="Element with pointer-events: none" style="pointer-events: none;">Element with pointer-events: none</div>
+  </div>
+
+  <div class="test-section" cy-section="contain-property">
+    <h3>CSS Contain Property</h3>
+    
+    <!-- Element with contain: layout -->
+    <div class="testCase" cy-expect="visible" cy-label="Element with contain: layout" style="width: 100px; height: 100px; background: lightcoral; contain: layout;">
+      <span class="testCase" cy-expect="visible" cy-label="Child of contain: layout element">contain: layout</span>
+    </div>
+
+    <!-- Element with contain: paint -->
+    <div class="testCase" cy-expect="visible" cy-label="Element with contain: paint" style="width: 100px; height: 100px; background: lightcoral; contain: paint;">
+      <span class="testCase" cy-legacy-expect="visible" cy-fast-expect="hidden" cy-label="Child positioned out of bounds of its `contain: paint` parent" style="position:relative; top:500px">contain: paint</span>
+    </div>
+
+    <!-- Element with contain: strict -->
+    <div class="testCase" cy-expect="visible" cy-label="Element with contain: strict" style="width: 100px; height: 100px; background: lightcoral; contain: strict;">
+      <span class="testCase" cy-expect="visible" cy-label="Child of contain: strict element">contain: strict</span>
+    </div>
+  </div>
+
 </body>
 </html>

packages/driver/cypress/fixtures/visibility/overflow.html

@@ -235,7 +235,7 @@ <h3 class="testCase" cy-expect="visible" cy-label="Heading">Example</h3>
     </div>
   </div>
 
-  <div class="test-section" cy-section="clip-path-scenarios">
+  <div class="test-section" cy-section="clip-scenarios">
     <h3>Clip-Path Scenarios (note: legacy mode does not support clip-path)</h3>
 
     <!-- Clip-path polygon that clips everything -->
@@ -267,6 +267,23 @@ <h3>Clip-Path Scenarios (note: legacy mode does not support clip-path)</h3>
     <div class="testCase" cy-expect="visible" cy-label="Parent with clip-path path" style="position: relative; clip-path: path('M 0 0 L 100 0 L 100 100 L 0 100 Z');">
       <span class="testCase" cy-expect="visible" cy-label="Element inside clip-path path" style="background: lightgreen;">path content</span>
     </div>
+
+    <!-- CSS clip property -->
+    <div class="testCase" cy-legacy-expect="visible" cy-fast-expect="hidden" cy-label="Element clipped by CSS clip property" style="position: absolute; clip: rect(0, 0, 0, 0); background: lightcoral; width: 100px; height: 100px;">clipped by clip: rect(0,0,0,0)</div>
+
+    <!-- CSS mask property note: this yields an element that is not rendered as visible, but has a box model that is visible and is clickable -->
+    <div class="testCase" cy-expect="visible" cy-label="Element masked by CSS mask" style="width: 100px; height: 100px; background: lightcoral; mask: linear-gradient(black, black); mask-size: 0 0;">masked by CSS mask</div>
+  </div>
+
+  <div cy-section="viewport-scenarios">
+    <h3>Viewport Scenarios</h3>
+    <div class="testCase" cy-legacy-expect="visible" cy-fast-expect="hidden" cy-label="Position absolute element outside viewport" style="position: absolute; top: -100px; left: -100px; width: 100px; height: 100px; background: lightcoral;">Element outside viewport</div>
+    <div class="testCase" cy-expect="hidden" cy-label="Position fixed element outside of viewport" style="position: fixed; top: -100px; left: -100px; width: 100px; height: 100px; background: lightcoral;">Position fixed element outside of viewport</div>
+    <iframe style="display:none;">
+      <body>
+        <div class="testCase" cy-expect="hidden" cy-label="Element inside hidden iframe" style="width: 100px; height: 100px; background: lightcoral;">Element inside hidden iframe</div>
+      </body>
+    </iframe>
   </div>
 </body>
 </html>

packages/driver/cypress/fixtures/visibility/positioning.html

@@ -109,5 +109,27 @@ <h3>Position Sticky Scenarios</h3>
     </div>
   </div>
 
+  <div class="test-section" cy-section="positioning-cousin-coverage" >
+    <h3>Positioning Cousin Coverage</h3>
+
+    <!-- Element covered by an absolutely positioned cousin -->
+     <div style="position: relative;">
+      <div style="width: 200px; height: 100px; background: lightblue;">
+        <span class="testCase" cy-fast-expect="hidden" cy-legacy-expect="visible" cy-label="Target element to be covered" style="display: block; width: 100px; height: 50px; background: lightgreen;">Target element</span>
+      </div>
+      <div class="testCase" cy-expect="visible" cy-label="Absolutely positioned cousin covering target" style="position: absolute; top: 0px; left: 0px; width: 100px; height: 50px; background: lightcoral;">Covering cousin</div>
+    </div>
+  </div>
+
+  <div class="test-section" cy-section="z-index-coverage">
+    <h3>Z-Index Coverage</h3>
+    
+    <!-- Element covered by higher z-index element -->
+    <div style="position: relative; width: 300px; height: 150px; background: lightgray;">
+      <div class="testCase" cy-legacy-expect="visible" cy-fast-expect="hidden" cy-label="Element covered by higher z-index" style="position: absolute; top: 20px; left: 20px; width: 100px; height: 100px; background: lightgreen; z-index: 1;">Lower z-index element</div>
+      <div class="testCase" cy-expect="visible" cy-label="Higher z-index covering element" style="position: absolute; top: 20px; left: 20px; width: 100px; height: 100px; background: lightcoral; z-index: 2;">Higher z-index element</div>
+    </div>
+  </div>
+
 </body>
 </html>

packages/driver/cypress/fixtures/visibility/transforms.html

@@ -37,6 +37,7 @@ <h3>Translation</h3>
     <div class="testCase" cy-expect="visible" cy-label="Translate 2D" style="transform: translate(10px, 15px)">Translated in 2 dimensions</div>
     <div class="testCase" cy-expect="visible" cy-label="Translate Z" style="transform: translateZ(10px)">Translated in 3rd dimension</div>
     <div class="testCase" cy-expect="visible" cy-label="Translate 3D" style="transform: translate3d(10px, 15px, 20px)">Translated in 3 dimensions</div>
+    <div class="testCase" cy-legacy-expect="visible" cy-fast-expect="hidden" cy-label="Translate outside viewport" style="transform: translateY(-9999px)">Translated outside viewport</div>
   </div>
   <div class="test-section" cy-section="rotation">
     <h3>Rotation</h3>

packages/driver/cypress/fixtures/visibility/ux.js

@@ -24,6 +24,8 @@ document.addEventListener('DOMContentLoaded', () => {
 })
 
 document.addEventListener('click', (ev) => {
+  // eslint-disable-next-line no-console
+  console.log('click', ev.target)
   const [, section] = ev.target?.href?.split('#') ?? []
 
   if (!section) return