feat: add ability to specify offsets for JSHandle.click

docs/api.md

@@ -307,7 +307,7 @@
   * [elementHandle.boundingBox()](#elementhandleboundingbox)
   * [elementHandle.boxModel()](#elementhandleboxmodel)
   * [elementHandle.click([options])](#elementhandleclickoptions)
-  * [elementHandle.clickablePoint()](#elementhandleclickablepoint)
+  * [elementHandle.clickablePoint([offset])](#elementhandleclickablepointoffset)
   * [elementHandle.contentFrame()](#elementhandlecontentframe)
   * [elementHandle.dispose()](#elementhandledispose)
   * [elementHandle.drag(target)](#elementhandledragtarget)
@@ -4445,13 +4445,19 @@ This method returns boxes of the element, or `null` if the element is not visibl
   - `button` <"left"|"right"|"middle"> Defaults to `left`.
   - `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
   - `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
+  - `offset` <[Object]> Offset in pixels relative to the top-left corder of the border box of the element.
+    - `x` <number> x-offset in pixels relative to the top-left corder of the border box of the element.
+    - `y` <number> y-offset in pixels relative to the top-left corder of the border box of the element.
 - returns: <[Promise]> Promise which resolves when the element is successfully clicked. Promise gets rejected if the element is detached from DOM.
 
 This method scrolls element into view if needed, and then uses [page.mouse](#pagemouse) to click in the center of the element.
 If the element is detached from DOM, the method throws an error.
 
-#### elementHandle.clickablePoint()
+#### elementHandle.clickablePoint([offset])
 
+- `offset` <[Object]>
+  - `x` <number> x-offset in pixels relative to the top-left corder of the border box of the element.
+  - `y` <number> y-offset in pixels relative to the top-left corder of the border box of the element.
 - returns: <[Promise<[Point]>]> Resolves to the x, y point that describes the element's position.
 
 #### elementHandle.contentFrame()

src/common/JSHandle.ts

@@ -411,7 +411,10 @@ export class ElementHandle<
     if (error) throw new Error(error);
   }
 
-  async clickablePoint(): Promise<Point> {
+  /**
+   * Returns the middle point within an element unless a specific offset is provided.
+   */
+  async clickablePoint(offset?: Offset): Promise<Point> {
     const [result, layoutMetrics] = await Promise.all([
       this._client
         .send('DOM.getContentQuads', {
@@ -434,8 +437,30 @@ export class ElementHandle<
       .filter((quad) => computeQuadArea(quad) > 1);
     if (!quads.length)
       throw new Error('Node is either not clickable or not an HTMLElement');
-    // Return the middle point of the first quad.
     const quad = quads[0];
+    if (offset) {
+      // Return the point of the first quad identified by offset.
+      let minX = Number.MAX_SAFE_INTEGER;
+      let minY = Number.MAX_SAFE_INTEGER;
+      for (const point of quad) {
+        if (point.x < minX) {
+          minX = point.x;
+        }
+        if (point.y < minY) {
+          minY = point.y;
+        }
+      }
+      if (
+        minX !== Number.MAX_SAFE_INTEGER &&
+        minY !== Number.MAX_SAFE_INTEGER
+      ) {
+        return {
+          x: minX + offset.x,
+          y: minY + offset.y,
+        };
+      }
+    }
+    // Return the middle point of the first quad.
     let x = 0;
     let y = 0;
     for (const point of quad) {
@@ -495,7 +520,7 @@ export class ElementHandle<
    */
   async click(options: ClickOptions = {}): Promise<void> {
     await this._scrollIntoViewIfNeeded();
-    const { x, y } = await this.clickablePoint();
+    const { x, y } = await this.clickablePoint(options.offset);
     await this._page.mouse.click(x, y, options);
   }
 
@@ -1011,6 +1036,20 @@ export class ElementHandle<
   }
 }
 
+/**
+ * @public
+ */
+export interface Offset {
+  /**
+   * x-offset for the clickable point relative to the top-left corder of the border box.
+   */
+  x: number;
+  /**
+   * y-offset for the clickable point relative to the top-left corder of the border box.
+   */
+  y: number;
+}
+
 /**
  * @public
  */
@@ -1029,6 +1068,10 @@ export interface ClickOptions {
    * @defaultValue 1
    */
   clickCount?: number;
+  /**
+   * Offset for the clickable point relative to the top-left corder of the border box.
+   */
+  offset?: Offset;
 }
 
 /**

test/jshandle.spec.ts

@@ -297,4 +297,95 @@ describe('JSHandle', function () {
       );
     });
   });
+
+  describe('JSHandle.clickablePoint', function () {
+    it('should work', async () => {
+      const { page } = getTestState();
+
+      await page.evaluate(() => {
+        document.body.style.padding = '0';
+        document.body.style.margin = '0';
+        document.body.innerHTML = `
+          <div style="cursor: pointer; width: 120px; height: 60px; margin: 30px; padding: 15px;"></div>
+        `;
+      });
+
+      const divHandle = await page.$('div');
+      expect(await divHandle.clickablePoint()).toEqual({
+        x: 45 + 60, // margin + middle point offset
+        y: 45 + 30, // margin + middle point offset
+      });
+      expect(
+        await divHandle.clickablePoint({
+          x: 10,
+          y: 15,
+        })
+      ).toEqual({
+        x: 30 + 10, // margin + offset
+        y: 30 + 15, // margin + offset
+      });
+    });
+
+    it('should work for iframes', async () => {
+      const { page } = getTestState();
+      await page.evaluate(() => {
+        document.body.style.padding = '10px';
+        document.body.style.margin = '10px';
+        document.body.innerHTML = `
+          <iframe style="border: none; margin: 0; padding: 0;" seamless sandbox srcdoc="<style>* { margin: 0; padding: 0;}</style><div style='cursor: pointer; width: 120px; height: 60px; margin: 30px; padding: 15px;' />"></iframe>
+        `;
+      });
+      const frame = page.frames()[1];
+      const divHandle = await frame.$('div');
+      expect(await divHandle.clickablePoint()).toEqual({
+        x: 20 + 45 + 60, // iframe pos + margin + middle point offset
+        y: 20 + 45 + 30, // iframe pos + margin + middle point offset
+      });
+      expect(
+        await divHandle.clickablePoint({
+          x: 10,
+          y: 15,
+        })
+      ).toEqual({
+        x: 20 + 30 + 10, // iframe pos + margin + offset
+        y: 20 + 30 + 15, // iframe pos + margin + offset
+      });
+    });
+  });
+
+  describe('JSHandle.click', function () {
+    itFailsFirefox('should work', async () => {
+      const { page } = getTestState();
+
+      const clicks = [];
+
+      await page.exposeFunction('reportClick', (x: number, y: number): void => {
+        clicks.push([x, y]);
+      });
+
+      await page.evaluate(() => {
+        document.body.style.padding = '0';
+        document.body.style.margin = '0';
+        document.body.innerHTML = `
+          <div style="cursor: pointer; width: 120px; height: 60px; margin: 30px; padding: 15px;"></div>
+        `;
+        document.body.addEventListener('click', (e) => {
+          (window as any).reportClick(e.clientX, e.clientY);
+        });
+      });
+
+      const divHandle = await page.$('div');
+      await divHandle.click();
+      await divHandle.click({
+        offset: {
+          x: 10,
+          y: 15,
+        },
+      });
+      expect(clicks).toEqual([
+        [45 + 60, 45 + 30], // margin + middle point offset
+        [30 + 10, 30 + 15], // margin + offset
+      ]);
+    });
+  });
 });

utils/doclint/check_public_api/index.js

@@ -371,6 +371,13 @@ function compareDocumentations(actual, expected) {
           expectedName: 'ClickOptions',
         },
       ],
+      [
+        'Method ElementHandle.clickablePoint() offset',
+        {
+          actualName: 'Object',
+          expectedName: 'Offset',
+        },
+      ],
       [
         'Method ElementHandle.press() options',
         {