docs: encourage using fill instead of type (#24616)

References #24614.

docs/src/api/class-locator.md

@@ -2136,6 +2136,10 @@ 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.
+:::
+
 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`].

docs/src/input.md

@@ -361,6 +361,10 @@ await page.GetByRole(AriaRole.Button).DispatchEventAsync("click");
 
 ## Type characters
 
+:::tip
+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`].
 
 ```js
@@ -390,10 +394,6 @@ await page.Locator("#area").TypeAsync("Hello World!");
 
 This method will emit all the necessary keyboard events, with all the `keydown`, `keyup`, `keypress` events in place. You can even specify the optional `delay` between the key presses to simulate real user behavior.
 
-:::note
-Most of the time, [`method: Page.fill`] will just work. You only need to type characters if there is special keyboard handling on the page.
-:::
-
 ## Keys and shortcuts
 
 ```js

docs/src/puppeteer-js.md

@@ -34,7 +34,7 @@ This guide describes migration to [Playwright Library](./library) and [Playwrigh
 | `await page.hover(selector)`                       | `await page.locator(selector).hover()`      |
 | `await page.select(selector, values)`              | `await page.locator(selector).selectOption(values)` |
 | `await page.tap(selector)`                         | `await page.locator(selector).tap()`        |
-| `await page.type(selector, ...)`                   | `await page.locator(selector).type(...)`<br/> Please also consider [`method: Locator.fill`] |
+| `await page.type(selector, ...)`                   | `await page.locator(selector).fill(...)` |
 | `await page.waitForFileChooser(...)`<br/>`await elementHandle.uploadFile(...)` | `await page.locator(selector).setInputFiles(...)` |
 | `await page.cookies([...urls])`                    | `await browserContext.cookies([urls])`      |
 | `await page.deleteCookie(...cookies)`              | `await browserContext.clearCookies()`       |

docs/src/writing-tests-js.md

@@ -106,12 +106,11 @@ learn more about them.
 | [`method: Locator.click`] | Click the element |
 | [`method: Locator.uncheck`] | Uncheck the input checkbox |
 | [`method: Locator.hover`] | Hover mouse over the element |
-| [`method: Locator.fill`] | Fill the form field (fast) |
+| [`method: Locator.fill`] | Fill the form field, input text |
 | [`method: Locator.focus`] | Focus the element |
 | [`method: Locator.press`] | Press single key |
 | [`method: Locator.setInputFiles`] | Pick files to upload |
 | [`method: Locator.selectOption`] | Select option in the drop down |
-| [`method: Locator.type`] | Type text character by character (slow) |
 
 ## Assertions
 

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

@@ -12316,6 +12316,10 @@ 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.
    *