diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/getbyalttext.md b/docs/sources/k6/next/javascript-api/k6-browser/page/getbyalttext.md index 99de7ff3ff..349b56d644 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/getbyalttext.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/getbyalttext.md @@ -7,25 +7,21 @@ description: 'Browser module: page.getByAltText(altText[, options]) method' Returns a locator for elements with the specified alt text. This method is useful for locating images and other elements that have an `alt` attribute, making your tests more accessible and user-focused. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------- | +| `altText` | string \| RegExp | - | Required. The alt text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the alt text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------- | -| altText | string\|RegExp | - | Required. The alt text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the alt text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with elements matching the specified alt text. | -### Returns +## Examples -| Type | Description | -| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified alt text. | - -### Examples - -#### Basic alt text matching +### Basic alt text matching Find and click an image by its alt text: @@ -64,7 +60,7 @@ export default async function () { } ``` -#### Exact alt text matching +### Exact alt text matching Use exact matching for precise alt text: @@ -103,7 +99,7 @@ export default async function () { } ``` -#### Using regular expressions +### Using regular expressions Find images using pattern matching: @@ -142,38 +138,29 @@ export default async function () { } ``` -### Common use cases - -**Image testing:** - -- Testing image alt text for accessibility compliance -- Interacting with clickable images/banners - -**Accessibility testing:** - -- Ensuring all images have meaningful alt text -- Testing screen reader compatibility -- Validating WCAG compliance +## Common use cases -**UI interaction:** +- **Image testing:** + - Testing image alt text for accessibility compliance + - Interacting with clickable images/banners +- **Accessibility testing:** + - Ensuring all images have meaningful alt text + - Testing screen reader compatibility + - Validating WCAG compliance +- **UI interaction:** + - Clicking on logo images to navigate home + - Selecting images in galleries or carousels + - Interacting with image-based buttons -- Clicking on logo images to navigate home -- Selecting images in galleries or carousels -- Interacting with image-based buttons - -### Best practices +## Best practices 1. **Use descriptive alt text**: When creating tests, ensure your application uses meaningful alt text that describes the image content or function. +1. **Prefer exact matches**: Use `exact: true` when you need precise matching to avoid false positives. +1. **Accessibility-first**: Using `getByAltText()` encourages better accessibility practices by ensuring images have proper alt attributes. +1. **Regular expressions for patterns**: Use RegExp for flexible matching when dealing with dynamic or numbered content. +1. **Combine with assertions**: Always verify that the located elements behave as expected using assertions. -2. **Prefer exact matches**: Use `exact: true` when you need precise matching to avoid false positives. - -3. **Accessibility-first**: Using `getByAltText()` encourages better accessibility practices by ensuring images have proper alt attributes. - -4. **Regular expressions for patterns**: Use RegExp for flexible matching when dealing with dynamic or numbered content. - -5. **Combine with assertions**: Always verify that the located elements behave as expected using assertions. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByLabel()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbylabel/) - Locate by form labels diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/getbylabel.md b/docs/sources/k6/next/javascript-api/k6-browser/page/getbylabel.md index acae9b3f79..496503c19a 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/getbylabel.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/getbylabel.md @@ -7,25 +7,21 @@ description: 'Browser module: page.getByLabel(text[, options]) method' Returns a locator for form controls associated with the specified label text. This method is ideal for interacting with form elements in an accessible and user-focused way, as it mirrors how users typically identify form fields. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| `text` | string \| RegExp | - | Required. The label text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the label text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------ | -| text | string\|RegExp | - | Required. The label text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the label text exactly with case sensitivity. When `true`, performs a case-sensitive match. | - - - -### Returns +## Returns | Type | Description | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the form control associated with the specified label. | -### Examples +## Examples -#### Basic form interaction +### Basic form interaction Fill form fields using their labels: @@ -69,7 +65,7 @@ export default async function () { } ``` -#### Working with different input types +### Working with different input types Handle various form control types in various label association patterns: @@ -136,52 +132,49 @@ export default async function () { } ``` -### Label association patterns +## Label association patterns The `getByLabel()` method works with several HTML patterns for associating labels with form controls: -**1. Explicit association with `for` attribute:** +1. Explicit association with `for` attribute: - + -```html - -``` + ```html + + ``` -**2. ARIA labeling:** +1. ARIA labeling: - + -```html -Username -``` + ```html + Username + ``` -**3. ARIA label attribute:** +1. ARIA label attribute: - + -```html - -``` + ```html + + ``` -### Common use cases +## Common use cases - **Form testing**: Login forms, registration forms, contact forms - **E-commerce**: Checkout forms, shipping information, payment details - **Settings pages**: User preferences, account settings, configuration forms - **Accessibility testing**: Ensuring proper label association and screen reader compatibility -### Best practices +## Best practices 1. **Accessibility-first approach**: Using `getByLabel()` ensures your tests work the same way users with assistive technology interact with forms. +1. **Meaningful labels**: Encourage developers to use descriptive, unique label text that clearly identifies the form control's purpose. +1. **Required field indicators**: When testing required fields, include any visual indicators (like asterisks) in your label text matching. +1. **Form validation testing**: Use labels to test form validation scenarios, as they provide a stable way to identify fields regardless of styling changes. -2. **Meaningful labels**: Encourage developers to use descriptive, unique label text that clearly identifies the form control's purpose. - -3. **Required field indicators**: When testing required fields, include any visual indicators (like asterisks) in your label text matching. - -4. **Form validation testing**: Use labels to test form validation scenarios, as they provide a stable way to identify fields regardless of styling changes. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/getbyplaceholder.md b/docs/sources/k6/next/javascript-api/k6-browser/page/getbyplaceholder.md index a019e87807..e5d163e2d7 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/getbyplaceholder.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/getbyplaceholder.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByPlaceholder(placeholder[, options]) meth Returns a locator for input elements with the specified `placeholder` attribute. This method is useful for locating form fields that use `placeholder` attribute to provide hints or examples to users about the expected input format. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | +| `placeholder` | string \| RegExp | - | Required. The placeholder text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the placeholder text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | -| placeholder | string\|RegExp | - | Required. The placeholder text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the placeholder text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the input elements matching the specified placeholder text. | -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the input element(s) matching the specified placeholder text. | - -### Examples +## Examples Find and fill inputs by their placeholder text: @@ -69,40 +65,32 @@ export default async function () { } ``` -### Common use cases - -**Form field identification:** - -- Login and registration forms without explicit labels -- Quick search boxes -- Filter and input controls -- Comment and feedback forms - -**E-commerce:** - -- Product search bars -- Quantity input fields -- Promo code entry -- Address and payment information - -**Interactive applications:** - -- Chat input fields -- Command input interfaces -- Settings and configuration forms -- Data entry applications - -### Best practices +## Common use cases + +- **Form field identification:** + - Login and registration forms without explicit labels + - Quick search boxes + - Filter and input controls + - Comment and feedback forms +- **E-commerce:** + - Product search bars + - Quantity input fields + - Promo code entry + - Address and payment information +- **Interactive applications:** + - Chat input fields + - Command input interfaces + - Settings and configuration forms + - Data entry applications + +## Best practices 1. **Complement, don't replace labels**: Placeholder text should supplement, not replace proper form labels for accessibility. +1. **Use descriptive placeholders**: Ensure placeholder text clearly indicates the expected input format or content. +1. **Consider internationalization**: When testing multi-language applications, be aware that placeholder text may change. +1. **Accessibility considerations**: Remember that placeholder text alone may not be sufficient for users with disabilities. -2. **Use descriptive placeholders**: Ensure placeholder text clearly indicates the expected input format or content. - -3. **Consider internationalization**: When testing multi-language applications, be aware that placeholder text may change. - -4. **Accessibility considerations**: Remember that placeholder text alone may not be sufficient for users with disabilities. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/getbyrole.md b/docs/sources/k6/next/javascript-api/k6-browser/page/getbyrole.md index 11e152395f..93085dd870 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/getbyrole.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/getbyrole.md @@ -7,33 +7,29 @@ description: 'Browser module: page.getByRole(role[, options]) method' Returns a locator for elements with the specified ARIA role. This is the preferred way to locate elements as it most closely resembles how users and assistive technology perceive the page. - - -| Parameter | Type | Default | Description | -| --------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | -| role | string | - | Required. The ARIA role to search for (e.g. `'button'`, `'link'`, `'heading'`, `'textbox'`, etc.). | -| options | object | `null` | | -| options.checked | boolean | `null` | Filter elements by their checked state. Only applicable for roles like `checkbox`, `radio`, `menuitemcheckbox`. | -| options.disabled | boolean | `null` | Filter elements by their disabled state. | -| options.exact | boolean | `false` | Whether to match the accessible name exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| options.expanded | boolean | `null` | Filter elements by their expanded state. Only applicable for roles that support the `aria-expanded` attribute. | -| options.includeHidden | boolean | `false` | Whether to include elements that are normally excluded from the accessibility tree in the search. | -| options.level | number | `null` | Filter headings by their level 1 to 6. Only applicable for `heading` role. | -| options.name | string\|RegExp | `null` | Filter elements by their accessible name. The accessible name is typically the text content, label text, or aria-label attribute. | -| options.pressed | boolean | `null` | Filter elements by their pressed state. Only applicable for roles like `button` with toggle behavior. | -| options.selected | boolean | `null` | Filter elements by their selected state. Only applicable for roles like `option`, `tab`. | - - - -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified role and options. | - -### Examples - -#### Basic role selection +| Parameter | Type | Default | Description | +| ----------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `role` | string | - | Required. The ARIA role to search for. For example, `'button'`, `'link'`, `'heading'`, or `'textbox'`. | +| options | object | `null` | | +| `options.checked` | boolean | `null` | Filter elements by their checked state. Only applicable for roles like `checkbox`, `radio`, `menuitemcheckbox`. | +| `options.disabled` | boolean | `null` | Filter elements by their disabled state. | +| `options.exact` | boolean | `false` | Whether to match the accessible name exactly with case sensitivity. When `true`, performs a case-sensitive match. | +| `options.expanded` | boolean | `null` | Filter elements by their expanded state. Only applicable for roles that support the `aria-expanded` attribute. | +| `options.includeHidden` | boolean | `false` | Whether to include elements that are normally excluded from the accessibility tree in the search. | +| `options.level` | number | `null` | Filter headings by their level 1 to 6. Only applicable for `heading` role. | +| `options.name` | string\|RegExp | `null` | Filter elements by their accessible name. The accessible name is typically the text content, label text, or aria-label attribute. | +| `options.pressed` | boolean | `null` | Filter elements by their pressed state. Only applicable for roles like `button` with toggle behavior. | +| `options.selected` | boolean | `null` | Filter elements by their selected state. Only applicable for roles like `option`, `tab`. | + +## Returns + +| Type | Description | +| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements matching the specified role and options. | + +## Examples + +### Basic role selection Find and click a button by its role: @@ -68,15 +64,15 @@ export default async function () { } ``` -### Complete ARIA roles reference +## Complete ARIA roles reference The following roles are supported and can be used with `getByRole()`, organized by category: -#### Widgets & Inputs +### Widgets & Inputs - `button` - Buttons and clickable elements - `checkbox` - Checkable boxes that can be on/off -- `combobox` - Editable dropdown combining input and listbox +- `combobox` - Editable drop-down menu combining input and list box - `listbox` - Container for selectable list options - `menu` - Menu of actions or navigation - `menubar` - Container for top-level menus @@ -84,7 +80,7 @@ The following roles are supported and can be used with `getByRole()`, organized - `menuitemcheckbox` - Checkable menu item - `menuitemradio` - Mutually exclusive menu item - `meter` - Scalar measurement within a known range -- `option` - Selectable option in a listbox or combobox +- `option` - Selectable option in a list box or combo box - `progressbar` - Progress indicator of an operation - `radio` - Single-select option in a group - `radiogroup` - Grouping of related radio buttons @@ -105,19 +101,19 @@ The following roles are supported and can be used with `getByRole()`, organized - `tree` - Hierarchical list of items - `treeitem` - Item in a tree -#### Tables & Grids +### Tables & Grids -- `table` - Tabular data with rows and columns -- `rowgroup` - Section that groups rows (thead, tbody, tfoot) -- `row` - A row of cells within a table or grid -- `rowheader` - Header cell for a row -- `columnheader` - Header cell for a column -- `cell` - Data cell in a table -- `grid` - Interactive, tabular widget (like a spreadsheet) -- `gridcell` - Cell within a grid -- `treegrid` - Tree-structured grid with expandable rows +- `table` - Tabular data with rows and columns. +- `rowgroup` - Section that groups rows. For example, `thead`, `tbody`, `tfoot`. +- `row` - A row of cells within a table or grid. +- `rowheader` - Header cell for a row. +- `columnheader` - Header cell for a column. +- `cell` - Data cell in a table. +- `grid` - Interactive, tabular widget, such as a spreadsheet. +- `gridcell` - Cell within a grid. +- `treegrid` - Tree-structured grid with expandable rows. -#### Document Structure & Semantics +### Document Structure & Semantics - `article` - Self-contained composition (article) - `blockquote` - Quotation from another source @@ -149,7 +145,7 @@ The following roles are supported and can be used with `getByRole()`, organized - `term` - A term being defined - `time` - A time or date -#### Landmarks & Regions +### Landmarks & Regions - `banner` - Site header landmark - `complementary` - Complementary content (sidebar) @@ -161,9 +157,9 @@ The following roles are supported and can be used with `getByRole()`, organized - `search` - Search region - `application` - Application container widget -#### Usage Examples by Category +### Usage Examples by Category -**Form Testing:** +- **Form Testing:** @@ -183,7 +179,7 @@ await page.getByRole('slider', { name: 'Volume' }).fill('75'); await page.getByRole('switch', { name: 'Enable notifications' }).click(); ``` -**Navigation Testing:** +- **Navigation Testing:** @@ -194,7 +190,7 @@ await page.getByRole('tab', { name: 'Overview' }).click(); await expect(page.getByRole('tabpanel', { name: 'Overview' })).toBeVisible(); ``` -**Content Verification:** +- **Content Verification:** @@ -209,15 +205,13 @@ await expect(page.getByRole('alert')).toHaveText('Form submitted successfully'); await expect(page.getByRole('status')).toHaveText('3 items selected'); ``` -### Best practices +## Best practices 1. **Prefer role-based selection**: `getByRole()` is the preferred method for locating elements as it closely mirrors how users and assistive technology interact with your page. +1. **Use accessible names**: Always try to use the `name` option to make your tests more specific and reliable. +1. **Consider accessibility**: Using `getByRole()` encourages better accessibility practices in your application by ensuring elements have proper ARIA roles. -2. **Use accessible names**: Always try to use the `name` option to make your tests more specific and reliable. - -3. **Consider accessibility**: Using `getByRole()` encourages better accessibility practices in your application by ensuring elements have proper ARIA roles. - -### Related +## Related - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text - [page.getByLabel()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbylabel/) - Locate by form labels diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/getbytestid.md b/docs/sources/k6/next/javascript-api/k6-browser/page/getbytestid.md index a26991be2f..b0d06e008a 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/getbytestid.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/getbytestid.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByTestId(testId) method' Returns a locator for elements with the specified test ID attribute. This method is designed for robust test automation by locating elements using dedicated test identifiers that are independent of the visual appearance or content changes. Currently it can only work with the `data-testid` attribute. - +| Parameter | Type | Default | Description | +| --------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `testId` | string \| RegExp | - | Required. The test ID value to search for. Searches for the `data-testid` attribute. Can be a string for exact match or a RegExp for pattern matching. | -| Parameter | Type | Default | Description | -| --------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| testId | string\|RegExp | - | Required. The test ID value to search for. Searches for the `data-testid` attribute. Can be a string for exact match or a RegExp for pattern matching. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements matching the specified test ID. | -### Returns +## Examples -| Type | Description | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified test ID. | - -### Examples - -#### Basic test ID usage +### Basic test ID usage Locate and interact with elements using test IDs: @@ -64,19 +60,15 @@ export default async function () { } ``` -### Best practices +## Best practices 1. **Stable identifiers**: Use meaningful, stable test IDs that won't change with refactoring or content updates. +1. **Hierarchical naming**: Use consistent naming conventions like `user-profile-edit-btn`. +1. **Avoid duplicates**: Ensure test IDs are unique within the page to prevent ambiguity. +1. **Strategic placement**: Add test IDs to key interactive elements and components that are frequently tested. +1. **Team coordination**: Establish test ID conventions with your development team to ensure consistency. -2. **Hierarchical naming**: Use consistent naming conventions like `user-profile-edit-btn`. - -3. **Avoid duplicates**: Ensure test IDs are unique within the page to prevent ambiguity. - -4. **Strategic placement**: Add test IDs to key interactive elements and components that are frequently tested. - -5. **Team coordination**: Establish test ID conventions with your development team to ensure consistency. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/getbytext.md b/docs/sources/k6/next/javascript-api/k6-browser/page/getbytext.md index b2917e15a5..ef2ba20192 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/getbytext.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/getbytext.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByText(text[, options]) method' Returns a locator for elements containing the specified text. This method finds elements by their visible text content, making it ideal for locating user-facing content like buttons, links, headings, and other text elements. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------- | +| `text` | string \| RegExp | - | Required. The text content to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------- | -| text | string\|RegExp | - | Required. The text content to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements containing the specified text. | -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) containing the specified text. | - -### Examples +## Examples Find and click elements by their visible text: @@ -61,7 +57,7 @@ export default async function () { } ``` -### Text matching behavior +## Text matching behavior **Whitespace normalization**: Text matching automatically normalizes whitespace, meaning: @@ -97,7 +93,7 @@ page.getByText(/Hello/); page.getByText(/^hello$/i); ``` -### Common use cases +## Common use cases - **Button interactions**: Submit, Cancel, Delete, Edit buttons - **Navigation**: Menu items, breadcrumbs, pagination links @@ -105,21 +101,16 @@ page.getByText(/^hello$/i); - **Form interactions**: Checkbox labels, radio button options - **Status indicators**: Active, Inactive, Pending states -### Best practices +## Best practices 1. **User-focused testing**: Using `getByText()` ensures your tests interact with content as users see it. +1. **Avoid brittle text**: Be cautious with exact text that might change frequently (like dates, counts, or user-generated content). +1. **Use meaningful text**: Prefer descriptive button text and labels over generic terms like "Click here" or "Button". +1. **Handle dynamic content**: Use regular expressions for text that contains variable parts (timestamps, user names, counts). +1. **Consider accessibility**: Text-based selection encourages better accessibility practices in your application. +1. **Internationalization**: For multi-language applications, consider using test IDs or roles instead of text for critical interactions. -2. **Avoid brittle text**: Be cautious with exact text that might change frequently (like dates, counts, or user-generated content). - -3. **Use meaningful text**: Prefer descriptive button text and labels over generic terms like "Click here" or "Button". - -4. **Handle dynamic content**: Use regular expressions for text that contains variable parts (timestamps, user names, counts). - -5. **Consider accessibility**: Text-based selection encourages better accessibility practices in your application. - -6. **Internationalization**: For multi-language applications, consider using test IDs or roles instead of text for critical interactions. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/getbytitle.md b/docs/sources/k6/next/javascript-api/k6-browser/page/getbytitle.md index ed4cd987d1..8c7be87342 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/getbytitle.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/getbytitle.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByTitle(title[, options]) method' Returns a locator for elements with the specified `title` attribute. This method is useful for locating elements that use the `title` attribute to provide additional information, tooltips, or accessibility context. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| `title` | string \| RegExp | - | Required. The title text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the title text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------ | -| title | string\|RegExp | - | Required. The title text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the title text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements matching the specified title attribute. | -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified title attribute. | - -### Examples +## Examples Find and interact with elements by their title attribute: @@ -71,44 +67,34 @@ export default async function () { } ``` -### Common use cases - -**User interface controls:** - -- Toolbar buttons and action items -- Navigation controls (previous/next, pagination) -- Media player controls -- Menu and dropdown triggers - -**Informational elements:** - -- Help icons and tooltips -- Status indicators and badges -- Progress indicators -- Warning and error messages - -**Accessibility support:** - -- Screen reader descriptions -- Alternative text for complex elements -- Context-sensitive help -- Form field explanations - -### Best practices +## Common use cases + +- **User interface controls:** + - Toolbar buttons and action items + - Navigation controls (previous/next, pagination) + - Media player controls + - Menu and drop-down triggers +- **Informational elements:** + - Help icons and tooltips + - Status indicators and badges + - Progress indicators + - Warning and error messages +- **Accessibility support:** + - Screen reader descriptions + - Alternative text for complex elements + - Context-sensitive help + - Form field explanations + +## Best practices 1. **Meaningful titles**: Ensure title attributes provide clear, helpful information about the element's purpose or content. +1. **Accessibility compliance**: Use titles to enhance accessibility, especially for elements that might not have clear visual labels. +1. **Avoid redundancy**: Don't duplicate visible text in the title attribute unless providing additional context. +1. **Dynamic content**: When testing applications with changing title content, use flexible matching patterns or regular expressions. +1. **Tooltip testing**: Remember that title attributes often create tooltips on hover, which can be useful for UI testing. +1. **Internationalization**: Consider that title text may change in different language versions of your application. -2. **Accessibility compliance**: Use titles to enhance accessibility, especially for elements that might not have clear visual labels. - -3. **Avoid redundancy**: Don't duplicate visible text in the title attribute unless providing additional context. - -4. **Dynamic content**: When testing applications with changing title content, use flexible matching patterns or regular expressions. - -5. **Tooltip testing**: Remember that title attributes often create tooltips on hover, which can be useful for UI testing. - -6. **Internationalization**: Consider that title text may change in different language versions of your application. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyalttext.md b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyalttext.md index 99de7ff3ff..349b56d644 100644 --- a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyalttext.md +++ b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyalttext.md @@ -7,25 +7,21 @@ description: 'Browser module: page.getByAltText(altText[, options]) method' Returns a locator for elements with the specified alt text. This method is useful for locating images and other elements that have an `alt` attribute, making your tests more accessible and user-focused. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------- | +| `altText` | string \| RegExp | - | Required. The alt text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the alt text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------- | -| altText | string\|RegExp | - | Required. The alt text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the alt text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with elements matching the specified alt text. | -### Returns +## Examples -| Type | Description | -| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified alt text. | - -### Examples - -#### Basic alt text matching +### Basic alt text matching Find and click an image by its alt text: @@ -64,7 +60,7 @@ export default async function () { } ``` -#### Exact alt text matching +### Exact alt text matching Use exact matching for precise alt text: @@ -103,7 +99,7 @@ export default async function () { } ``` -#### Using regular expressions +### Using regular expressions Find images using pattern matching: @@ -142,38 +138,29 @@ export default async function () { } ``` -### Common use cases - -**Image testing:** - -- Testing image alt text for accessibility compliance -- Interacting with clickable images/banners - -**Accessibility testing:** - -- Ensuring all images have meaningful alt text -- Testing screen reader compatibility -- Validating WCAG compliance +## Common use cases -**UI interaction:** +- **Image testing:** + - Testing image alt text for accessibility compliance + - Interacting with clickable images/banners +- **Accessibility testing:** + - Ensuring all images have meaningful alt text + - Testing screen reader compatibility + - Validating WCAG compliance +- **UI interaction:** + - Clicking on logo images to navigate home + - Selecting images in galleries or carousels + - Interacting with image-based buttons -- Clicking on logo images to navigate home -- Selecting images in galleries or carousels -- Interacting with image-based buttons - -### Best practices +## Best practices 1. **Use descriptive alt text**: When creating tests, ensure your application uses meaningful alt text that describes the image content or function. +1. **Prefer exact matches**: Use `exact: true` when you need precise matching to avoid false positives. +1. **Accessibility-first**: Using `getByAltText()` encourages better accessibility practices by ensuring images have proper alt attributes. +1. **Regular expressions for patterns**: Use RegExp for flexible matching when dealing with dynamic or numbered content. +1. **Combine with assertions**: Always verify that the located elements behave as expected using assertions. -2. **Prefer exact matches**: Use `exact: true` when you need precise matching to avoid false positives. - -3. **Accessibility-first**: Using `getByAltText()` encourages better accessibility practices by ensuring images have proper alt attributes. - -4. **Regular expressions for patterns**: Use RegExp for flexible matching when dealing with dynamic or numbered content. - -5. **Combine with assertions**: Always verify that the located elements behave as expected using assertions. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByLabel()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbylabel/) - Locate by form labels diff --git a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbylabel.md b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbylabel.md index acae9b3f79..496503c19a 100644 --- a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbylabel.md +++ b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbylabel.md @@ -7,25 +7,21 @@ description: 'Browser module: page.getByLabel(text[, options]) method' Returns a locator for form controls associated with the specified label text. This method is ideal for interacting with form elements in an accessible and user-focused way, as it mirrors how users typically identify form fields. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| `text` | string \| RegExp | - | Required. The label text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the label text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------ | -| text | string\|RegExp | - | Required. The label text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the label text exactly with case sensitivity. When `true`, performs a case-sensitive match. | - - - -### Returns +## Returns | Type | Description | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the form control associated with the specified label. | -### Examples +## Examples -#### Basic form interaction +### Basic form interaction Fill form fields using their labels: @@ -69,7 +65,7 @@ export default async function () { } ``` -#### Working with different input types +### Working with different input types Handle various form control types in various label association patterns: @@ -136,52 +132,49 @@ export default async function () { } ``` -### Label association patterns +## Label association patterns The `getByLabel()` method works with several HTML patterns for associating labels with form controls: -**1. Explicit association with `for` attribute:** +1. Explicit association with `for` attribute: - + -```html - -``` + ```html + + ``` -**2. ARIA labeling:** +1. ARIA labeling: - + -```html -Username -``` + ```html + Username + ``` -**3. ARIA label attribute:** +1. ARIA label attribute: - + -```html - -``` + ```html + + ``` -### Common use cases +## Common use cases - **Form testing**: Login forms, registration forms, contact forms - **E-commerce**: Checkout forms, shipping information, payment details - **Settings pages**: User preferences, account settings, configuration forms - **Accessibility testing**: Ensuring proper label association and screen reader compatibility -### Best practices +## Best practices 1. **Accessibility-first approach**: Using `getByLabel()` ensures your tests work the same way users with assistive technology interact with forms. +1. **Meaningful labels**: Encourage developers to use descriptive, unique label text that clearly identifies the form control's purpose. +1. **Required field indicators**: When testing required fields, include any visual indicators (like asterisks) in your label text matching. +1. **Form validation testing**: Use labels to test form validation scenarios, as they provide a stable way to identify fields regardless of styling changes. -2. **Meaningful labels**: Encourage developers to use descriptive, unique label text that clearly identifies the form control's purpose. - -3. **Required field indicators**: When testing required fields, include any visual indicators (like asterisks) in your label text matching. - -4. **Form validation testing**: Use labels to test form validation scenarios, as they provide a stable way to identify fields regardless of styling changes. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyplaceholder.md b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyplaceholder.md index a019e87807..e5d163e2d7 100644 --- a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyplaceholder.md +++ b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyplaceholder.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByPlaceholder(placeholder[, options]) meth Returns a locator for input elements with the specified `placeholder` attribute. This method is useful for locating form fields that use `placeholder` attribute to provide hints or examples to users about the expected input format. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | +| `placeholder` | string \| RegExp | - | Required. The placeholder text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the placeholder text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | -| placeholder | string\|RegExp | - | Required. The placeholder text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the placeholder text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the input elements matching the specified placeholder text. | -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the input element(s) matching the specified placeholder text. | - -### Examples +## Examples Find and fill inputs by their placeholder text: @@ -69,40 +65,32 @@ export default async function () { } ``` -### Common use cases - -**Form field identification:** - -- Login and registration forms without explicit labels -- Quick search boxes -- Filter and input controls -- Comment and feedback forms - -**E-commerce:** - -- Product search bars -- Quantity input fields -- Promo code entry -- Address and payment information - -**Interactive applications:** - -- Chat input fields -- Command input interfaces -- Settings and configuration forms -- Data entry applications - -### Best practices +## Common use cases + +- **Form field identification:** + - Login and registration forms without explicit labels + - Quick search boxes + - Filter and input controls + - Comment and feedback forms +- **E-commerce:** + - Product search bars + - Quantity input fields + - Promo code entry + - Address and payment information +- **Interactive applications:** + - Chat input fields + - Command input interfaces + - Settings and configuration forms + - Data entry applications + +## Best practices 1. **Complement, don't replace labels**: Placeholder text should supplement, not replace proper form labels for accessibility. +1. **Use descriptive placeholders**: Ensure placeholder text clearly indicates the expected input format or content. +1. **Consider internationalization**: When testing multi-language applications, be aware that placeholder text may change. +1. **Accessibility considerations**: Remember that placeholder text alone may not be sufficient for users with disabilities. -2. **Use descriptive placeholders**: Ensure placeholder text clearly indicates the expected input format or content. - -3. **Consider internationalization**: When testing multi-language applications, be aware that placeholder text may change. - -4. **Accessibility considerations**: Remember that placeholder text alone may not be sufficient for users with disabilities. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyrole.md b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyrole.md index 11e152395f..93085dd870 100644 --- a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyrole.md +++ b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbyrole.md @@ -7,33 +7,29 @@ description: 'Browser module: page.getByRole(role[, options]) method' Returns a locator for elements with the specified ARIA role. This is the preferred way to locate elements as it most closely resembles how users and assistive technology perceive the page. - - -| Parameter | Type | Default | Description | -| --------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | -| role | string | - | Required. The ARIA role to search for (e.g. `'button'`, `'link'`, `'heading'`, `'textbox'`, etc.). | -| options | object | `null` | | -| options.checked | boolean | `null` | Filter elements by their checked state. Only applicable for roles like `checkbox`, `radio`, `menuitemcheckbox`. | -| options.disabled | boolean | `null` | Filter elements by their disabled state. | -| options.exact | boolean | `false` | Whether to match the accessible name exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| options.expanded | boolean | `null` | Filter elements by their expanded state. Only applicable for roles that support the `aria-expanded` attribute. | -| options.includeHidden | boolean | `false` | Whether to include elements that are normally excluded from the accessibility tree in the search. | -| options.level | number | `null` | Filter headings by their level 1 to 6. Only applicable for `heading` role. | -| options.name | string\|RegExp | `null` | Filter elements by their accessible name. The accessible name is typically the text content, label text, or aria-label attribute. | -| options.pressed | boolean | `null` | Filter elements by their pressed state. Only applicable for roles like `button` with toggle behavior. | -| options.selected | boolean | `null` | Filter elements by their selected state. Only applicable for roles like `option`, `tab`. | - - - -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified role and options. | - -### Examples - -#### Basic role selection +| Parameter | Type | Default | Description | +| ----------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `role` | string | - | Required. The ARIA role to search for. For example, `'button'`, `'link'`, `'heading'`, or `'textbox'`. | +| options | object | `null` | | +| `options.checked` | boolean | `null` | Filter elements by their checked state. Only applicable for roles like `checkbox`, `radio`, `menuitemcheckbox`. | +| `options.disabled` | boolean | `null` | Filter elements by their disabled state. | +| `options.exact` | boolean | `false` | Whether to match the accessible name exactly with case sensitivity. When `true`, performs a case-sensitive match. | +| `options.expanded` | boolean | `null` | Filter elements by their expanded state. Only applicable for roles that support the `aria-expanded` attribute. | +| `options.includeHidden` | boolean | `false` | Whether to include elements that are normally excluded from the accessibility tree in the search. | +| `options.level` | number | `null` | Filter headings by their level 1 to 6. Only applicable for `heading` role. | +| `options.name` | string\|RegExp | `null` | Filter elements by their accessible name. The accessible name is typically the text content, label text, or aria-label attribute. | +| `options.pressed` | boolean | `null` | Filter elements by their pressed state. Only applicable for roles like `button` with toggle behavior. | +| `options.selected` | boolean | `null` | Filter elements by their selected state. Only applicable for roles like `option`, `tab`. | + +## Returns + +| Type | Description | +| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements matching the specified role and options. | + +## Examples + +### Basic role selection Find and click a button by its role: @@ -68,15 +64,15 @@ export default async function () { } ``` -### Complete ARIA roles reference +## Complete ARIA roles reference The following roles are supported and can be used with `getByRole()`, organized by category: -#### Widgets & Inputs +### Widgets & Inputs - `button` - Buttons and clickable elements - `checkbox` - Checkable boxes that can be on/off -- `combobox` - Editable dropdown combining input and listbox +- `combobox` - Editable drop-down menu combining input and list box - `listbox` - Container for selectable list options - `menu` - Menu of actions or navigation - `menubar` - Container for top-level menus @@ -84,7 +80,7 @@ The following roles are supported and can be used with `getByRole()`, organized - `menuitemcheckbox` - Checkable menu item - `menuitemradio` - Mutually exclusive menu item - `meter` - Scalar measurement within a known range -- `option` - Selectable option in a listbox or combobox +- `option` - Selectable option in a list box or combo box - `progressbar` - Progress indicator of an operation - `radio` - Single-select option in a group - `radiogroup` - Grouping of related radio buttons @@ -105,19 +101,19 @@ The following roles are supported and can be used with `getByRole()`, organized - `tree` - Hierarchical list of items - `treeitem` - Item in a tree -#### Tables & Grids +### Tables & Grids -- `table` - Tabular data with rows and columns -- `rowgroup` - Section that groups rows (thead, tbody, tfoot) -- `row` - A row of cells within a table or grid -- `rowheader` - Header cell for a row -- `columnheader` - Header cell for a column -- `cell` - Data cell in a table -- `grid` - Interactive, tabular widget (like a spreadsheet) -- `gridcell` - Cell within a grid -- `treegrid` - Tree-structured grid with expandable rows +- `table` - Tabular data with rows and columns. +- `rowgroup` - Section that groups rows. For example, `thead`, `tbody`, `tfoot`. +- `row` - A row of cells within a table or grid. +- `rowheader` - Header cell for a row. +- `columnheader` - Header cell for a column. +- `cell` - Data cell in a table. +- `grid` - Interactive, tabular widget, such as a spreadsheet. +- `gridcell` - Cell within a grid. +- `treegrid` - Tree-structured grid with expandable rows. -#### Document Structure & Semantics +### Document Structure & Semantics - `article` - Self-contained composition (article) - `blockquote` - Quotation from another source @@ -149,7 +145,7 @@ The following roles are supported and can be used with `getByRole()`, organized - `term` - A term being defined - `time` - A time or date -#### Landmarks & Regions +### Landmarks & Regions - `banner` - Site header landmark - `complementary` - Complementary content (sidebar) @@ -161,9 +157,9 @@ The following roles are supported and can be used with `getByRole()`, organized - `search` - Search region - `application` - Application container widget -#### Usage Examples by Category +### Usage Examples by Category -**Form Testing:** +- **Form Testing:** @@ -183,7 +179,7 @@ await page.getByRole('slider', { name: 'Volume' }).fill('75'); await page.getByRole('switch', { name: 'Enable notifications' }).click(); ``` -**Navigation Testing:** +- **Navigation Testing:** @@ -194,7 +190,7 @@ await page.getByRole('tab', { name: 'Overview' }).click(); await expect(page.getByRole('tabpanel', { name: 'Overview' })).toBeVisible(); ``` -**Content Verification:** +- **Content Verification:** @@ -209,15 +205,13 @@ await expect(page.getByRole('alert')).toHaveText('Form submitted successfully'); await expect(page.getByRole('status')).toHaveText('3 items selected'); ``` -### Best practices +## Best practices 1. **Prefer role-based selection**: `getByRole()` is the preferred method for locating elements as it closely mirrors how users and assistive technology interact with your page. +1. **Use accessible names**: Always try to use the `name` option to make your tests more specific and reliable. +1. **Consider accessibility**: Using `getByRole()` encourages better accessibility practices in your application by ensuring elements have proper ARIA roles. -2. **Use accessible names**: Always try to use the `name` option to make your tests more specific and reliable. - -3. **Consider accessibility**: Using `getByRole()` encourages better accessibility practices in your application by ensuring elements have proper ARIA roles. - -### Related +## Related - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text - [page.getByLabel()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbylabel/) - Locate by form labels diff --git a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytestid.md b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytestid.md index a26991be2f..b0d06e008a 100644 --- a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytestid.md +++ b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytestid.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByTestId(testId) method' Returns a locator for elements with the specified test ID attribute. This method is designed for robust test automation by locating elements using dedicated test identifiers that are independent of the visual appearance or content changes. Currently it can only work with the `data-testid` attribute. - +| Parameter | Type | Default | Description | +| --------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `testId` | string \| RegExp | - | Required. The test ID value to search for. Searches for the `data-testid` attribute. Can be a string for exact match or a RegExp for pattern matching. | -| Parameter | Type | Default | Description | -| --------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| testId | string\|RegExp | - | Required. The test ID value to search for. Searches for the `data-testid` attribute. Can be a string for exact match or a RegExp for pattern matching. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements matching the specified test ID. | -### Returns +## Examples -| Type | Description | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified test ID. | - -### Examples - -#### Basic test ID usage +### Basic test ID usage Locate and interact with elements using test IDs: @@ -64,19 +60,15 @@ export default async function () { } ``` -### Best practices +## Best practices 1. **Stable identifiers**: Use meaningful, stable test IDs that won't change with refactoring or content updates. +1. **Hierarchical naming**: Use consistent naming conventions like `user-profile-edit-btn`. +1. **Avoid duplicates**: Ensure test IDs are unique within the page to prevent ambiguity. +1. **Strategic placement**: Add test IDs to key interactive elements and components that are frequently tested. +1. **Team coordination**: Establish test ID conventions with your development team to ensure consistency. -2. **Hierarchical naming**: Use consistent naming conventions like `user-profile-edit-btn`. - -3. **Avoid duplicates**: Ensure test IDs are unique within the page to prevent ambiguity. - -4. **Strategic placement**: Add test IDs to key interactive elements and components that are frequently tested. - -5. **Team coordination**: Establish test ID conventions with your development team to ensure consistency. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytext.md b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytext.md index b2917e15a5..ef2ba20192 100644 --- a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytext.md +++ b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytext.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByText(text[, options]) method' Returns a locator for elements containing the specified text. This method finds elements by their visible text content, making it ideal for locating user-facing content like buttons, links, headings, and other text elements. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------- | +| `text` | string \| RegExp | - | Required. The text content to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------- | -| text | string\|RegExp | - | Required. The text content to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements containing the specified text. | -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) containing the specified text. | - -### Examples +## Examples Find and click elements by their visible text: @@ -61,7 +57,7 @@ export default async function () { } ``` -### Text matching behavior +## Text matching behavior **Whitespace normalization**: Text matching automatically normalizes whitespace, meaning: @@ -97,7 +93,7 @@ page.getByText(/Hello/); page.getByText(/^hello$/i); ``` -### Common use cases +## Common use cases - **Button interactions**: Submit, Cancel, Delete, Edit buttons - **Navigation**: Menu items, breadcrumbs, pagination links @@ -105,21 +101,16 @@ page.getByText(/^hello$/i); - **Form interactions**: Checkbox labels, radio button options - **Status indicators**: Active, Inactive, Pending states -### Best practices +## Best practices 1. **User-focused testing**: Using `getByText()` ensures your tests interact with content as users see it. +1. **Avoid brittle text**: Be cautious with exact text that might change frequently (like dates, counts, or user-generated content). +1. **Use meaningful text**: Prefer descriptive button text and labels over generic terms like "Click here" or "Button". +1. **Handle dynamic content**: Use regular expressions for text that contains variable parts (timestamps, user names, counts). +1. **Consider accessibility**: Text-based selection encourages better accessibility practices in your application. +1. **Internationalization**: For multi-language applications, consider using test IDs or roles instead of text for critical interactions. -2. **Avoid brittle text**: Be cautious with exact text that might change frequently (like dates, counts, or user-generated content). - -3. **Use meaningful text**: Prefer descriptive button text and labels over generic terms like "Click here" or "Button". - -4. **Handle dynamic content**: Use regular expressions for text that contains variable parts (timestamps, user names, counts). - -5. **Consider accessibility**: Text-based selection encourages better accessibility practices in your application. - -6. **Internationalization**: For multi-language applications, consider using test IDs or roles instead of text for critical interactions. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text diff --git a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytitle.md b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytitle.md index ed4cd987d1..8c7be87342 100644 --- a/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytitle.md +++ b/docs/sources/k6/v1.2.x/javascript-api/k6-browser/page/getbytitle.md @@ -7,23 +7,19 @@ description: 'Browser module: page.getByTitle(title[, options]) method' Returns a locator for elements with the specified `title` attribute. This method is useful for locating elements that use the `title` attribute to provide additional information, tooltips, or accessibility context. - +| Parameter | Type | Default | Description | +| --------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| `title` | string \| RegExp | - | Required. The title text to search for. Can be a string for exact match or a RegExp for pattern matching. | +| `options` | object | `null` | | +| `options.exact` | boolean | `false` | Whether to match the title text exactly with case sensitivity. When `true`, performs a case-sensitive match. | -| Parameter | Type | Default | Description | -| ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------ | -| title | string\|RegExp | - | Required. The title text to search for. Can be a string for exact match or a RegExp for pattern matching. | -| options | object | `null` | | -| options.exact | boolean | `false` | Whether to match the title text exactly with case sensitivity. When `true`, performs a case-sensitive match. | +## Returns - +| Type | Description | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the elements matching the specified title attribute. | -### Returns - -| Type | Description | -| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) matching the specified title attribute. | - -### Examples +## Examples Find and interact with elements by their title attribute: @@ -71,44 +67,34 @@ export default async function () { } ``` -### Common use cases - -**User interface controls:** - -- Toolbar buttons and action items -- Navigation controls (previous/next, pagination) -- Media player controls -- Menu and dropdown triggers - -**Informational elements:** - -- Help icons and tooltips -- Status indicators and badges -- Progress indicators -- Warning and error messages - -**Accessibility support:** - -- Screen reader descriptions -- Alternative text for complex elements -- Context-sensitive help -- Form field explanations - -### Best practices +## Common use cases + +- **User interface controls:** + - Toolbar buttons and action items + - Navigation controls (previous/next, pagination) + - Media player controls + - Menu and drop-down triggers +- **Informational elements:** + - Help icons and tooltips + - Status indicators and badges + - Progress indicators + - Warning and error messages +- **Accessibility support:** + - Screen reader descriptions + - Alternative text for complex elements + - Context-sensitive help + - Form field explanations + +## Best practices 1. **Meaningful titles**: Ensure title attributes provide clear, helpful information about the element's purpose or content. +1. **Accessibility compliance**: Use titles to enhance accessibility, especially for elements that might not have clear visual labels. +1. **Avoid redundancy**: Don't duplicate visible text in the title attribute unless providing additional context. +1. **Dynamic content**: When testing applications with changing title content, use flexible matching patterns or regular expressions. +1. **Tooltip testing**: Remember that title attributes often create tooltips on hover, which can be useful for UI testing. +1. **Internationalization**: Consider that title text may change in different language versions of your application. -2. **Accessibility compliance**: Use titles to enhance accessibility, especially for elements that might not have clear visual labels. - -3. **Avoid redundancy**: Don't duplicate visible text in the title attribute unless providing additional context. - -4. **Dynamic content**: When testing applications with changing title content, use flexible matching patterns or regular expressions. - -5. **Tooltip testing**: Remember that title attributes often create tooltips on hover, which can be useful for UI testing. - -6. **Internationalization**: Consider that title text may change in different language versions of your application. - -### Related +## Related - [page.getByRole()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role - [page.getByAltText()](https://grafana.com/docs/k6//javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text