From c1d7be379b9d0dbf702600afb59f43460b0578bd Mon Sep 17 00:00:00 2001
From: Tim van der Lippe <TimvdLippe@users.noreply.github.com>
Date: Fri, 12 Jun 2020 06:32:59 +0100
Subject: [PATCH] docs(api): add copy-pasting text example to Mouse class
 (#6000)

There are numerous issues on the Puppeteer issue tracker about selecting and copy-pasting of text (#3252, #4954,  #423, #1366, #343) as well as several StackOverflow questions:

- https://stackoverflow.com/questions/57101467/how-do-you-paste-text-using-puppeteer
- https://stackoverflow.com/questions/49131516/how-to-copy-text-from-browser-clipboard-using-puppeteer-in-nodejs
- https://stackoverflow.com/questions/60158746/how-do-i-access-the-contents-of-the-clipboard-from-within-a-headless-puppeteer-t
- https://stackoverflow.com/questions/56306153/domexception-on-calling-navigator-clipboard-readtext

I propose we include this commonly-asked question in the main documentation.

Fixes #3252.
Fixes #4954.
---
 docs/api.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/api.md b/docs/api.md
index 1b22242e..98487abf 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -185,6 +185,7 @@
   * [keyboard.type(text[, options])](#keyboardtypetext-options)
   * [keyboard.up(key)](#keyboardupkey)
 - [class: Mouse](#class-mouse)
+  * [Selecting text and moving the mouse](#selecting-text-and-moving-the-mouse)
   * [mouse.click(x, y[, options])](#mouseclickx-y-options)
   * [mouse.down([options])](#mousedownoptions)
   * [mouse.move(x, y[, options])](#mousemovex-y-options)
@@ -2487,6 +2488,45 @@ await page.mouse.move(0, 0);
 await page.mouse.up();
 ```
 
+#### Selecting text and moving the mouse
+
+Note that the mouse events trigger synthetic `MouseEvent`s.
+This means that it does not fully replicate the functionality of what a normal user would be able to do with their mouse.
+
+For example, dragging and selecting text is not possible using `page.mouse`.
+Instead, you can use the [`DocumentOrShadowRoot.getSelection()`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection) functionality implemented in the platform.
+
+For example, if you want to select all content between nodes:
+```js
+await page.evaluate((from, to) => {
+  const selection = from.getRootNode().getSelection();
+  const range = document.createRange();
+  range.setStartBefore(from);
+  range.setEndAfter(to);
+  selection.removeAllRanges();
+  selection.addRange(range);
+}, fromJSHandle, toJSHandle);
+```
+
+If you then would want to copy-paste your selection, you can use the clipboard api:
+
+```js
+// The clipboard api does not allow you to copy, unless the tab is focused.
+await page.bringToFront();
+await page.evaluate(() => {
+  // Copy the selected content to the clipboard
+  document.execCommand('copy');
+  // Obtain the content of the clipboard as a string
+  return navigator.clipboard.readText();
+});
+```
+
+Note that if you want access to the clipboard API, you have to give it permission to do so:
+
+```js
+await browser.defaultBrowserContext().overridePermissions('<your origin>', ['clipboard-read', 'clipboard-write']);
+```
+
 #### mouse.click(x, y[, options])
 - `x` <[number]>
 - `y` <[number]>