How to Locate Elements by Test ID in Playwright?

Locating elements reliably is a critical part of any test automation strategy. In Playwright, one powerful approach is to locate elements by test ID. This method offers a clean and stable way to select UI elements that are meant to be interacted with during automated testing. Instead of relying on class names or fragile CSS selectors that might change with every UI update, test IDs provide a consistent identifier. Playwright supports selecting elements using getByTestId, making it easier to write resilient tests for modern web applications. When you follow this best practice, your test code becomes easier to maintain and less likely to break due to frontend changes.

Using a test ID is one of the most dependable ways to select elements in your testing suite. When you locate element by test ID in Playwright, it ensures that your selectors remain clean, readable, and closely aligned with the app’s intended testing logic. Test IDs are typically added by developers specifically for testing purposes, which means they won’t be removed or modified unintentionally. As a result, your test scripts become more robust and maintainable, especially in large-scale projects with frequent UI changes.

What is Test ID in Playwright?

In Playwright, a test id is a custom attribute used to identify elements specifically for testing. It doesn’t interfere with your app’s functionality or layout, making it a clean solution for stable element selection. Typically, the attribute used is data-testid.

Why Use Test ID Locators?

Using test ID locators comes with several advantages:

• More stable than class or ID selectors
• Unaffected by design or layout changes
• Improves test readability
• Avoids brittle selectors like XPath

Syntax to Locate Elements by Test ID In Playwright

Playwright uses the getByTestId() method via its Testing Library queries, or you can use locator(‘[data-testid=”your-id”]’) for direct access. You can also configure Playwright to recognize data-testid as a default test ID attribute.

Syntax:

const element = page.getByTestId('submit-button');

const element = page.getByTestId('submit-button');

This line finds the element that has data-testid=”submit-button” on the page.

Real-World Example

HTML Code:

<button data-testid="login-btn">Login</button>

<button data-testid="login-btn">Login</button>

Playwright Test Code:

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

test('Login button should be visible', async ({ page }) => {
  await page.goto('Your site URL');
  
  //Locate login button element by test id.
  const loginButton = page.getByTestId('login-btn');
  
  //assert login button is visible.
  await expect(loginButton).toBeVisible();
});

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

test('Login button should be visible', async ({ page }) => {
  await page.goto('Your site URL');
  
  //Locate login button element by test id.
  const loginButton = page.getByTestId('login-btn');
  
  //assert login button is visible.
  await expect(loginButton).toBeVisible();
});

Best Practices to locate elements by Test ID

• Use consistent naming — Stick to a naming convention like data-testid=”login-input”.
• Keep test IDs semantic — Use IDs that describe the purpose, not the appearance.
• Avoid duplication — Ensure each data-testid is unique across your app.
• Do not reuse production attributes — Keep test attributes separate from class names or ARIA labels.

Common Errors to Avoid

• Using getByTestId without assigning data-testid in the HTML.
• Using dynamic or duplicate test IDs.
• Trying to locate nested elements without proper hierarchy.

Alternatives to Test ID Locators

If data-testid is not available, Playwright supports:

• getByRole() – Best for accessible elements like buttons, links
• getByLabel() – For form fields associated with labels
• locator(‘css selector’) – As a fallback for custom structures

Still, getByTestId() is the preferred method when accessibility is insufficient

When Not to Use getByTestId

While using getByTestId is often recommended, there are times when other locators might be better:

• For accessibility testing, use getByRole.
• When data-testid is not available, fallback to other reliable attributes.

Final Thoughts

Learning to locate elements by test ID in Playwright can make your automated tests more reliable and easier to maintain. By using getByTestId, you ensure your locators remain stable even as the UI changes. Combine this with best practices and avoid common pitfalls to get the most out of your Playwright tests.

If your test involves complex UI elements or dynamic content, data-testid is your best friend.

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 tech troubleshooting and 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.