// Buttons
page.getByRole('button', {name: 'Submit', exact: true}) // exact accessible name
page.getByRole('button', {name: /submit/i}) // flexible case-insensitive match

// Links
page.getByRole('link', {name: 'Home'})

// Form elements
page.getByRole('textbox', {name: 'Email'})
page.getByRole('checkbox', {name: 'Remember me'})
page.getByRole('combobox', {name: 'Country'})
page.getByRole('radio', {name: 'Option A'})

// Headings
page.getByRole('heading', {name: 'Welcome', level: 1})

// Lists & items
page.getByRole('list').getByRole('listitem')

// Navigation & regions
page.getByRole('navigation')
page.getByRole('main')
page.getByRole('dialog')
page.getByRole('alert')

// Input with <label for="email">
page.getByLabel('Email address')

// Input with aria-label
page.getByLabel('Search')

// Exact match
page.getByLabel('Email', {exact: true})

page.getByPlaceholder('Enter your email')
page.getByPlaceholder(/email/i)

// Partial match (default)
page.getByText('Welcome')

// Exact match
page.getByText('Welcome to our site', {exact: true})

// Regex
page.getByText(/welcome/i)

use: {
  testIdAttribute: 'data-testid' // default
}

// HTML: <button data-testid="submit-btn">Submit</button>
page.getByTestId('submit-btn')

// Filter by text
page.getByRole('listitem').filter({hasText: 'Product'})

// Filter by NOT having text
page.getByRole('listitem').filter({hasNotText: 'Out of stock'})

// Filter by child locator
page.getByRole('listitem').filter({
  has: page.getByRole('button', {name: 'Buy'}),
})

// Combine filters
page
  .getByRole('listitem')
  .filter({hasText: 'Product'})
  .filter({has: page.getByText('$9.99')})

// Navigate down the DOM tree
page.getByRole('article').getByRole('heading')

// Get parent/ancestor
page.getByText('Child').locator('..')
page.getByText('Child').locator('xpath=ancestor::article')

page.getByRole('listitem').first()
page.getByRole('listitem').last()
page.getByRole('listitem').nth(2) // 0-indexed

await page.getByRole('button').waitFor({state: 'visible'})
await page.getByText('Loading').waitFor({state: 'hidden'})

// Wait for specific count
await expect(page.getByRole('listitem')).toHaveCount(5)

// Get all matching elements
const items = await page.getByRole('listitem').all()
for (const item of items) {
  await expect(item).toBeVisible()
}

// Automatically finds elements inside shadow roots
page.getByRole('button', {name: 'Shadow Button'})

// Explicit shadow DOM traversal (if needed)
page.locator('my-component').locator('internal:shadow=button')

// By frame name or URL
const frame = page.frameLocator('iframe[name="content"]')
await frame.getByRole('button').click()

// By index
const frame = page.frameLocator('iframe').first()

// Nested iframes
const nestedFrame = page.frameLocator('#outer').frameLocator('#inner')
await nestedFrame.getByText('Content').click()

// Highlight element in headed mode
await page.getByRole('button').highlight()

// Count matches
const count = await page.getByRole('listitem').count()

// Check if exists without waiting
const exists = (await page.getByRole('button').count()) > 0

// Use Playwright Inspector
// PWDEBUG=1 npx playwright test