feat: add wheel method to Mouse class

[christian-bromann]

fixes #1679

This patch adds a wheel command to the Mouse class. It behaves similar to other mouse commands like up or down and therefor requires a mouse.move(x, y) for targeting the element properly.

An example script to test this feature:

const puppeteer = require('./');

function sleep (ms = 3000) {
  return new Promise((resolve) => setTimeout(resolve, ms))
}

(async () => {
  const browser = await puppeteer.launch({
    headless: false,
  });
  const page = await browser.newPage();

  page.on('request', async (request) => {
    console.log(await request.headers());
  });

  await page.goto('https://mdn.mozillademos.org/en-US/docs/Web/API/Element/wheel_event$samples/Scaling_an_element_via_the_wheel?revision=1587366');
  await page.mouse.wheel({ y: 100 });
  await sleep(1000);

  const elem = await page.$('div');
  const boundingBox = await elem.boundingBox();
  console.log(boundingBox); // returns: { x: 342.5, y: 242.5, width: 115, height: 115 }

  await page.mouse.move(
    boundingBox.x + boundingBox.width / 2,
    boundingBox.y + boundingBox.height / 2
  );

  await page.mouse.wheel({ deltaY: -100 });
  console.log(await elem.boundingBox()); // returns: { x: 285, y: 185, width: 230, height: 230 }

  await sleep();
  await browser.close();
})();

[mathiasbynens]

Thanks for taking this on, Christian! Looking good so far.

Please document this in docs/api.md as well.

[googlebot]

All (the pull request submitter and all commit authors) CLAs are signed, but one or more commits were authored or co-authored by someone other than the pull request submitter.

We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that by leaving a comment that contains only @googlebot I consent. in this pull request.

Note to project maintainer: There may be cases where the author cannot leave a comment, or the comment is not properly detected as consent. In those cases, you can manually confirm consent of the commit author(s), and set the cla label to yes (if enabled on your project).

ℹ️ Googlers: Go here for more info.

[googlebot]

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

[christian-bromann]

@mathiasbynens @jackfranklin thanks for the comments. I addressed them and squashed all commits into one. Please let me know if anything is missing.

[jackfranklin]

Thanks for this! Sorry you have to write the docs in two places; hopefully we can finish the migration in the not-too-distant future.

[christian-bromann]

hopefully we can finish the migration in the not-too-distant future.

Sounds good! Let me know if there is anything I can do to help.

[christian-bromann]

@jackfranklin I need some help understanding why the docs test are failing:

DocLint Failures:
  1) [MarkDown] Method Mouse.wheel() options Object != MouseWheelOptions
  2) [MarkDown] Method Mouse.wheel() options has unexpected property 

They seem to scan the api.md file and complain about my change there:

+ #### mouse.wheel([options])
+ - `options` <[Object]>
+   - `deltaX` X delta in CSS pixels for mouse wheel event (default: 0).
+   - `deltaY` Y delta in CSS pixels for mouse wheel event (default: 0).
+ - returns: <[Promise]>
+ 
+ Dispatches a `mousewheel` event.

However I don't see any other TS interface options being used anywhere else in that document, e.g. for mouse.up():

#### mouse.up([options])
- `options` <[Object]>
  - `button` <"left"|"right"|"middle"> Defaults to `left`.
  - `clickCount` <[number]> defaults to 1. See [UIEvent.detail].
- returns: <[Promise]>

Dispatches a `mouseup` event.

Any advice?

[jackfranklin]

@christian-bromann ah, this is because the old system that's used to validate the docs doesn't understand the TypeScript source code as well as it should. Given we are migrating away from it I've not invested time into fixing it.

So what we do is we basically tell the old doc tool to ignore it, because it doesn't understand. You can see examples of this here: https://github.com/puppeteer/puppeteer/blob/main/utils/doclint/check_public_api/index.js#L746

This is not good, and another reason we're keen to get #6118 done!