feat(browser): support toBeInViewport utility method to assert element is in viewport or not (#8234)

Author: Shinyaigeek

docs/guide/browser/assertion-api.md

@@ -300,6 +300,27 @@ await expect.element(
 ).toBeVisible()
 ```
 
+## toBeInViewport
+
+```ts
+function toBeInViewport(options: { ratio?: number }): Promise<void>
+```
+
+This allows you to check if an element is currently in viewport with [IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+
+You can pass `ratio` argument as option, which means the minimal ratio of the element should be in viewport. `ratio` should be in 0~1.
+
+```ts
+// A specific element is in viewport.
+await expect.element(page.getByText('Welcome')).toBeInViewport()
+
+// 50% of a specific element should be in viewport
+await expect.element(page.getByText('To')).toBeInViewport({ ratio: 0.5 })
+
+// Full of a specific element should be in viewport
+await expect.element(page.getByText('Vitest')).toBeInViewport({ ratio: 1 })
+```
+
 ## toContainElement
 
 ```ts

packages/browser/jest-dom.d.ts

@@ -14,6 +14,52 @@ export interface TestingLibraryMatchers<E, R> {
    * @see https://vitest.dev/guide/browser/assertion-api#tobeinthedocument
    */
   toBeInTheDocument(): R
+  /**
+   * @description
+   * Assert whether an element is within the viewport or not.
+   *
+   * An element is considered to be in the viewport if any part of it intersects with the current viewport bounds.
+   * This matcher calculates the intersection ratio between the element and the viewport, similar to the
+   * IntersectionObserver API.
+   *
+   * The element must be in the document and have visible dimensions. Elements with display: none or 
+   * visibility: hidden are considered not in viewport.
+   * @example
+   * <div
+   *   data-testid="visible-element"
+   *   style="position: absolute; top: 10px; left: 10px; width: 50px; height: 50px;"
+   * >
+   *   Visible Element
+   * </div>
+   *
+   * <div
+   *   data-testid="hidden-element" 
+   *   style="position: fixed; top: -100px; left: 10px; width: 50px; height: 50px;"
+   * >
+   *   Hidden Element
+   * </div>
+   *
+   * <div
+   *   data-testid="large-element"
+   *   style="height: 400vh;"
+   * >
+   *   Large Element
+   * </div>
+   *
+   * // Check if any part of element is in viewport
+   * await expect.element(page.getByTestId('visible-element')).toBeInViewport()
+   * 
+   * // Check if element is outside viewport
+   * await expect.element(page.getByTestId('hidden-element')).not.toBeInViewport()
+   * 
+   * // Check if at least 50% of element is visible
+   * await expect.element(page.getByTestId('large-element')).toBeInViewport({ ratio: 0.5 })
+   * 
+   * // Check if element is completely visible
+   * await expect.element(page.getByTestId('visible-element')).toBeInViewport({ ratio: 1 })
+   * @see https://vitest.dev/guide/browser/assertion-api#tobeinviewport
+   */
+  toBeInViewport(options?: { ratio?: number }): R
   /**
    * @description
    * This allows you to check if an element is currently visible to the user.

packages/browser/src/client/tester/expect/index.ts

@@ -4,6 +4,7 @@ import toBeEmptyDOMElement from './toBeEmptyDOMElement'
 import { toBeDisabled, toBeEnabled } from './toBeEnabled'
 import toBeInTheDocument from './toBeInTheDocument'
 import { toBeInvalid, toBeValid } from './toBeInvalid'
+import toBeInViewport from './toBeInViewport'
 import toBePartiallyChecked from './toBePartiallyChecked'
 import toBeRequired from './toBeRequired'
 import toBeVisible from './toBeVisible'
@@ -28,6 +29,7 @@ export const matchers: MatchersObject = {
   toBeEnabled,
   toBeEmptyDOMElement,
   toBeInTheDocument,
+  toBeInViewport,
   toBeInvalid,
   toBeRequired,
   toBeValid,

packages/browser/src/client/tester/expect/toBeInViewport.ts

@@ -0,0 +1,81 @@
+/**
+ * The MIT License (MIT)
+ * Copyright (c) 2017 Kent C. Dodds
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ */
+
+import type { ExpectationResult, MatcherState } from '@vitest/expect'
+import type { Locator } from '../locators'
+import { getElementFromUserInput } from './utils'
+
+export default function toBeInViewport(
+  this: MatcherState,
+  actual: Element | Locator,
+  options?: { ratio?: number },
+): ExpectationResult {
+  const htmlElement = getElementFromUserInput(actual, toBeInViewport, this)
+
+  const expectedRatio = options?.ratio ?? 0
+  return getViewportIntersection(htmlElement, expectedRatio).then(({ pass, ratio }) => {
+    return {
+      pass,
+      message: () => {
+        const is = pass ? 'is' : 'is not'
+        const ratioText = expectedRatio > 0 ? ` with ratio ${expectedRatio}` : ''
+        const actualRatioText = ratio !== undefined ? ` (actual ratio: ${ratio.toFixed(3)})` : ''
+        return [
+          this.utils.matcherHint(
+            `${this.isNot ? '.not' : ''}.toBeInViewport`,
+            'element',
+            '',
+          ),
+          '',
+          `Received element ${is} in viewport${ratioText}${actualRatioText}:`,
+          `  ${this.utils.printReceived(htmlElement.cloneNode(false))}`,
+        ].join('\n')
+      },
+    }
+  })
+}
+
+/**
+ * Get viewport intersection ratio using IntersectionObserver API
+ * This implementation follows Playwright's approach using IntersectionObserver as the primary mechanism
+ */
+async function getViewportIntersection(element: HTMLElement | SVGElement, expectedRatio: number): Promise<{ pass: boolean; ratio?: number }> {
+  // Use IntersectionObserver API to get the intersection ratio
+  // Following Playwright's exact pattern from viewportRatio function
+  const intersectionRatio = await new Promise<number>((resolve) => {
+    // This mimics Playwright's Promise-based implementation in a synchronous context
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.length > 0) {
+        resolve(entries[0].intersectionRatio)
+      }
+      else {
+        resolve(0)
+      }
+      observer.disconnect()
+    })
+
+    observer.observe(element)
+
+    // Firefox workaround: requestAnimationFrame to ensure observer callback fires
+    // This is exactly how Playwright handles it
+    requestAnimationFrame(() => {})
+  })
+
+  // Apply the same logic as Playwright:
+  // ratio > 0 && ratio > (expectedRatio - 1e-9)
+  const pass = intersectionRatio > 0 && intersectionRatio > (expectedRatio - 1e-9)
+
+  return { pass, ratio: intersectionRatio }
+}

test/browser/fixtures/expect-dom/toBeInViewport.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { render } from './utils'
+
+describe('toBeInViewport', () => {
+  it('should work', async () => {
+    // Apply margin and width to small element, and padding to body and html because firefox's rendering causes a bit space between the element and the viewport
+    const { container } = render(`
+      <style>body, html { padding: 30px; }</style>
+      <div id="big" style="height: 10000px;"></div>
+      <div id="small" style="width: 50px; margin: 30px;">foo</div>
+    `)
+
+    await expect(container.querySelector('#big')).toBeInViewport()
+    await expect(container.querySelector('#small')).not.toBeInViewport()
+    
+    // Scroll to make small element visible
+    container.querySelector('#small')?.scrollIntoView()
+    await expect(container.querySelector('#small')).toBeInViewport()
+    await expect(container.querySelector('#small')).toBeInViewport({ ratio: 1 })
+  })
+
+  it('should respect ratio option', async () => {
+    const { container } = render(`
+      <style>body, div, html { padding: 0; margin: 0; }</style>
+      <div id="big" style="height: 400vh;"></div>
+    `)
+
+    await expect(container.querySelector('div')).toBeInViewport()
+    await expect(container.querySelector('div')).toBeInViewport({ ratio: 0.1 })
+    await expect(container.querySelector('div')).toBeInViewport({ ratio: 0.2 })
+    await expect(container.querySelector('div')).toBeInViewport({ ratio: 0.24 })
+    
+    // In this test, element's ratio is approximately 0.25 (viewport height / element height = 100vh / 400vh = 0.25)
+    // IntersectionObserver may return slightly different values due to browser rendering
+    await expect(container.querySelector('div')).toBeInViewport({ ratio: 0.24 })
+    await expect(container.querySelector('div')).not.toBeInViewport({ ratio: 0.26 })
+    
+    await expect(container.querySelector('div')).not.toBeInViewport({ ratio: 0.3 })
+    await expect(container.querySelector('div')).not.toBeInViewport({ ratio: 0.7 })
+    await expect(container.querySelector('div')).not.toBeInViewport({ ratio: 0.8 })
+  })
+
+  it('should report intersection even if fully covered by other element', async () => {
+    const { container } = render(`
+      <h1>hello</h1>
+      <div style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; background: red; z-index: 1000;"></div>
+    `)
+    
+    await expect(container.querySelector('h1')).toBeInViewport()
+  })
+})