Locators That Don't Break

The #1 reason tests break after deployments? Brittle locators. A developer changes a CSS class, and suddenly 50 tests fail. Let's fix that.

The Locator Hierarchy

Playwright recommends locators in this priority order:

1. getByRole()     → Best: matches how users see the page
2. getByText()     → Good: visible text content
3. getByLabel()    → Good: form accessibility
4. getByTestId()   → Good: explicit test contracts
5. CSS selectors   → Okay: when nothing else works
6. XPath           → Last resort: complex DOM traversal

Why this order? User-facing locators are stable. If your "Add to Cart" button changes from to , a CSS selector breaks. But getByRole('button', { name: 'Add to Cart' }) keeps working.

Role-Based Locators (Best Practice)

getByRole()

Matches elements by their ARIA role and accessible name:

// Buttons
await page.getByRole('button', { name: 'Add to Cart' }).click();
await page.getByRole('button', { name: 'Proceed to Checkout' }).click();

// Links
await page.getByRole('link', { name: 'View Details' }).click();
await page.getByRole('link', { name: 'My Account' }).click();

// Headings
await expect(page.getByRole('heading', { name: 'Shopping Cart' })).toBeVisible();

// Navigation
await page.getByRole('navigation').getByRole('link', { name: 'Products' }).click();

// Form elements
await page.getByRole('textbox', { name: 'Email' }).fill('john@example.com');
await page.getByRole('spinbutton', { name: 'Quantity' }).fill('3');
await page.getByRole('checkbox', { name: 'Subscribe to newsletter' }).check();
await page.getByRole('combobox', { name: 'Country' }).selectOption('United States');

Common Roles for E-Commerce

Element	Role	Example
	button	Add to Cart, Buy Now
	link	Product links, navigation
	textbox	Search, form fields
	spinbutton	Quantity selector
	combobox	Size, color dropdowns
	checkbox	Newsletter signup
	radio	Shipping options
-	heading	Page titles
	img	Product images
table Order history dialog Cart modal, popups Name Matching Options // Exact match (default) page.getByRole('button', { name: 'Add to Cart' }); // Case-insensitive page.getByRole('button', { name: 'add to cart', exact: false }); // Regex pattern page.getByRole('button', { name: /add to cart/i }); // Partial match page.getByRole('heading', { name: /checkout/i }); Text-Based Locators getByText() Finds elements containing specific text: // Product name on page await page.getByText('Wireless Bluetooth Headphones').click(); // Price (be specific to avoid matching multiple prices) await expect(page.getByText('$129.99')).toBeVisible(); // Status messages await expect(page.getByText('Item added to cart')).toBeVisible(); await expect(page.getByText('Order confirmed')).toBeVisible(); // Partial text match await page.getByText('Free shipping', { exact: false }).click(); getByLabel() Essential for form fields: // Checkout form await page.getByLabel('First Name').fill('John'); await page.getByLabel('Last Name').fill('Doe'); await page.getByLabel('Email Address').fill('john@example.com'); await page.getByLabel('Credit Card Number').fill('4111111111111111'); await page.getByLabel('Expiration Date').fill('12/25'); await page.getByLabel('CVV').fill('123'); // Shipping options await page.getByLabel('Standard Shipping ($5.99)').check(); await page.getByLabel('Express Shipping ($15.99)').check(); getByPlaceholder() When labels are missing (not ideal, but common): await page.getByPlaceholder('Search products...').fill('laptop'); await page.getByPlaceholder('Enter promo code').fill('SAVE20'); Test ID Locators getByTestId() When you control the application, add explicit test IDs: // In your application code <button data-testid="add-to-cart-btn">Add to Cart</button> <div data-testid="cart-total">$129.99</div> <span data-testid="cart-count">3</span> // In your tests await page.getByTestId('add-to-cart-btn').click(); await expect(page.getByTestId('cart-total')).toHaveText('$129.99'); await expect(page.getByTestId('cart-count')).toHaveText('3'); Custom Test ID Attribute If your app uses a different attribute: // playwright.config.ts export default defineConfig({ use: { testIdAttribute: 'data-test', // or 'data-cy', 'data-qa' }, }); // Now getByTestId looks for data-test="..." await page.getByTestId('product-card').click(); When to Use Test IDs Use test IDs when: Element has no accessible role or text Multiple similar elements exist You need a stable contract between dev and QA // Product grid with many similar items // HTML: <div data-testid="product-card-SKU123">...</div> await page.getByTestId('product-card-SKU123').click(); // Dynamic content // HTML: <span data-testid="inventory-count">5 left</span> await expect(page.getByTestId('inventory-count')).toContainText('left'); CSS Selectors (When Necessary) Sometimes you need CSS: // Class-based (fragile, but sometimes necessary) await page.locator('.product-card').first().click(); // Attribute selectors await page.locator('[data-product-id="12345"]').click(); // Combining attributes await page.locator('button[type="submit"]').click(); // Structural selectors await page.locator('.product-grid > div:first-child').click(); // State-based await page.locator('input:enabled').fill('test'); Chaining and Filtering Narrowing Down Locators // Find product card, then button within it const productCard = page.locator('.product-card').filter({ hasText: 'Laptop' }); await productCard.getByRole('button', { name: 'Add to Cart' }).click(); // Filter by child content const expensiveProducts = page.locator('.product-card').filter({ has: page.getByText('$500', { exact: false }), }); // Chain locators await page .getByRole('navigation') .getByRole('link', { name: 'Electronics' }) .click(); Working with Lists E-commerce pages often have product lists: // Get all product cards const products = page.getByTestId('product-card'); // Count products const count = await products.count(); console.log(`Found ${count} products`); // Work with specific items await products.first().click(); await products.last().click(); await products.nth(2).click(); // Third item (0-indexed) // Iterate over products for (const product of await products.all()) { const name = await product.getByRole('heading').textContent(); console.log(name); } E-Commerce Locator Patterns Product Card // Good: Test ID for container, roles for content async function getProduct(page: Page, productName: string) { const card = page.locator('[data-testid="product-card"]').filter({ hasText: productName, }); return { card, name: card.getByRole('heading'), price: card.getByTestId('product-price'), addToCart: card.getByRole('button', { name: 'Add to Cart' }), image: card.getByRole('img'), }; } // Usage const laptop = await getProduct(page, 'MacBook Pro'); await expect(laptop.price).toHaveText('$1,299.00'); await laptop.addToCart.click(); Cart Items // Cart item row function getCartItem(page: Page, productName: string) { const row = page.getByRole('row').filter({ hasText: productName }); return { row, quantity: row.getByRole('spinbutton'), price: row.getByTestId('item-price'), remove: row.getByRole('button', { name: 'Remove' }), subtotal: row.getByTestId('item-subtotal'), }; } // Usage const item = getCartItem(page, 'Wireless Mouse'); await item.quantity.fill('3'); await expect(item.subtotal).toHaveText('$89.97'); Checkout Form // Shipping address await page.getByRole('group', { name: 'Shipping Address' }).within(async () => { // This doesn't work in Playwright - use chaining instead }); // Instead, use this pattern: const shippingSection = page.getByRole('group', { name: 'Shipping Address' }); await shippingSection.getByLabel('Street Address').fill('123 Main St'); await shippingSection.getByLabel('City').fill('San Francisco'); await shippingSection.getByLabel('State').selectOption('California'); await shippingSection.getByLabel('ZIP Code').fill('94102'); Filters and Sorting // Category filter await page.getByRole('checkbox', { name: 'Electronics' }).check(); await page.getByRole('checkbox', { name: 'Under $100' }).check(); // Sort dropdown await page.getByRole('combobox', { name: 'Sort by' }).selectOption('price-low-high'); // Price range slider (custom handling often needed) const minPrice = page.getByRole('slider', { name: 'Minimum price' }); await minPrice.fill('50'); Why Locators Survive Refactoring Consider a product card redesign: Before: <div class="product-card old-style"> <h3 class="title">Laptop</h3> <span class="price">$999</span> <button class="btn btn-primary add-cart">Add to Cart</button> </div> After: <article class="ProductCard ProductCard--modern"> <h2 class="ProductCard__title">Laptop</h2> <div class="ProductCard__price">$999</div> <button class="ProductCard__button">Add to Cart</button> </article> Locator Type Before After Broken? .product-card Works Fails Yes .btn-primary Works Fails Yes h3.title Works Fails Yes getByRole('heading', { name: 'Laptop' }) Works Works No getByRole('button', { name: 'Add to Cart' }) Works Works No getByText('$999') Works Works No Role and text-based locators survived because they match user perception, not implementation. Debugging Locators Playwright Inspector npx playwright test --debug Opens an inspector where you can: Hover over elements to see suggested locators Try locators in the console Step through tests Pick Locator Tool npx playwright codegen https://www.saucedemo.com Opens a browser where: Click any element to see recommended locators Locators are copied to clipboard Multiple suggestions shown Locator Console In UI mode or debug mode: // In the console await page.locator('.product-card').count(); // How many matched? await page.getByRole('button').allTextContents(); // What buttons exist? await page.locator('.cart-item').evaluateAll(els => els.map(e => e.textContent)); Key Takeaways Prefer role-based locators: getByRole() matches user perception and survives refactoring Text locators are stable: Users see text, so text-based locators are durable Test IDs create contracts: Explicit agreement between devs and QA CSS/XPath are fallbacks: Use only when semantic locators fail Chain for precision: Narrow down with .filter() and nested locators Use codegen: Let Playwright suggest the best locators Next Lesson You've learned to find elements reliably. But what happens after you find them? In the next lesson, we'll explore auto-wait and web-first assertions - how Playwright ensures your actions succeed without manual waits. Setup & First Test Mark Complete +200 XP 🎉 Lesson Complete! Great work! Keep up the momentum. +200 XP Earned 0 Total XP 0 Day Streak Review Lesson Next Lesson Get Your Free Resource Enter your details to access Program Interested* Select Program Software Development Data Analytics QA 🇮🇳 +91 Are you currently working?* Yes No Graduation Year* Select Year 2030 2029 2028 2027 2026 2025 2024 2023 2022 2021 2020 2019 or earlier I agree to receive SMS & WhatsApp communications from Crio.Do Get Access Your information is secure and will never be shared. Start Your Free Trial Choose a track to begin your learning journey Software Development Full Stack, Frontend, Backend Data Analytics Python, SQL, Data Science QA & SDET Selenium, API Testing, Automation All trials are 100% free. No credit card required. Your Interactive Session is Ready Watch a real Crio class demo and chat with our team in real-time. See exactly what you'll learn. Experience a live class environment Chat with our team during the session See real projects you'll build ~45 minutes, watch at your pace Join Session or Quick Skill Check NEW (2 min) Not sure? Take a quick assessment to see where you stand