Skip to content

Style guide and Vale fixes for getBy pages #2045

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 3, 2025
Merged

Style guide and Vale fixes for getBy pages #2045

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b8fc883
Style guide and Vale fixes for getBy pages
heitortsergent Sep 2, 2025
55b00b8
Apply to v1.2
heitortsergent Sep 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 31 additions & 44 deletions docs/sources/k6/next/javascript-api/k6-browser/page/getbyalttext.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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

</TableWithNestedRows>
| Type | Description |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Locator](https://grafana.com/docs/k6/<K6_VERSION>/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/<K6_VERSION>/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:

Expand Down Expand Up @@ -64,7 +60,7 @@ export default async function () {
}
```

#### Exact alt text matching
### Exact alt text matching

Use exact matching for precise alt text:

Expand Down Expand Up @@ -103,7 +99,7 @@ export default async function () {
}
```

#### Using regular expressions
### Using regular expressions

Find images using pattern matching:

Expand Down Expand Up @@ -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/<K6_VERSION>/javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role
- [page.getByLabel()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbylabel/) - Locate by form labels
Expand Down
69 changes: 31 additions & 38 deletions docs/sources/k6/next/javascript-api/k6-browser/page/getbylabel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<TableWithNestedRows>
| 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. |

</TableWithNestedRows>

### Returns
## Returns

| Type | Description |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [Locator](https://grafana.com/docs/k6/<K6_VERSION>/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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

<!-- eslint-skip -->
<!-- eslint-skip -->

```html
<label for="username">Username</label> <input type="text" id="username" name="username" />
```
```html
<label for="username">Username</label> <input type="text" id="username" name="username" />
```

**2. ARIA labeling:**
1. ARIA labeling:

<!-- eslint-skip -->
<!-- eslint-skip -->

```html
<span id="username-label">Username</span> <input type="text" aria-labelledby="username-label" />
```
```html
<span id="username-label">Username</span> <input type="text" aria-labelledby="username-label" />
```

**3. ARIA label attribute:**
1. ARIA label attribute:

<!-- eslint-skip -->
<!-- eslint-skip -->

```html
<input type="text" aria-label="Username" />
```
```html
<input type="text" aria-label="Username" />
```

### 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/<K6_VERSION>/javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role
- [page.getByAltText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text
Expand Down
78 changes: 33 additions & 45 deletions docs/sources/k6/next/javascript-api/k6-browser/page/getbyplaceholder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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

</TableWithNestedRows>
| Type | Description |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [Locator](https://grafana.com/docs/k6/<K6_VERSION>/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/<K6_VERSION>/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:

Expand Down Expand Up @@ -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/<K6_VERSION>/javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role
- [page.getByAltText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text
Expand Down
Loading
Loading