api(keyboard.insertText): renamed from sendCharaters (#1370)

docs/api.md

@@ -3051,7 +3051,7 @@ const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.
 
 Keyboard provides an api for managing a virtual keyboard. The high level api is [`keyboard.type`](#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
 
-For finer control, you can use [`keyboard.down`](#keyboarddownkey-options), [`keyboard.up`](#keyboardupkey), and [`keyboard.sendCharacters`](#keyboardsendcharacterstext) to manually fire events as if they were generated from a real keyboard.
+For finer control, you can use [`keyboard.down`](#keyboarddownkey-options), [`keyboard.up`](#keyboardupkey), and [`keyboard.insertText`](#keyboardsendcharacterstext) to manually fire events as if they were generated from a real keyboard.
 
 An example of holding down `Shift` in order to select and delete some text:
 ```js
@@ -3078,8 +3078,8 @@ await page.keyboard.up('Shift');
 
 <!-- GEN:toc -->
 - [keyboard.down(key[, options])](#keyboarddownkey-options)
+- [keyboard.insertText(text)](#keyboardinserttexttext)
 - [keyboard.press(key[, options])](#keyboardpresskey-options)
-- [keyboard.sendCharacters(text)](#keyboardsendcharacterstext)
 - [keyboard.type(text[, options])](#keyboardtypetext-options)
 - [keyboard.up(key)](#keyboardupkey)
 <!-- GEN:stop -->
@@ -3100,6 +3100,18 @@ After the key is pressed once, subsequent calls to [`keyboard.down`](#keyboarddo
 
 > **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.
 
+#### keyboard.insertText(text)
+- `text` <[string]> Sets input to the specified text value.
+- returns: <[Promise]>
+
+Dispatches only `input` event, does not emit the `keydown`, `keyup` or `keypress` events.
+
+```js
+page.keyboard.insertText('嗨');
+```
+
+> **NOTE** Modifier keys DO NOT effect `keyboard.insertText`. Holding down `Shift` will not type the text in upper case.
+
 #### keyboard.press(key[, options])
 - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names.
 - `options` <[Object]>
@@ -3113,18 +3125,6 @@ If `key` is a single character and no modifier keys besides `Shift` are being he
 
 Shortcut for [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey).
 
-#### keyboard.sendCharacters(text)
-- `text` <[string]> Characters to send into the page.
-- returns: <[Promise]>
-
-Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
-
-```js
-page.keyboard.sendCharacters('嗨');
-```
-
-> **NOTE** Modifier keys DO NOT effect `keyboard.sendCharacters`. Holding down `Shift` will not type the text in upper case.
-
 #### keyboard.type(text[, options])
 - `text` <[string]> A text to type into a focused element.
 - `options` <[Object]>

src/dom.ts

@@ -306,7 +306,7 @@ export class ElementHandle<T extends Node = Node> extends js.JSHandle<T> {
       if (error)
         throw new Error(error);
       if (value)
-        await this._page.keyboard.sendCharacters(value);
+        await this._page.keyboard.insertText(value);
       else
         await this._page.keyboard.press('Delete');
     }, options, true);

src/input.ts

@@ -126,7 +126,7 @@ export class Keyboard {
     await this._raw.keyup(this._pressedModifiers, description.code, description.keyCode, description.keyCodeWithoutLocation, description.key, description.location);
   }
 
-  async sendCharacters(text: string) {
+  async insertText(text: string) {
     await this._raw.sendText(text);
   }
 
@@ -138,7 +138,7 @@ export class Keyboard {
       } else {
         if (delay)
           await new Promise(f => setTimeout(f, delay));
-        await this.sendCharacters(char);
+        await this.insertText(char);
       }
     }
   }

test/keyboard.spec.js

@@ -72,12 +72,26 @@ module.exports.describe = function({testRunner, expect, FFOX, CHROMIUM, WEBKIT,
     it('should send a character with sendCharacter', async({page, server}) => {
       await page.goto(server.PREFIX + '/input/textarea.html');
       await page.focus('textarea');
-      await page.keyboard.sendCharacters('嗨');
+      await page.keyboard.insertText('嗨');
       expect(await page.evaluate(() => document.querySelector('textarea').value)).toBe('嗨');
       await page.evaluate(() => window.addEventListener('keydown', e => e.preventDefault(), true));
-      await page.keyboard.sendCharacters('a');
+      await page.keyboard.insertText('a');
       expect(await page.evaluate(() => document.querySelector('textarea').value)).toBe('嗨a');
     });
+    it('insertText should only emit input event', async({page, server}) => {
+      await page.goto(server.PREFIX + '/input/textarea.html');
+      await page.focus('textarea');
+      page.on('console', m => console.log(m.text()));
+      await page.evaluate(() => {
+        window.events = [];
+        document.addEventListener('keydown', e => events.push(e.type));
+        document.addEventListener('keyup', e => events.push(e.type));
+        document.addEventListener('keypress', e => events.push(e.type));
+        document.addEventListener('input', e => events.push(e.type));
+      });
+      await page.keyboard.insertText('hello world');
+      expect(await page.evaluate('window.events')).toEqual(['input']);
+    });
     it.fail(FFOX)('should report shiftKey', async({page, server}) => {
       await page.goto(server.PREFIX + '/input/keyboard.html');
       const keyboard = page.keyboard;