diff --git a/docs/api.md b/docs/api.md index 17934bad435..83dcc3d929c 100644 --- a/docs/api.md +++ b/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) diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index ad1da812a12..4f955cbdb80 100644 --- a/new-docs/puppeteer.md +++ b/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) | | diff --git a/new-docs/puppeteer.mouse.md b/new-docs/puppeteer.mouse.md index 8a5044cab00..0b372a92b05 100644 --- a/new-docs/puppeteer.mouse.md +++ b/new-docs/puppeteer.mouse.md @@ -81,4 +81,5 @@ await browser.defaultBrowserContext().overridePermissions( | [down(options)](./puppeteer.mouse.down.md) | | Dispatches a mousedown event. | | [move(x, y, options)](./puppeteer.mouse.move.md) | | Dispatches a mousemove event. | | [up(options)](./puppeteer.mouse.up.md) | | Dispatches a mouseup event. | +| [wheel(options)](./puppeteer.mouse.wheel.md) | | Dispatches a mousewheel event. | diff --git a/new-docs/puppeteer.mouse.wheel.md b/new-docs/puppeteer.mouse.wheel.md new file mode 100644 index 00000000000..0b5aab75f74 --- /dev/null +++ b/new-docs/puppeteer.mouse.wheel.md @@ -0,0 +1,42 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [Mouse](./puppeteer.mouse.md) > [wheel](./puppeteer.mouse.wheel.md) + +## Mouse.wheel() method + +Dispatches a `mousewheel` event. + +Signature: + +```typescript +wheel(options?: MouseWheelOptions): Promise; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| options | [MouseWheelOptions](./puppeteer.mousewheeloptions.md) | Optional: MouseWheelOptions. | + +Returns: + +Promise<void> + +## 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 }) + +``` + diff --git a/new-docs/puppeteer.mousewheeloptions.deltax.md b/new-docs/puppeteer.mousewheeloptions.deltax.md new file mode 100644 index 00000000000..1b060aef695 --- /dev/null +++ b/new-docs/puppeteer.mousewheeloptions.deltax.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [MouseWheelOptions](./puppeteer.mousewheeloptions.md) > [deltaX](./puppeteer.mousewheeloptions.deltax.md) + +## MouseWheelOptions.deltaX property + +Signature: + +```typescript +deltaX?: number; +``` diff --git a/new-docs/puppeteer.mousewheeloptions.deltay.md b/new-docs/puppeteer.mousewheeloptions.deltay.md new file mode 100644 index 00000000000..5cfb6f6c46c --- /dev/null +++ b/new-docs/puppeteer.mousewheeloptions.deltay.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [MouseWheelOptions](./puppeteer.mousewheeloptions.md) > [deltaY](./puppeteer.mousewheeloptions.deltay.md) + +## MouseWheelOptions.deltaY property + +Signature: + +```typescript +deltaY?: number; +``` diff --git a/new-docs/puppeteer.mousewheeloptions.md b/new-docs/puppeteer.mousewheeloptions.md new file mode 100644 index 00000000000..7ff07c3a7ad --- /dev/null +++ b/new-docs/puppeteer.mousewheeloptions.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [MouseWheelOptions](./puppeteer.mousewheeloptions.md) + +## MouseWheelOptions interface + + +Signature: + +```typescript +export interface MouseWheelOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [deltaX](./puppeteer.mousewheeloptions.deltax.md) | number | | +| [deltaY](./puppeteer.mousewheeloptions.deltay.md) | number | | + diff --git a/src/common/Input.ts b/src/common/Input.ts index b395170a71b..30443c92c09 100644 --- a/src/common/Input.ts +++ b/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 { + 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', + }); + } } /** diff --git a/test/assets/input/wheel.html b/test/assets/input/wheel.html new file mode 100644 index 00000000000..3d093a993e7 --- /dev/null +++ b/test/assets/input/wheel.html @@ -0,0 +1,43 @@ + + + + + + Element: wheel event - Scaling_an_element_via_the_wheel - code sample + + +
Scale me with your mouse wheel.
+ + + diff --git a/test/mouse.spec.ts b/test/mouse.spec.ts index 1cca238d71c..97aae6b9011 100644 --- a/test/mouse.spec.ts +++ b/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(); diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index 83dc1c5bf66..b767190a2c4 100644 --- a/utils/doclint/check_public_api/index.js +++ b/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', {