feat: add Mouse#wheel (#6141)

docs/api.md

@@ -190,6 +190,7 @@
   * [mouse.down([options])](#mousedownoptions)
   * [mouse.move(x, y[, options])](#mousemovex-y-options)
   * [mouse.up([options])](#mouseupoptions)
+  * [mouse.wheel([options])](#mousewheeloptions)
 - [class: Touchscreen](#class-touchscreen)
   * [touchscreen.tap(x, y)](#touchscreentapx-y)
 - [class: Tracing](#class-tracing)
@@ -2579,6 +2580,28 @@ Dispatches a `mousemove` event.
 
 Dispatches a `mouseup` event.
 
+#### mouse.wheel([options])
+- `options` <[Object]>
+  - `deltaX` X delta in CSS pixels for mouse wheel event (default: 0). Positive values emulate a scroll up and negative values a scroll down event.
+  - `deltaY` Y delta in CSS pixels for mouse wheel event (default: 0). Positive values emulate a scroll right and negative values a scroll left event.
+- returns: <[Promise]>
+
+Dispatches a `mousewheel` event.
+
+Examples:
+```js
+await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');
+
+const elem = await page.$('div');
+const boundingBox = await elem.boundingBox();
+await page.mouse.move(
+  boundingBox.x + boundingBox.width / 2,
+  boundingBox.y + boundingBox.height / 2
+);
+
+await page.mouse.wheel({ deltaY: -100 })
+```
+
 ### class: Touchscreen
 
 #### touchscreen.tap(x, y)

new-docs/puppeteer.md

@@ -64,6 +64,7 @@
 |  [LaunchOptions](./puppeteer.launchoptions.md) | Generic launch options that can be passed when launching any browser. |
 |  [Metrics](./puppeteer.metrics.md) |  |
 |  [MouseOptions](./puppeteer.mouseoptions.md) |  |
+|  [MouseWheelOptions](./puppeteer.mousewheeloptions.md) |  |
 |  [PressOptions](./puppeteer.pressoptions.md) |  |
 |  [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. |
 |  [RemoteAddress](./puppeteer.remoteaddress.md) |  |

new-docs/puppeteer.mouse.md

@@ -81,4 +81,5 @@ await browser.defaultBrowserContext().overridePermissions(
 |  [down(options)](./puppeteer.mouse.down.md) |  | Dispatches a <code>mousedown</code> event. |
 |  [move(x, y, options)](./puppeteer.mouse.move.md) |  | Dispatches a <code>mousemove</code> event. |
 |  [up(options)](./puppeteer.mouse.up.md) |  | Dispatches a <code>mouseup</code> event. |
+|  [wheel(options)](./puppeteer.mouse.wheel.md) |  | Dispatches a <code>mousewheel</code> event. |
 

new-docs/puppeteer.mouse.wheel.md

@@ -0,0 +1,42 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Mouse](./puppeteer.mouse.md) &gt; [wheel](./puppeteer.mouse.wheel.md)
+
+## Mouse.wheel() method
+
+Dispatches a `mousewheel` event.
+
+<b>Signature:</b>
+
+```typescript
+wheel(options?: MouseWheelOptions): Promise<void>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  options | [MouseWheelOptions](./puppeteer.mousewheeloptions.md) | Optional: <code>MouseWheelOptions</code>. |
+
+<b>Returns:</b>
+
+Promise&lt;void&gt;
+
+## Example
+
+An example of zooming into an element:
+
+```js
+await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');
+
+const elem = await page.$('div');
+const boundingBox = await elem.boundingBox();
+await page.mouse.move(
+  boundingBox.x + boundingBox.width / 2,
+  boundingBox.y + boundingBox.height / 2
+);
+
+await page.mouse.wheel({ deltaY: -100 })
+
+```
+

new-docs/puppeteer.mousewheeloptions.deltax.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [MouseWheelOptions](./puppeteer.mousewheeloptions.md) &gt; [deltaX](./puppeteer.mousewheeloptions.deltax.md)
+
+## MouseWheelOptions.deltaX property
+
+<b>Signature:</b>
+
+```typescript
+deltaX?: number;
+```

new-docs/puppeteer.mousewheeloptions.deltay.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [MouseWheelOptions](./puppeteer.mousewheeloptions.md) &gt; [deltaY](./puppeteer.mousewheeloptions.deltay.md)
+
+## MouseWheelOptions.deltaY property
+
+<b>Signature:</b>
+
+```typescript
+deltaY?: number;
+```

new-docs/puppeteer.mousewheeloptions.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [MouseWheelOptions](./puppeteer.mousewheeloptions.md)
+
+## MouseWheelOptions interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface MouseWheelOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [deltaX](./puppeteer.mousewheeloptions.deltax.md) | number |  |
+|  [deltaY](./puppeteer.mousewheeloptions.deltay.md) | number |  |
+

src/common/Input.ts

@@ -288,6 +288,14 @@ export interface MouseOptions {
   clickCount?: number;
 }
 
+/**
+ * @public
+ */
+export interface MouseWheelOptions {
+  deltaX?: number;
+  deltaY?: number;
+}
+
 /**
  * The Mouse class operates in main-frame CSS pixels
  * relative to the top-left corner of the viewport.
@@ -446,6 +454,38 @@ export class Mouse {
       clickCount,
     });
   }
+
+  /**
+   * Dispatches a `mousewheel` event.
+   * @param options - Optional: `MouseWheelOptions`.
+   *
+   * @example
+   * An example of zooming into an element:
+   * ```js
+   * await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');
+   *
+   * const elem = await page.$('div');
+   * const boundingBox = await elem.boundingBox();
+   * await page.mouse.move(
+   *   boundingBox.x + boundingBox.width / 2,
+   *   boundingBox.y + boundingBox.height / 2
+   * );
+   *
+   * await page.mouse.wheel({ deltaY: -100 })
+   * ```
+   */
+  async wheel(options: MouseWheelOptions = {}): Promise<void> {
+    const { deltaX = 0, deltaY = 0 } = options;
+    await this._client.send('Input.dispatchMouseEvent', {
+      type: 'mouseWheel',
+      x: this._x,
+      y: this._y,
+      deltaX,
+      deltaY,
+      modifiers: this._keyboard._modifiers,
+      pointerType: 'mouse',
+    });
+  }
 }
 
 /**

test/assets/input/wheel.html

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <style>
+      body {
+        min-height: 100vh;
+        margin: 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+
+      div {
+        width: 105px;
+        height: 105px;
+        background: #cdf;
+        padding: 5px;
+      }
+    </style>
+    <title>Element: wheel event - Scaling_an_element_via_the_wheel - code sample</title>
+  </head>
+  <body>
+    <div>Scale me with your mouse wheel.</div>
+    <script>
+      function zoom(event) {
+        event.preventDefault();
+
+        scale += event.deltaY * -0.01;
+
+        // Restrict scale
+        scale = Math.min(Math.max(.125, scale), 4);
+
+        // Apply scale transform
+        el.style.transform = `scale(${scale})`;
+      }
+
+      let scale = 1;
+      const el = document.querySelector('div');
+      el.onwheel = zoom;
+    </script>
+  </body>
+</html>

test/mouse.spec.ts

@@ -173,6 +173,29 @@ describe('Mouse', function () {
         throw new Error(modifiers[modifier] + ' should be false');
     }
   });
+  itFailsFirefox('should send mouse wheel events', async () => {
+    const { page, server } = getTestState();
+
+    await page.goto(server.PREFIX + '/input/wheel.html');
+    const elem = await page.$('div');
+    const boundingBoxBefore = await elem.boundingBox();
+    expect(boundingBoxBefore).toMatchObject({
+      width: 115,
+      height: 115,
+    });
+
+    await page.mouse.move(
+      boundingBoxBefore.x + boundingBoxBefore.width / 2,
+      boundingBoxBefore.y + boundingBoxBefore.height / 2
+    );
+
+    await page.mouse.wheel({ deltaY: -100 });
+    const boundingBoxAfter = await elem.boundingBox();
+    expect(boundingBoxAfter).toMatchObject({
+      width: 230,
+      height: 230,
+    });
+  });
   itFailsFirefox('should tween mouse movement', async () => {
     const { page } = getTestState();
 

utils/doclint/check_public_api/index.js

@@ -388,6 +388,13 @@ function compareDocumentations(actual, expected) {
           expectedName: 'MouseOptions',
         },
       ],
+      [
+        'Method Mouse.wheel() options',
+        {
+          actualName: 'Object',
+          expectedName: 'MouseWheelOptions',
+        },
+      ],
       [
         'Method Tracing.start() options',
         {