feat: replace Locator.type with Locator.pressSequentially (#26624)

Also deprecate `Locator.type`, `Frame.type`, `Page.type` and
`ElementHandle.type`, but not `Keyboard.type`.

References #24614.

docs/src/api/class-elementhandle.md

@@ -513,7 +513,7 @@ This method waits for [actionability](../actionability.md) checks, focuses the e
 
 If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled instead.
 
-To send fine-grained keyboard events, use [`method: ElementHandle.type`].
+To send fine-grained keyboard events, use [`method: Keyboard.type`].
 
 ### param: ElementHandle.fill.value
 * since: v1.8
@@ -977,6 +977,7 @@ Returns the `node.textContent`.
 
 ## async method: ElementHandle.type
 * since: v1.8
+* deprecated: Use locator-based [`method: Locator.pressSequentially`] instead. Read more about [locators](../locators.md).
 
 Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
 
@@ -984,63 +985,6 @@ To press a special key, like `Control` or `ArrowDown`, use [`method: ElementHand
 
 **Usage**
 
-```js
-await elementHandle.type('Hello'); // Types instantly
-await elementHandle.type('World', { delay: 100 }); // Types slower, like a user
-```
-
-```java
-elementHandle.type("Hello"); // Types instantly
-elementHandle.type("World", new ElementHandle.TypeOptions().setDelay(100)); // Types slower, like a user
-```
-
-```python async
-await element_handle.type("hello") # types instantly
-await element_handle.type("world", delay=100) # types slower, like a user
-```
-
-```python sync
-element_handle.type("hello") # types instantly
-element_handle.type("world", delay=100) # types slower, like a user
-```
-
-```csharp
-await elementHandle.TypeAsync("Hello"); // Types instantly
-await elementHandle.TypeAsync("World", new() { Delay = 100 }); // Types slower, like a user
-```
-
-An example of typing into a text field and then submitting the form:
-
-```js
-const elementHandle = await page.$('input');
-await elementHandle.type('some text');
-await elementHandle.press('Enter');
-```
-
-```java
-ElementHandle elementHandle = page.querySelector("input");
-elementHandle.type("some text");
-elementHandle.press("Enter");
-```
-
-```python async
-element_handle = await page.query_selector("input")
-await element_handle.type("some text")
-await element_handle.press("Enter")
-```
-
-```python sync
-element_handle = page.query_selector("input")
-element_handle.type("some text")
-element_handle.press("Enter")
-```
-
-```csharp
-var elementHandle = await page.QuerySelectorAsync("input");
-await elementHandle.TypeAsync("some text");
-await elementHandle.PressAsync("Enter");
-```
-
 ### param: ElementHandle.type.text
 * since: v1.8
 - `text` <[string]>

docs/src/api/class-frame.md

@@ -1733,7 +1733,7 @@ Returns the page title.
 
 ## async method: Frame.type
 * since: v1.8
-* discouraged: Use locator-based [`method: Locator.type`] instead. Read more about [locators](../locators.md).
+* deprecated: Use locator-based [`method: Locator.pressSequentially`] instead. Read more about [locators](../locators.md).
 
 Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `frame.type` can be used to
 send fine-grained keyboard events. To fill values in form fields, use [`method: Frame.fill`].
@@ -1742,33 +1742,6 @@ To press a special key, like `Control` or `ArrowDown`, use [`method: Keyboard.pr
 
 **Usage**
 
-```js
-await frame.type('#mytextarea', 'Hello'); // Types instantly
-await frame.type('#mytextarea', 'World', { delay: 100 }); // Types slower, like a user
-```
-
-```java
-// Types instantly
-frame.type("#mytextarea", "Hello");
-// Types slower, like a user
-frame.type("#mytextarea", "World", new Frame.TypeOptions().setDelay(100));
-```
-
-```python async
-await frame.type("#mytextarea", "hello") # types instantly
-await frame.type("#mytextarea", "world", delay=100) # types slower, like a user
-```
-
-```python sync
-frame.type("#mytextarea", "hello") # types instantly
-frame.type("#mytextarea", "world", delay=100) # types slower, like a user
-```
-
-```csharp
-await frame.TypeAsync("#mytextarea", "hello"); // types instantly
-await frame.TypeAsync("#mytextarea", "world", new() { Delay = 100 }); // types slower, like a user
-```
-
 ### param: Frame.type.selector = %%-input-selector-%%
 * since: v1.8
 

docs/src/api/class-locator.md

@@ -913,7 +913,7 @@ This method waits for [actionability](../actionability.md) checks, focuses the e
 
 If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be filled instead.
 
-To send fine-grained keyboard events, use [`method: Locator.type`].
+To send fine-grained keyboard events, use [`method: Locator.pressSequentially`].
 
 ### param: Locator.fill.value
 * since: v1.14
@@ -1693,6 +1693,99 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
 ### option: Locator.press.timeout = %%-input-timeout-js-%%
 * since: v1.14
 
+
+## async method: Locator.pressSequentially
+* since: v1.38
+
+:::tip
+In most cases, you should use [`method: Locator.fill`] instead. You only need to press keys one by one if there is special keyboard handling on the page.
+:::
+
+Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
+
+To press a special key, like `Control` or `ArrowDown`, use [`method: Locator.press`].
+
+**Usage**
+
+```js
+await locator.pressSequentially('Hello'); // Types instantly
+await locator.pressSequentially('World', { delay: 100 }); // Types slower, like a user
+```
+
+```java
+locator.pressSequentially("Hello"); // Types instantly
+locator.pressSequentially("World", new Locator.pressSequentiallyOptions().setDelay(100)); // Types slower, like a user
+```
+
+```python async
+await locator.press_sequentially("hello") # types instantly
+await locator.press_sequentially("world", delay=100) # types slower, like a user
+```
+
+```python sync
+locator.press_sequentially("hello") # types instantly
+locator.press_sequentially("world", delay=100) # types slower, like a user
+```
+
+```csharp
+await locator.PressSequentiallyAsync("Hello"); // Types instantly
+await locator.PressSequentiallyAsync("World", new() { Delay = 100 }); // Types slower, like a user
+```
+
+An example of typing into a text field and then submitting the form:
+
+```js
+const locator = page.getByLabel('Password');
+await locator.pressSequentially('my password');
+await locator.press('Enter');
+```
+
+```java
+Locator locator = page.getByLabel("Password");
+locator.pressSequentially("my password");
+locator.press("Enter");
+```
+
+```python async
+locator = page.get_by_label("Password")
+await locator.press_sequentially("my password")
+await locator.press("Enter")
+```
+
+```python sync
+locator = page.get_by_label("Password")
+locator.press_sequentially("my password")
+locator.press("Enter")
+```
+
+```csharp
+var locator = page.GetByLabel("Password");
+await locator.PressSequentiallyAsync("my password");
+await locator.PressAsync("Enter");
+```
+
+### param: Locator.pressSequentially.text
+* since: v1.38
+- `text` <[string]>
+
+String of characters to sequentially press into a focused element.
+
+### option: Locator.pressSequentially.delay
+* since: v1.38
+- `delay` <[float]>
+
+Time to wait between key presses in milliseconds. Defaults to 0.
+
+### option: Locator.pressSequentially.noWaitAfter = %%-input-no-wait-after-%%
+* since: v1.38
+
+### option: Locator.pressSequentially.timeout = %%-input-timeout-%%
+* since: v1.38
+
+### option: Locator.pressSequentially.timeout = %%-input-timeout-js-%%
+* since: v1.38
+
+
 ## async method: Locator.screenshot
 * since: v1.14
 - returns: <[Buffer]>
@@ -2138,10 +2231,7 @@ Returns the [`node.textContent`](https://developer.mozilla.org/en-US/docs/Web/AP
 
 ## async method: Locator.type
 * since: v1.14
-
+* deprecated: In most cases, you should use [`method: Locator.fill`] instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use [`method: Locator.pressSequentially`].
-:::tip
-In most cases, you should use [`method: Locator.fill`] instead. You only need to type characters if there is special keyboard handling on the page.
-:::
 
 Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
 
@@ -2149,63 +2239,6 @@ To press a special key, like `Control` or `ArrowDown`, use [`method: Locator.pre
 
 **Usage**
 
-```js
-await element.type('Hello'); // Types instantly
-await element.type('World', { delay: 100 }); // Types slower, like a user
-```
-
-```java
-element.type("Hello"); // Types instantly
-element.type("World", new Locator.TypeOptions().setDelay(100)); // Types slower, like a user
-```
-
-```python async
-await element.type("hello") # types instantly
-await element.type("world", delay=100) # types slower, like a user
-```
-
-```python sync
-element.type("hello") # types instantly
-element.type("world", delay=100) # types slower, like a user
-```
-
-```csharp
-await element.TypeAsync("Hello"); // Types instantly
-await element.TypeAsync("World", new() { Delay = 100 }); // Types slower, like a user
-```
-
-An example of typing into a text field and then submitting the form:
-
-```js
-const element = page.getByLabel('Password');
-await element.type('my password');
-await element.press('Enter');
-```
-
-```java
-Locator element = page.getByLabel("Password");
-element.type("my password");
-element.press("Enter");
-```
-
-```python async
-element = page.get_by_label("Password")
-await element.type("my password")
-await element.press("Enter")
-```
-
-```python sync
-element = page.get_by_label("Password")
-element.type("my password")
-element.press("Enter")
-```
-
-```csharp
-var element = page.GetByLabel("Password");
-await element.TypeAsync("my password");
-await element.PressAsync("Enter");
-```
-
 ### param: Locator.type.text
 * since: v1.14
 - `text` <[string]>

docs/src/api/class-page.md

@@ -3772,7 +3772,7 @@ Returns the page's title.
 
 ## async method: Page.type
 * since: v1.8
-* discouraged: Use locator-based [`method: Locator.type`] instead. Read more about [locators](../locators.md).
+* deprecated: Use locator-based [`method: Locator.pressSequentially`] instead. Read more about [locators](../locators.md).
 
 Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `page.type` can be used to send
 fine-grained keyboard events. To fill values in form fields, use [`method: Page.fill`].
@@ -3781,33 +3781,6 @@ To press a special key, like `Control` or `ArrowDown`, use [`method: Keyboard.pr
 
 **Usage**
 
-```js
-await page.type('#mytextarea', 'Hello'); // Types instantly
-await page.type('#mytextarea', 'World', { delay: 100 }); // Types slower, like a user
-```
-
-```java
-// Types instantly
-page.type("#mytextarea", "Hello");
-// Types slower, like a user
-page.type("#mytextarea", "World", new Page.TypeOptions().setDelay(100));
-```
-
-```python async
-await page.type("#mytextarea", "hello") # types instantly
-await page.type("#mytextarea", "world", delay=100) # types slower, like a user
-```
-
-```python sync
-page.type("#mytextarea", "hello") # types instantly
-page.type("#mytextarea", "world", delay=100) # types slower, like a user
-```
-
-```csharp
-await page.TypeAsync("#mytextarea", "hello"); // types instantly
-await page.TypeAsync("#mytextarea", "world", new() { Delay = 100 }); // types slower, like a user
-```
-
 ### param: Page.type.selector = %%-input-selector-%%
 * since: v1.8
 

docs/src/input.md

@@ -365,30 +365,30 @@ await page.GetByRole(AriaRole.Button).DispatchEventAsync("click");
 Most of the time, you should input text with [`method: Locator.fill`]. See the [Text input](#text-input) section above. You only need to type characters if there is special keyboard handling on the page.
 :::
 
-Type into the field character by character, as if it was a user with a real keyboard with [`method: Locator.type`].
+Type into the field character by character, as if it was a user with a real keyboard with [`method: Locator.pressSequentially`].
 
 ```js
-// Type character by character
+// Press keys one by one
-await page.locator('#area').type('Hello World!');
+await page.locator('#area').pressSequentially('Hello World!');
 ```
 
 ```java
-// Type character by character
+// Press keys one by one
-page.locator("#area").type("Hello World!");
+page.locator("#area").pressSequentially("Hello World!");
 ```
 
 ```python async
-# Type character by character
+# Press keys one by one
-await page.locator('#area').type('Hello World!')
+await page.locator('#area').pressSequentially('Hello World!')
 ```
 
 ```python sync
-# Type character by character
+# Press keys one by one
-page.locator('#area').type('Hello World!')
+page.locator('#area').pressSequentially('Hello World!')
 ```
 
 ```csharp
-// Type character by character
+// Press keys one by one
 await page.Locator("#area").TypeAsync("Hello World!");
 ```
 

packages/playwright-core/src/client/locator.ts

@@ -315,6 +315,10 @@ export class Locator implements api.Locator {
     return this._frame.type(this._selector, text, { strict: true, ...options });
   }
 
+  async pressSequentially(text: string, options: channels.ElementHandleTypeOptions = {}): Promise<void> {
+    return this.type(text, options);
+  }
+
   async uncheck(options: channels.ElementHandleUncheckOptions = {}) {
     return this._frame.uncheck(this._selector, { strict: true, ...options });
   }

packages/playwright-core/types/types.d.ts

@@ -4103,9 +4103,6 @@ export interface Page {
   title(): Promise<string>;
 
   /**
-   * **NOTE** Use locator-based [locator.type(text[, options])](https://playwright.dev/docs/api/class-locator#locator-type)
-   * instead. Read more about [locators](https://playwright.dev/docs/locators).
-   *
    * Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `page.type` can be used to
    * send fine-grained keyboard events. To fill values in form fields, use
    * [page.fill(selector, value[, options])](https://playwright.dev/docs/api/class-page#page-fill).
@@ -4114,12 +4111,9 @@ export interface Page {
    * [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press).
    *
    * **Usage**
-   *
+   * @deprecated Use locator-based
-   * ```js
+   * [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially)
-   * await page.type('#mytextarea', 'Hello'); // Types instantly
+   * instead. Read more about [locators](https://playwright.dev/docs/locators).
-   * await page.type('#mytextarea', 'World', { delay: 100 }); // Types slower, like a user
-   * ```
-   *
    * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
    * used.
    * @param text A text to type into a focused element.
@@ -7121,9 +7115,6 @@ export interface Frame {
   title(): Promise<string>;
 
   /**
-   * **NOTE** Use locator-based [locator.type(text[, options])](https://playwright.dev/docs/api/class-locator#locator-type)
-   * instead. Read more about [locators](https://playwright.dev/docs/locators).
-   *
    * Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. `frame.type` can be used
    * to send fine-grained keyboard events. To fill values in form fields, use
    * [frame.fill(selector, value[, options])](https://playwright.dev/docs/api/class-frame#frame-fill).
@@ -7132,12 +7123,9 @@ export interface Frame {
    * [keyboard.press(key[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-press).
    *
    * **Usage**
-   *
+   * @deprecated Use locator-based
-   * ```js
+   * [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially)
-   * await frame.type('#mytextarea', 'Hello'); // Types instantly
+   * instead. Read more about [locators](https://playwright.dev/docs/locators).
-   * await frame.type('#mytextarea', 'World', { delay: 100 }); // Types slower, like a user
-   * ```
-   *
    * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be
    * used.
    * @param text A text to type into a focused element.
@@ -9680,7 +9668,7 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
    * instead.
    *
    * To send fine-grained keyboard events, use
-   * [elementHandle.type(text[, options])](https://playwright.dev/docs/api/class-elementhandle#element-handle-type).
+   * [keyboard.type(text[, options])](https://playwright.dev/docs/api/class-keyboard#keyboard-type).
    * @param value Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
    * @param options
    */
@@ -10279,20 +10267,9 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
    * [elementHandle.press(key[, options])](https://playwright.dev/docs/api/class-elementhandle#element-handle-press).
    *
    * **Usage**
-   *
+   * @deprecated Use locator-based
-   * ```js
+   * [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially)
-   * await elementHandle.type('Hello'); // Types instantly
+   * instead. Read more about [locators](https://playwright.dev/docs/locators).
-   * await elementHandle.type('World', { delay: 100 }); // Types slower, like a user
-   * ```
-   *
-   * An example of typing into a text field and then submitting the form:
-   *
-   * ```js
-   * const elementHandle = await page.$('input');
-   * await elementHandle.type('some text');
-   * await elementHandle.press('Enter');
-   * ```
-   *
    * @param text A text to type into a focused element.
    * @param options
    */
@@ -11147,7 +11124,7 @@ export interface Locator {
    * instead.
    *
    * To send fine-grained keyboard events, use
-   * [locator.type(text[, options])](https://playwright.dev/docs/api/class-locator#locator-type).
+   * [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
    * @param value Value to set for the `<input>`, `<textarea>` or `[contenteditable]` element.
    * @param options
    */
@@ -11988,6 +11965,57 @@ export interface Locator {
     timeout?: number;
   }): Promise<void>;
 
+  /**
+   * **NOTE** In most cases, you should use
+   * [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
+   * to press keys one by one if there is special keyboard handling on the page.
+   *
+   * Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the
+   * text.
+   *
+   * To press a special key, like `Control` or `ArrowDown`, use
+   * [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press).
+   *
+   * **Usage**
+   *
+   * ```js
+   * await locator.pressSequentially('Hello'); // Types instantly
+   * await locator.pressSequentially('World', { delay: 100 }); // Types slower, like a user
+   * ```
+   *
+   * An example of typing into a text field and then submitting the form:
+   *
+   * ```js
+   * const locator = page.getByLabel('Password');
+   * await locator.pressSequentially('my password');
+   * await locator.press('Enter');
+   * ```
+   *
+   * @param text String of characters to sequentially press into a focused element.
+   * @param options
+   */
+  pressSequentially(text: string, options?: {
+    /**
+     * Time to wait between key presses in milliseconds. Defaults to 0.
+     */
+    delay?: number;
+
+    /**
+     * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
+     * can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
+     * navigating to inaccessible pages. Defaults to `false`.
+     */
+    noWaitAfter?: boolean;
+
+    /**
+     * Maximum time in milliseconds. Defaults to `0` - no timeout. The default value can be changed via `actionTimeout`
+     * option in the config, or by using the
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
+    timeout?: number;
+  }): Promise<void>;
+
   /**
    * Take a screenshot of the element matching the locator.
    *
@@ -12381,10 +12409,6 @@ export interface Locator {
   }): Promise<null|string>;
 
   /**
-   * **NOTE** In most cases, you should use
-   * [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
-   * to type characters if there is special keyboard handling on the page.
-   *
    * Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the
    * text.
    *
@@ -12392,20 +12416,10 @@ export interface Locator {
    * [locator.press(key[, options])](https://playwright.dev/docs/api/class-locator#locator-press).
    *
    * **Usage**
-   *
+   * @deprecated In most cases, you should use
-   * ```js
+   * [locator.fill(value[, options])](https://playwright.dev/docs/api/class-locator#locator-fill) instead. You only need
-   * await element.type('Hello'); // Types instantly
+   * to press keys one by one if there is special keyboard handling on the page - in this case use
-   * await element.type('World', { delay: 100 }); // Types slower, like a user
+   * [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
-   * ```
-   *
-   * An example of typing into a text field and then submitting the form:
-   *
-   * ```js
-   * const element = page.getByLabel('Password');
-   * await element.type('my password');
-   * await element.press('Enter');
-   * ```
-   *
    * @param text A text to type into a focused element.
    * @param options
    */

tests/page/locator-misc-2.spec.ts

@@ -94,6 +94,12 @@ it('should type', async ({ page }) => {
   expect(await page.$eval('input', input => input.value)).toBe('hello');
 });
 
+it('should pressSequentially', async ({ page }) => {
+  await page.setContent(`<input type='text' />`);
+  await page.locator('input').pressSequentially('hello');
+  expect(await page.$eval('input', input => input.value)).toBe('hello');
+});
+
 it('should take screenshot', async ({ page, server, browserName, headless, isAndroid, mode }) => {
   it.skip(browserName === 'firefox' && !headless);
   it.skip(isAndroid, 'Different dpr. Remove after using 1x scale for screenshots.');