1-Seletores.md

Seletores (Locators)

O Playwright usa Locators — objetos que representam como encontrar elementos na página. Ao contrário de seletores simples, locators têm auto-retry e suportam asserções automáticas.

Locators Recomendados (por prioridade)

getByRole — Por papel de acessibilidade

É o seletor mais recomendado. Alinhado com como usuários e leitores de tela percebem a página:

// Botão pelo nome
page.getByRole('button', { name: 'Entrar' })
page.getByRole('button', { name: /entrar/i })  // regex, case-insensitive

// Link
page.getByRole('link', { name: 'Saiba mais' })

// Heading
page.getByRole('heading', { name: 'Dashboard', level: 1 })

// Checkbox
page.getByRole('checkbox', { name: 'Lembrar-me' })

// Textbox (campo de texto)
page.getByRole('textbox', { name: 'Nome completo' })

// Combobox (select)
page.getByRole('combobox', { name: 'País' })

getByLabel — Por label de formulário

// Encontra o campo associado ao label "E-mail"
page.getByLabel('E-mail')
page.getByLabel('Senha')

getByPlaceholder — Pelo placeholder

page.getByPlaceholder('Digite seu e-mail')
page.getByPlaceholder('Ex: joao@email.com')

getByText — Por texto visível

page.getByText('Bem-vindo de volta!')
page.getByText('Bem-vindo', { exact: false })  // contém o texto
page.getByText(/^\d+ itens$/)                  // regex

getByAltText — Pelo atributo alt de imagens

page.getByAltText('Logo da empresa')
page.getByAltText('Foto do produto')

getByTestId — Por data-testid

Para quando nenhum dos anteriores funcionar, adicione data-testid no HTML:

<button data-testid="btn-confirmar">Confirmar</button>

page.getByTestId('btn-confirmar')

locator — CSS e XPath

Use como último recurso:

// CSS
page.locator('#meu-id')
page.locator('.minha-classe')
page.locator('input[type="email"]')

// XPath
page.locator('//button[@type="submit"]')

Combinando e Filtrando Locators

// Dentro de um container específico
const form = page.locator('form#login');
const email = form.getByLabel('E-mail');

// Filtrar por texto
page.getByRole('listitem').filter({ hasText: 'Produto A' })

// Filtrar por locator filho
page.getByRole('listitem').filter({ has: page.getByRole('img') })

// Nth — pegar o N-ésimo elemento (base 0)
page.getByRole('row').nth(2)

// First / Last
page.getByRole('listitem').first()
page.getByRole('listitem').last()

Prioridade de Seletores

Prioridade	Seletor	Por que usar
1	getByRole	Reflete acessibilidade real
2	getByLabel	Natural para formulários
3	getByPlaceholder	Para campos sem label
4	getByText	Para elementos de conteúdo
5	getByAltText	Para imagens
6	getByTestId	Quando nada mais funciona
7	locator(css/xpath)	Último recurso

---

Ir para: Comandos Básicos