From f484b833ae7139ac3de34ffb4b64c0276abed91a Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Fri, 17 Mar 2023 12:48:07 -0700
Subject: [PATCH] docs: update getByLabel docs to mention aria attributes
 (#21765)

References #21624.
---
 docs/src/api/params.md                    | 10 ++++++--
 packages/playwright-core/types/types.d.ts | 28 ++++++++++++++++-------
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index 36a61f79ef..22f3527198 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -1430,34 +1430,40 @@ await page.GetByAltText("Playwright logo").ClickAsync();
 
 ## template-locator-get-by-label-text
 
-Allows locating input elements by the text of the associated label.
+Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the `aria-label` attribute.
 
 **Usage**
 
-For example, this method will find the input by label text "Password" in the following DOM:
+For example, this method will find inputs by label "Username" and "Password" in the following DOM:
 
 ```html
+<input aria-label="Username">
 <label for="password-input">Password:</label>
 <input id="password-input">
 ```
 
 ```js
+await page.getByLabel('Username').fill('john');
 await page.getByLabel('Password').fill('secret');
 ```
 
 ```java
+page.getByLabel("Username").fill("john");
 page.getByLabel("Password").fill("secret");
 ```
 
 ```python async
+await page.get_by_label("Username").fill("john")
 await page.get_by_label("Password").fill("secret")
 ```
 
 ```python sync
+page.get_by_label("Username").fill("john")
 page.get_by_label("Password").fill("secret")
 ```
 
 ```csharp
+await page.GetByLabel("Username").FillAsync("john");
 await page.GetByLabel("Password").FillAsync("secret");
 ```
 
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 1d4f2bb8db..85b02db334 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -2482,18 +2482,21 @@ export interface Page {
   }): Locator;
 
   /**
-   * Allows locating input elements by the text of the associated label.
+   * Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
+   * `aria-label` attribute.
    *
    * **Usage**
    *
-   * For example, this method will find the input by label text "Password" in the following DOM:
+   * For example, this method will find inputs by label "Username" and "Password" in the following DOM:
    *
    * ```html
+   * <input aria-label="Username">
    * <label for="password-input">Password:</label>
    * <input id="password-input">
    * ```
    *
    * ```js
+   * await page.getByLabel('Username').fill('john');
    * await page.getByLabel('Password').fill('secret');
    * ```
    *
@@ -5900,18 +5903,21 @@ export interface Frame {
   }): Locator;
 
   /**
-   * Allows locating input elements by the text of the associated label.
+   * Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
+   * `aria-label` attribute.
    *
    * **Usage**
    *
-   * For example, this method will find the input by label text "Password" in the following DOM:
+   * For example, this method will find inputs by label "Username" and "Password" in the following DOM:
    *
    * ```html
+   * <input aria-label="Username">
    * <label for="password-input">Password:</label>
    * <input id="password-input">
    * ```
    *
    * ```js
+   * await page.getByLabel('Username').fill('john');
    * await page.getByLabel('Password').fill('secret');
    * ```
    *
@@ -10855,18 +10861,21 @@ export interface Locator {
   }): Locator;
 
   /**
-   * Allows locating input elements by the text of the associated label.
+   * Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
+   * `aria-label` attribute.
    *
    * **Usage**
    *
-   * For example, this method will find the input by label text "Password" in the following DOM:
+   * For example, this method will find inputs by label "Username" and "Password" in the following DOM:
    *
    * ```html
+   * <input aria-label="Username">
    * <label for="password-input">Password:</label>
    * <input id="password-input">
    * ```
    *
    * ```js
+   * await page.getByLabel('Username').fill('john');
    * await page.getByLabel('Password').fill('secret');
    * ```
    *
@@ -16692,18 +16701,21 @@ export interface FrameLocator {
   }): Locator;
 
   /**
-   * Allows locating input elements by the text of the associated label.
+   * Allows locating input elements by the text of the associated `<label>` or `aria-labelledby` element, or by the
+   * `aria-label` attribute.
    *
    * **Usage**
    *
-   * For example, this method will find the input by label text "Password" in the following DOM:
+   * For example, this method will find inputs by label "Username" and "Password" in the following DOM:
    *
    * ```html
+   * <input aria-label="Username">
    * <label for="password-input">Password:</label>
    * <input id="password-input">
    * ```
    *
    * ```js
+   * await page.getByLabel('Username').fill('john');
    * await page.getByLabel('Password').fill('secret');
    * ```
    *