microsoft/playwright
1
1
Fork 0
mirror of https://github.com/microsoft/playwright.git synced 2025-01-05 19:04:43 +03:00
Code Issues Projects Releases Wiki Activity

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

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

References #24614.
This commit is contained in:
Dmitry Gozman 2023-08-22 15:21:00 -07:00 committed by GitHub
parent 65aa062ea1
commit c4e79eb6ed
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 185 additions and 238 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/src/api/class-elementhandle.md
View File

@ -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]>

29
docs/src/api/class-frame.md
View File

@ -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

157
docs/src/api/class-locator.md
View File

@ -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
:::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.
:::
* 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`].
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]>

29
docs/src/api/class-page.md
View File

@ -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

20
docs/src/input.md
View File

@ -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
await page.locator('#area').type('Hello World!');
// Press keys one by one
await page.locator('#area').pressSequentially('Hello World!');
```
```java
// Type character by character
page.locator("#area").type("Hello World!");
// Press keys one by one
page.locator("#area").pressSequentially("Hello World!");
```
```python async
# Type character by character
await page.locator('#area').type('Hello World!')
# Press keys one by one
await page.locator('#area').pressSequentially('Hello World!')
```
```python sync
# Type character by character
page.locator('#area').type('Hello World!')
# Press keys one by one
page.locator('#area').pressSequentially('Hello World!')
```
```csharp
// Type character by character
// Press keys one by one
await page.Locator("#area").TypeAsync("Hello World!");
```

4
packages/playwright-core/src/client/locator.ts
View File

@ -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 });
}

118
packages/playwright-core/types/types.d.ts vendored
View File

@ -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**
*
* ```js
* await page.type('#mytextarea', 'Hello'); // Types instantly
* await page.type('#mytextarea', 'World', { delay: 100 }); // Types slower, like a user
* ```
*
* @deprecated Use locator-based
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
* @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**
*
* ```js
* await frame.type('#mytextarea', 'Hello'); // Types instantly
* await frame.type('#mytextarea', 'World', { delay: 100 }); // Types slower, like a user
* ```
*
* @deprecated Use locator-based
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
* @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**
*
* ```js
* await elementHandle.type('Hello'); // Types instantly
* 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');
* ```
*
* @deprecated Use locator-based
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially)
* instead. Read more about [locators](https://playwright.dev/docs/locators).
* @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**
*
* ```js
* await element.type('Hello'); // Types instantly
* await element.type('World', { 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');
* ```
*
* @deprecated 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 - in this case use
* [locator.pressSequentially(text[, options])](https://playwright.dev/docs/api/class-locator#locator-press-sequentially).
* @param text A text to type into a focused element.
* @param options
*/

6
tests/page/locator-misc-2.spec.ts
View File

@ -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.');