How to Use getByAltText Locator in Playwright

When automating tests for web applications, selecting the right elements on a page is crucial. The getByAltText Locator in Playwright helps you locate elements based on their alt attribute, which is typically used with images and other media for accessibility purposes. This is especially useful when testing UI components and ensuring your app is accessible to everyone.

For broader accessibility testing, you might also explore the getByRole locator in Playwright, which helps you locate elements by their ARIA roles.

In this tutorial, you’ll learn what getByAltText is, how to use it, and when it’s most effective. We’ll also compare it with other common locators in Playwright.

What is getByAltText Locator in Playwright?

getByAltText is a locator method provided by the @playwright/test library. It lets you find elements using their alternative text, which is typically defined using the alt attribute in HTML. It’s commonly used to target images, icons, and other non-text content that includes descriptive text.

const image = page.getByAltText('Company logo');

const image = page.getByAltText('Company logo');

This command will return the element with the alt text “Company logo” — helping you interact with or validate it in your test script.

Why Use getByAltText Locator?

There are several reasons why getByAltText is a smart choice for Playwright tests:

• Great for testing accessibility
• Helps ensure that images are correctly loaded
• Makes your tests more readable and maintainable
• Target elements that don’t have traditional visible text

Using this method, you can write tests that more closely simulate how screen readers perceive content, thereby improving accessibility compliance.

Similarly, the getByLabel locator helps you find form elements using their associated labels, ideal for form testing.

Syntax of getByAltText Locator

Here’s the basic syntax:

page.getByAltText(altText: string, options?)

page.getByAltText(altText: string, options?)

• altText: A string matching the alt attribute
• options (optional): For example, { exact: true } enforces case-sensitive matching

Practical Example

Here’s a basic example that verifies if a logo is visible on the homepage:

import { test, expect } from '@playwright/test';

test('Example: Locate image using getByAltText locator in Playwright', async ({ page }) => {
  await page.goto('https://only-testing-blog.blogspot.com/2014/09/selectable.html');
  
  //Locate image using alt text.
  const logo = page.getByAltText('Test Image Alt Text');

  //Assert image is visible.
  await expect(logo).toBeVisible();
});

import { test, expect } from '@playwright/test';

test('Example: Locate image using getByAltText locator in Playwright', async ({ page }) => {
  await page.goto('https://only-testing-blog.blogspot.com/2014/09/selectable.html');
  
  //Locate image using alt text.
  const logo = page.getByAltText('Test Image Alt Text');

  //Assert image is visible.
  await expect(logo).toBeVisible();
});

You can also combine this with interaction commands like click() or screenshot() to test further.

Using Options Like exact

The exact option ensures that the alt text matches precisely, including letter casing.

page.getByAltText('Company Logo', { exact: true });

page.getByAltText('Company Logo', { exact: true });

This is helpful when your site includes multiple images with similar alt text values.

Advanced Use Cases

You can also use getByAltText in dynamic situations, like:

• Validating product images in an e-commerce app
• Confirming placeholder images in news articles
• Testing image galleries and slideshows

const thumbnails = await page.getByAltText(/product/i);
await expect(thumbnails).toHaveCount(4);

const thumbnails = await page.getByAltText(/product/i);
await expect(thumbnails).toHaveCount(4);

Using regular expressions lets you select a group of similar elements by partial alt text.

Best Practices

• Always write meaningful alt attributes for images
• Use getByAltText only when alt text is reliably defined
• Avoid using this locator if alt text is missing or empty
• Combine with assertions (expect) for clear pass/fail logic

Another alternative is using a Playwright text selector to target visible text on the page when alt is not present.

Conclusion

The getByAltText in Playwright locator is a powerful way to interact with elements that are described using alternative text. It supports accessible testing, helps you write clean, understandable test scripts, and improves your web app’s overall test coverage.

Whether you’re building for accessibility or just need a stable selector for images, Playwright getByAltText makes your test automation more efficient and effective.

Frequently Asked Questions (FAQs)

Aravind

Hi, I’m Aravind — a seasoned Automation Test Engineer with over 17 years of hands-on experience in the software testing industry.I specialize in tools like Selenium, Playwright, Appium, JMeter, and Excel automation. Through this blog, I share practical tutorials, expert tips, and real-world insights to help testers and developers improve their automation skills.In addition to software testing, I also explore tech trends and user-focused topics, including Snapchat guides, codeless test automation, and more.