Menu
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Open source
getByAltText(altText[, options])
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.
Returns
Examples
Basic alt text matching
Find and click an image by its alt text:
import { browser } from 'k6/browser';
export const options = {
scenarios: {
ui: {
executor: 'shared-iterations',
options: {
browser: {
type: 'chromium',
},
},
},
},
};
export default async function () {
const page = await browser.newPage();
try {
await page.setContent(`
<iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
`);
const logo = page.locator('#my_frame').contentFrame().getByAltText('LOGO');
await logo.waitFor();
await logo.click();
await page.waitForLoadState();
} finally {
await page.close();
}
}Exact alt text matching
Use exact matching for precise alt text:
import { browser } from 'k6/browser';
export const options = {
scenarios: {
ui: {
executor: 'shared-iterations',
options: {
browser: {
type: 'chromium',
},
},
},
},
};
export default async function () {
const page = await browser.newPage();
try {
await page.setContent(`
<iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
`);
const logo = page.locator('#my_frame').contentFrame().getByAltText('logo', { exact: true });
await logo.waitFor();
await logo.click();
await page.waitForLoadState();
} finally {
await page.close();
}
}Using regular expressions
Find images using pattern matching:
import { browser } from 'k6/browser';
export const options = {
scenarios: {
ui: {
executor: 'shared-iterations',
options: {
browser: {
type: 'chromium',
},
},
},
},
};
export default async function () {
const page = await browser.newPage();
try {
await page.setContent(`
<iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
`);
const logo = page.locator('#my_frame').contentFrame().getByAltText(/logo/s);
await logo.waitFor();
await logo.click();
await page.waitForLoadState();
} finally {
await page.close();
}
}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
- UI interaction:
- Clicking on logo images to navigate home
- Selecting images in galleries or carousels
- Interacting with image-based buttons
Best practices
- Use descriptive alt text: When creating tests, ensure your application uses meaningful alt text that describes the image content or function.
- Prefer exact matches: Use
exact: truewhen you need precise matching to avoid false positives. - Accessibility-first: Using
getByAltText()encourages better accessibility practices by ensuring images have proper alt attributes. - Regular expressions for patterns: Use RegExp for flexible matching when dealing with dynamic or numbered content.
- Combine with assertions: Always verify that the located elements behave as expected using assertions.
Related
- frameLocator.getByRole() - Locate by ARIA role
- frameLocator.getByLabel() - Locate by form labels
- frameLocator.getByPlaceholder() - Locate by placeholder text
- frameLocator.getByTestId() - Locate by test ID
- frameLocator.getByTitle() - Locate by title attribute
- frameLocator.getByText() - Locate by visible text

