Browser: Add getBy* APIs for frame, frameLocator and locator docs and locator.contentFrame

docs/sources/k6/next/javascript-api/k6-browser/frame/_index.md

@@ -24,6 +24,13 @@ Frame represents a single frame in a browser window. It can be a top-level frame
 | [focus(selector[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/focus/)                                                | Fetches an element with `selector` and focuses on it.                                                                                                 |
 | [frameElement()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/frameelement)                                                      | Returns the `frame`'s `element`.                                                                                                                      |
 | [getAttribute(selector, name[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getattribute/)                            | Returns the element attribute value for the given attribute name.                                                                                     |
+| [getByAltText(altText[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyalttext/)                                   | Returns a locator for elements with the specified `alt` attribute text.                                                                                    |
+| [getByLabel(text[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbylabel/)                                          | Returns a locator for form controls with the specified label text.                                                                                   |
+| [getByPlaceholder(placeholder[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyplaceholder/)                       | Returns a locator for input elements with the specified `placeholder` attribute text.                                                                                   |
+| [getByRole(role[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyrole/)                                            | Returns a locator for elements with the specified ARIA role.                                                                                    |
+| [getByTestId(testId)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytestid/)                                                 | Returns a locator for elements with the specified `data-testid` attribute.                                                                              |
+| [getByText(text[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytext/)                                            | Returns a locator for elements containing the specified text.                                                                                  |
+| [getByTitle(title[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytitle/)                                         | Returns a locator for elements with the specified `title` attribute.                                                                             |
 | [goto(url[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/goto/)                                                       | Navigates to the specified `url`.                                                                                                                     |
 | [hover(selector[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/hover/)                                                | Hovers over an element matching `selector`.                                                                                                           |
 | [innerHTML(selector[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/innerhtml/)                                        | Returns the `element.innerHTML`.                                                                                                                      |

docs/sources/k6/next/javascript-api/k6-browser/frame/getbyalttext.md

@@ -0,0 +1,136 @@
+---
+title: 'getByAltText(altText[, options])'
+description: 'Browser module: frame.getByAltText(altText[, options]) method'
+---
+
+{{< docs/shared source="k6" lookup="browser/getby-apis/getbyalttext-spec.md" version="<K6_VERSION>" >}}
+
+## Examples
+
+### Basic alt text matching
+
+Find and click an image by its alt text:
+
+<!-- md-k6:skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    ui: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.goto('https://quickpizza.grafana.com');
+
+    const logo = page.mainFrame().getByAltText('LOGO');
+    await logo.waitFor();
+
+    await logo.click();
+    await page.waitForLoadState();
+  } finally {
+    await page.close();
+  }
+}
+```
+
+### Exact alt text matching
+
+Use exact matching for precise alt text:
+
+<!-- md-k6:skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    ui: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.goto('https://quickpizza.grafana.com');
+
+    const logo = page.mainFrame().getByAltText('logo', { exact: true });
+    await logo.waitFor();
+
+    await logo.click();
+    await page.waitForLoadState();
+  } finally {
+    await page.close();
+  }
+}
+```
+
+### Using regular expressions
+
+Find images using pattern matching:
+
+<!-- md-k6:skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    ui: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.goto('https://quickpizza.grafana.com');
+
+    const logo = page.mainFrame().getByAltText(/logo/s);
+    await logo.waitFor();
+
+    await logo.click();
+    await page.waitForLoadState();
+  } finally {
+    await page.close();
+  }
+}
+```
+
+{{< docs/shared source="k6" lookup="browser/getby-apis/getbyalttext-tips.md" version="<K6_VERSION>" >}}
+
+## Related
+
+- [frame.getByRole()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyrole/) - Locate by ARIA role
+- [frame.getByLabel()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbylabel/) - Locate by form labels
+- [frame.getByPlaceholder()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyplaceholder/) - Locate by placeholder text
+- [frame.getByTestId()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytestid/) - Locate by test ID
+- [frame.getByTitle()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytitle/) - Locate by title attribute
+- [frame.getByText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytext/) - Locate by visible text

docs/sources/k6/next/javascript-api/k6-browser/frame/getbylabel.md

@@ -0,0 +1,133 @@
+---
+title: 'getByLabel(text[, options])'
+description: 'Browser module: frame.getByLabel(text[, options]) method'
+---
+
+{{< docs/shared source="k6" lookup="browser/getby-apis/getbylabel-spec.md" version="<K6_VERSION>" >}}
+
+## Examples
+
+### Basic form interaction
+
+Fill form fields using their labels:
+
+<!-- md-k6:skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    ui: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.setContent(`
+      <label for="username">Username (hint: default)</label>
+      <input type="text" id="username" name="username">
+      <label for="password">Password (hint: 12345678)</label>
+      <input type="password" id="password" name="password">
+    `);
+
+    const frame = page.mainFrame();
+    const username = frame.getByLabel('Username (hint: default)', { exact: true });
+    const password = frame.getByLabel(/^Password.*$/);
+
+    await username.fill('default');
+    await password.fill('12345678');
+  } finally {
+    await page.close();
+  }
+}
+```
+
+### Working with different input types
+
+Handle various form control types in various label association patterns:
+
+<!-- md-k6:skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.setContent(`
+      <label for="username">Username (hint: default)</label>
+      <input type="text" id="username" name="username">
+      <span id="password-label">Password (hint: 12345678)</span>
+      <input type="password" aria-labelledby="password-label">
+      <label for="subscribe">Subscribe to newsletter</label>
+      <input type="checkbox" id="subscribe" name="subscribe">
+      <label for="email">Email</label>
+      <input type="radio" id="email" value="email">
+      <label for="sms">Text message</label>
+      <input type="radio" id="sms" value="sms">
+      <label for="theme">Theme</label>
+      <select id="theme" name="theme">
+        <option value="light">Light</option>
+        <option value="dark">Dark</option>
+        <option value="system">System</option>
+      </select>
+      <textarea aria-label="Comments"></textarea>
+    `);
+
+    const frame = page.mainFrame();
+
+    // Inputs
+    await frame.getByLabel('Username (hint: default)', { exact: true }).fill('default');
+    await frame.getByLabel(/^Password.*$/).fill('12345678');
+
+    // Checkbox
+    await frame.getByLabel('Subscribe to newsletter').check();
+
+    // Radio button
+    await frame.getByLabel('Email', { exact: true }).check();
+
+    // Select dropdown
+    await frame.getByLabel('Theme').selectOption('light');
+
+    // Textarea
+    await frame.getByLabel('Comments').fill('This is a test comment');
+  } finally {
+    await page.close();
+  }
+}
+```
+
+{{< docs/shared source="k6" lookup="browser/getby-apis/getbylabel-tips.md" version="<K6_VERSION>" >}}
+
+## Related
+
+- [frame.getByRole()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyrole/) - Locate by ARIA role
+- [frame.getByAltText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyalttext/) - Locate by alt text
+- [frame.getByPlaceholder()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyplaceholder/) - Locate by placeholder text
+- [frame.getByTestId()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytestid/) - Locate by test ID
+- [frame.getByTitle()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytitle/) - Locate by title attribute
+- [frame.getByText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytext/) - Locate by text content

docs/sources/k6/next/javascript-api/k6-browser/frame/getbyplaceholder.md

@@ -0,0 +1,64 @@
+---
+title: 'getByPlaceholder(placeholder[, options])'
+description: 'Browser module: frame.getByPlaceholder(placeholder[, options]) method'
+---
+
+{{< docs/shared source="k6" lookup="browser/getby-apis/getbyplaceholder-spec.md" version="<K6_VERSION>" >}}
+
+## Example
+
+Find and fill inputs by their placeholder text:
+
+<!-- md-k6:skip -->
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'shared-iterations',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+
+  try {
+    await page.setContent(`
+      <input type="text" placeholder="First name">
+      <input type="text" placeholder="Last name">
+      <input type="text" placeholder="dd/mm/yyyy">
+      <input type="text" placeholder="your.email@example.com">
+      <input type="text" placeholder="+1 (555) 123-4567">
+    `);
+
+    const frame = page.mainFrame();
+    await frame.getByPlaceholder('First name').fill('First');
+    await frame.getByPlaceholder('Last name').fill('Last');
+    await frame.getByPlaceholder('dd/mm/yyyy').fill('01/01/1990');
+
+    await frame.getByPlaceholder('your.email@example.com').fill('first.last@example.com');
+    await frame.getByPlaceholder('+1 (555) 123-4567').fill('+1 (555) 987-6543');
+  } finally {
+    await page.close();
+  }
+}
+```
+
+{{< docs/shared source="k6" lookup="browser/getby-apis/getbyplaceholder-tips.md" version="<K6_VERSION>" >}}
+
+## Related
+
+- [frame.getByRole()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyrole/) - Locate by ARIA role
+- [frame.getByAltText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbyalttext/) - Locate by alt text
+- [frame.getByLabel()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbylabel/) - Locate by form labels (preferred for accessibility)
+- [frame.getByTestId()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytestid/) - Locate by test ID
+- [frame.getByTitle()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytitle/) - Locate by title attribute
+- [frame.getByText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/getbytext/) - Locate by visible text