feat: introduce locator.viewportRatio (#19761)

References #8740

docs/src/api/class-locator.md

@@ -1339,6 +1339,12 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: Locator.uncheck.trial = %%-input-trial-%%
 * since: v1.14
 
+## async method: Locator.viewportRatio
+* since: v1.30
+- returns: <[float]>
+
+Returns the ratio of intersection between viewport and the element, according to the [intersection observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+
 ## async method: Locator.waitFor
 * since: v1.16
 

packages/playwright-core/src/client/locator.ts

@@ -257,6 +257,10 @@ export class Locator implements api.Locator {
     return this._withElement((h, timeout) => h.scrollIntoViewIfNeeded({ ...options, timeout }), options.timeout);
   }
 
+  async viewportRatio(): Promise<number> {
+    return (await this._frame._channel.viewportRatio({ selector: this._selector, strict: true })).value;
+  }
+
   async selectOption(values: string | api.ElementHandle | SelectOption | string[] | api.ElementHandle[] | SelectOption[] | null, options: SelectOptionOptions = {}): Promise<string[]> {
     return this._frame.selectOption(this._selector, values, { strict: true, ...options });
   }

packages/playwright-core/src/protocol/debug.ts

@@ -66,6 +66,7 @@ export const commandsWithTracingSnapshots = new Set([
   'Frame.isEnabled',
   'Frame.isHidden',
   'Frame.isVisible',
+  'Frame.viewportRatio',
   'Frame.isEditable',
   'Frame.press',
   'Frame.selectOption',

packages/playwright-core/src/protocol/validator.ts

@@ -1425,6 +1425,13 @@ scheme.FrameIsVisibleParams = tObject({
 scheme.FrameIsVisibleResult = tObject({
   value: tBoolean,
 });
+scheme.FrameViewportRatioParams = tObject({
+  selector: tString,
+  strict: tOptional(tBoolean),
+});
+scheme.FrameViewportRatioResult = tObject({
+  value: tNumber,
+});
 scheme.FrameIsEditableParams = tObject({
   selector: tString,
   strict: tOptional(tBoolean),

packages/playwright-core/src/server/dispatchers/frameDispatcher.ts

@@ -203,6 +203,10 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Pa
     return { value: await this._frame.isVisible(metadata, params.selector, params) };
   }
 
+  async viewportRatio(params: channels.FrameViewportRatioParams, metadata: CallMetadata): Promise<channels.FrameViewportRatioResult> {
+    return { value: await this._frame.viewportRatio(metadata, params.selector, params) };
+  }
+
   async hover(params: channels.FrameHoverParams, metadata: CallMetadata): Promise<void> {
     return await this._frame.hover(metadata, params.selector, params);
   }

packages/playwright-core/src/server/frames.ts

@@ -1318,6 +1318,31 @@ export class Frame extends SdkObject {
     }, this._page._timeoutSettings.timeout({}));
   }
 
+  async viewportRatio(metadata: CallMetadata, selector: string, options: types.StrictOptions = {}): Promise<number> {
+    const controller = new ProgressController(metadata, this);
+    return controller.run(async progress => {
+      progress.log(`  calculating viewport ratio of ${this._asLocator(selector)}`);
+      const resolved = await this._resolveInjectedForSelector(progress, selector, options);
+      if (!resolved)
+        return 0;
+      return await resolved.injected.evaluate(async (injected, { info }) => {
+        const element = injected.querySelector(info.parsed, document, info.strict);
+        if (!element)
+          return 0;
+        return await new Promise(resolve => {
+          const observer = new IntersectionObserver(entries => {
+            resolve(entries[0].intersectionRatio);
+            observer.disconnect();
+          });
+          observer.observe(element);
+          // Firefox doesn't call IntersectionObserver callback unless
+          // there are rafs.
+          requestAnimationFrame(() => {});
+        });
+      }, { info: resolved.info });
+    }, this._page._timeoutSettings.timeout({}));
+  }
+
   async isHidden(metadata: CallMetadata, selector: string, options: types.StrictOptions = {}): Promise<boolean> {
     return !(await this.isVisible(metadata, selector, options));
   }

packages/playwright-core/types/types.d.ts

@@ -11448,6 +11448,12 @@ export interface Locator {
     trial?: boolean;
   }): Promise<void>;
 
+  /**
+   * Returns the ratio of intersection between viewport and the element, according to the
+   * [intersection observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+   */
+  viewportRatio(): Promise<number>;
+
   /**
    * Returns when element specified by locator satisfies the `state` option.
    *

packages/protocol/src/channels.ts

@@ -2196,6 +2196,7 @@ export interface FrameChannel extends FrameEventTarget, Channel {
   isEnabled(params: FrameIsEnabledParams, metadata?: Metadata): Promise<FrameIsEnabledResult>;
   isHidden(params: FrameIsHiddenParams, metadata?: Metadata): Promise<FrameIsHiddenResult>;
   isVisible(params: FrameIsVisibleParams, metadata?: Metadata): Promise<FrameIsVisibleResult>;
+  viewportRatio(params: FrameViewportRatioParams, metadata?: Metadata): Promise<FrameViewportRatioResult>;
   isEditable(params: FrameIsEditableParams, metadata?: Metadata): Promise<FrameIsEditableResult>;
   press(params: FramePressParams, metadata?: Metadata): Promise<FramePressResult>;
   querySelector(params: FrameQuerySelectorParams, metadata?: Metadata): Promise<FrameQuerySelectorResult>;
@@ -2593,6 +2594,16 @@ export type FrameIsVisibleOptions = {
 export type FrameIsVisibleResult = {
   value: boolean,
 };
+export type FrameViewportRatioParams = {
+  selector: string,
+  strict?: boolean,
+};
+export type FrameViewportRatioOptions = {
+  strict?: boolean,
+};
+export type FrameViewportRatioResult = {
+  value: number,
+};
 export type FrameIsEditableParams = {
   selector: string,
   strict?: boolean,

packages/protocol/src/protocol.yml

@@ -1908,6 +1908,15 @@ Frame:
       tracing:
         snapshot: true
 
+    viewportRatio:
+      parameters:
+        selector: string
+        strict: boolean?
+      returns:
+        value: number
+      tracing:
+        snapshot: true
+
     isEditable:
       parameters:
         selector: string

tests/page/locator-misc-2.spec.ts

@@ -154,3 +154,17 @@ it('locator.count should work with deleted Map in main world', async ({ page })
   await page.locator('#searchResultTableDiv .x-grid3-row').count();
   await expect(page.locator('#searchResultTableDiv .x-grid3-row')).toHaveCount(0);
 });
+
+it('locator.viewportRatio', async ({ page }) => {
+  await page.setContent(`
+    <style>body { padding: 0; margin: 0; } div { position: absolute; left: 0; top: 0 }</style>
+    <div id=fills-viewport style='width: 100vw; height: 100vh;'></div>
+    <div id=half-viewport style='width: 50vw; height: 100vh;'></div>
+    <div id=twice-viewport style='width: 200vw; height: 100vh;'></div>
+    <div id=off-viewport style='left:100vw; width: 100vw; height: 100vh;'></div>
+  `);
+  expect.soft(await page.locator('#fills-viewport').viewportRatio()).toBe(1);
+  expect.soft(await page.locator('#half-viewport').viewportRatio()).toBe(1);
+  expect.soft(await page.locator('#twice-viewport').viewportRatio()).toBe(0.5);
+  expect.soft(await page.locator('#off-viewport').viewportRatio()).toBe(0);
+});