Nó Smart Locators

O nó Smart Locators permite automatizar interações com páginas web usando localizadores semânticos do Playwright — baseados em roles ARIA, labels, placeholders e outros atributos de acessibilidade. Esta abordagem é mais resiliente que seletores CSS, pois reflete como os usuários realmente encontram elementos na página.

Dica: Se preferir seletores CSS e XPath tradicionais, use o nó Web Flow.

Visão Geral

Configuração Geral

Idêntica ao nó Web Flow:

Sistema de Localizadores

Métodos de Localização

Em vez de seletores CSS, o Smart Locators usa métodos semânticos do Playwright:

Configuração do Localizador

ARIA Roles Disponíveis

Para o método getByRole, os seguintes roles estão disponíveis:

Exemplo de uso:

Método: getByRole
Valor: button
Nome: Entrar

Equivale ao Playwright: page.getByRole('button', { name: 'Entrar' })

Ações Disponíveis

Detalhes das Ações

navigate

Navega para uma URL.

click

Clica em um elemento localizado semanticamente.

O click aguarda o elemento ficar visível, rola até ele se necessário, e então clica. Se falhar, tenta novamente.

Exemplo:

Método: getByRole
Valor: button
Nome: Enviar
Tentativas: 3

dblclick

Duplo clique em um elemento.

fill

Preenche um campo de entrada instantaneamente (substitui o valor).

Usa locator.fill() do Playwright — ideal para campos simples.

type

Digita texto caractere por caractere, simulando digitação real.

Usa locator.pressSequentially() do Playwright — ideal para campos com:

• Autocomplete (sugestões aparecem enquanto digita)
• Máscaras (CPF, telefone, CEP)
• Validação on-keypress (verifica cada tecla)

Exemplo:

Localizador: getByPlaceholder → "CPF"
Texto: 123.456.789-00
Delay: 100ms

check / uncheck

Marca ou desmarca um checkbox/radio button.

Exemplo:

Método: getByLabel
Valor: Aceito os termos de uso

selectOption

Seleciona uma opção de um dropdown (<select>).

hover

Passa o mouse sobre um elemento.

focus

Define o foco em um elemento.

press

Pressiona uma tecla do teclado no contexto de um elemento.

assert

Verifica condições na página. Oferece múltiplos modos de verificação:

Modos de Assert:

Exemplos:

// Verificar que botão "Enviar" está visível
Modo: visible, Localizador: getByRole("button", "Enviar")

// Verificar que mensagem contém "Sucesso"
Modo: textContains, Localizador: getByText("Sucesso"), Esperado: "Sucesso"

// Verificar URL após login
Modo: hasURL, Esperado: "/dashboard"

// Verificar que campo está desabilitado
Modo: disabled, Localizador: getByLabel("E-mail")

extract

Extrai dados de um elemento.

Atributos disponíveis:

wait

Aguarda uma condição.

scroll

Rola a página.

refresh

Recarrega a página. Mesma configuração do Web Flow.

frame

Alterna para iframe. Suporta modos name e main (voltar ao principal).

Evidências (Screenshots por Passo)

Idêntico ao Web Flow — cada passo pode ter configuração individual de captura de screenshot.

Outputs

Exemplo Completo: Login com Smart Locators

Passo 1: navigate → https://meusite.com/login
Passo 2: fill → getByLabel("E-mail") → "{{ variables.EMAIL }}"
Passo 3: fill → getByLabel("Senha") → "{{ variables.SENHA }}"
Passo 4: click → getByRole("button", { name: "Entrar" })
Passo 5: wait → networkIdle
Passo 6: assert → "loginOk" → textContains → getByText("Bem-vindo")
Passo 7: extract → "userName" → getByRole("heading") → text

Quando Usar Smart Locators vs Web Flow

Dicas

• Prefira getByRole — é o mais resiliente e reflete como assistive technologies encontram elementos
• Use getByLabel para campos de formulário — é mais estável que CSS
• getByTestId é ótimo para elementos sem role/label claro
• Use a ação type (em vez de fill) para campos com máscaras ou autocomplete
• O campo Nth permite selecionar um elemento específico quando múltiplos correspondem ao localizador