Finding Elements with Semantic Locators in Playwright

The Treasure Hunt Story

Imagine you’re on a treasure hunt in a huge toy store! 🏪 The store has thousands of toys, and you need to find specific ones. But here’s the magic: instead of running around randomly, you have 7 special maps that help you find exactly what you want.

These maps are called Semantic Locators in Playwright. “Semantic” just means they understand what things mean — like finding a toy by what it does or what it’s called, not just where it sits on the shelf.

Why Semantic Locators Are Your Best Friends

Think about finding your friend in a crowded playground:

• ❌ Bad way: “Find the person standing 47 steps from the gate” (what if they move?)
• ✅ Good way: “Find Sarah, the girl in the red hat” (that’s who she IS!)

Semantic locators work the same way. They find elements by what they are and what they do, not by fragile details that might change.

The 7 Magic Maps (Locators)

Let’s learn each one with simple examples!

1. getByRole — Find by What It Does

The Idea: Every button, link, or textbox has a “job” on a webpage. This locator finds things by their job (role).

Simple Analogy: It’s like finding helpers in a store by their uniform:

• 🛒 Cashier wears an apron = button
• 📦 Stock person wears a vest = textbox
• 🚪 Security wears a badge = link

// Find a button that says "Submit"
page.getByRole('button', { name: 'Submit' })

// Find a textbox for email
page.getByRole('textbox', { name: 'Email' })

// Find a link that says "Home"
page.getByRole('link', { name: 'Home' })

Common Roles:

• button — Clickable buttons
• textbox — Input fields for typing
• link — Clickable links
• checkbox — Tick boxes
• heading — Titles (h1, h2, etc.)

2. getByText — Find by What It Says

The Idea: Find something by the words written on it. Simple!

Simple Analogy: Finding a book by its title on the cover.

// Find anything that says "Welcome"
page.getByText('Welcome')

// Find text that contains "Hello"
page.getByText('Hello', { exact: false })

// Find EXACTLY "Sign Up" (not "Sign Up Now")
page.getByText('Sign Up', { exact: true })

When to Use: Perfect for finding labels, paragraphs, or any visible text on the page.

3. getByLabel — Find by Its Name Tag

The Idea: Form fields often have labels next to them (like “Username:” or “Password:”). This finds the input box by its label.

Simple Analogy: It’s like finding a jar by reading its label — “Sugar”, “Salt”, “Cookies” 🍪

// Find the input field labeled "Username"
page.getByLabel('Username')

// Find the input field labeled "Password"
page.getByLabel('Password')

// Find checkbox labeled "Remember me"
page.getByLabel('Remember me')

Pro Tip: This is SUPER useful for forms because labels are meant for humans to read!

4. getByPlaceholder — Find by Ghost Text

The Idea: Some input boxes have faded “hint text” inside them before you type. This finds boxes by that hint.

Simple Analogy: Finding an empty box by the faded writing that says “Put toys here”

// Find input with placeholder "Enter email"
page.getByPlaceholder('Enter email')

// Find input with placeholder "Search..."
page.getByPlaceholder('Search...')

// Find input with placeholder "Type here"
page.getByPlaceholder('Type here')

When to Use: Great for search boxes and forms without visible labels.

5. getByAltText — Find Images by Description

The Idea: Images have invisible descriptions (alt text) for screen readers. This finds images by that description.

Simple Analogy: It’s like finding a photo by reading the caption on the back!

// Find image with alt text "Company Logo"
page.getByAltText('Company Logo')

// Find image with alt text "User Avatar"
page.getByAltText('User Avatar')

// Find image with alt text "Product Image"
page.getByAltText('Product Image')

When to Use: Perfect for clicking on images, logos, or icons.

6. getByTitle — Find by Tooltip

The Idea: Some elements show a small popup (tooltip) when you hover over them. This finds things by their tooltip text.

Simple Analogy: Like finding a tool in a workshop by the small tag attached to it!

// Find element with title "Close"
page.getByTitle('Close')

// Find element with title "Settings"
page.getByTitle('Settings')

// Find element with title "More options"
page.getByTitle('More options')

When to Use: Great for icon buttons that don’t have visible text.

7. getByTestId — Find by Secret Code

The Idea: Developers can add a special hidden ID just for testing. It’s like a secret handshake!

Simple Analogy: Finding your locker using your personal locker number that only you know.

// Find element with data-testid="submit-btn"
page.getByTestId('submit-btn')

// Find element with data-testid="user-profile"
page.getByTestId('user-profile')

// Find element with data-testid="nav-menu"
page.getByTestId('nav-menu')

When to Use: When other locators won’t work, or when developers add test IDs specifically for you.

Quick Decision Guide

graph LR
    A[Need to find an element?] --> B{What do you know?}
    B --> C[Its job/role] --> C1[getByRole]
    B --> D[What it says] --> D1[getByText]
    B --> E[Its label] --> E1[getByLabel]
    B --> F[Placeholder text] --> F1[getByPlaceholder]
    B --> G[Image description] --> G1[getByAltText]
    B --> H[Tooltip text] --> H1[getByTitle]
    B --> I[Test ID] --> I1[getByTestId]

The Priority Order

Playwright recommends this order (best first):

1. getByRole — Most reliable, works like humans think
2. getByLabel — Perfect for form fields
3. getByPlaceholder — Good for inputs without labels
4. getByText — Find any visible text
5. getByAltText — For images
6. getByTitle — For tooltips
7. getByTestId — Last resort when nothing else works

Real-World Example

Imagine a login form:

<form>
  <label for="email">Email Address</label>
  <input id="email" type="email"
         placeholder="you@example.com">

  <label for="pass">Password</label>
  <input id="pass" type="password"
         placeholder="Enter password">

  <button type="submit">Sign In</button>
</form>

Finding each element:

// By label (recommended!)
page.getByLabel('Email Address')
page.getByLabel('Password')

// By placeholder
page.getByPlaceholder('you@example.com')
page.getByPlaceholder('Enter password')

// By role + name
page.getByRole('textbox', { name: 'Email' })
page.getByRole('button', { name: 'Sign In' })

// By text
page.getByText('Sign In')

Remember This!

You Did It! 🎉

You now know all 7 semantic locators in Playwright! They’re your treasure maps to find any element on a webpage. Start with getByRole and getByLabel — they’ll solve 90% of your problems!

Next Step: Practice using these locators on real webpages. The more you use them, the faster you’ll find elements!