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:

As opções de Browser & Device são as mesmas do nó Web Flow — consulte a documentação do Web Flow para detalhes sobre presets de viewport e dispositivos mobile disponíveis.

Auditoria de Performance

Quando Auditoria de performance está habilitada, o Smart Locators monitora a sessão Playwright e gera evidências visuais de performance por tela.

O recurso coleta:

• Page Load da tela
• FCP (First Contentful Paint)
• LCP (Largest Contentful Paint)
• quantidade total de requests
• quantidade de requests de API
• erros de request/API
• APIs lentas por tela

Além do resumo global, o QANode gera checkpoints por tela navegada, com:

• nome da tela
• URL
• passo que originou a navegação
• gráfico das APIs mais lentas
• gráfico separado para erros de API quando existirem

Outputs de Performance

Quando a auditoria está ligada, o nó expõe:

• performancePassed
• performanceRequestCount
• performanceApiRequestCount
• performanceErrorCount
• performanceSlowRequestCount
• performance

O objeto performance contém um resumo estruturado da execução, incluindo os checkpoints por tela.

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.

Teste de Acessibilidade

O Smart Locators suporta escaneamento automático de acessibilidade com axe-core integrado. Quando ativado, o nó audita a página após cada passo que captura screenshot, identificando violações WCAG/ARIA e marcando visualmente os elementos problemáticos.

O Smart Locators já usa localizadores semânticos baseados em roles ARIA — combiná-lo com o escaneamento de acessibilidade é especialmente útil para verificar se os elementos que você interage passam nos critérios de acessibilidade.

Configuração

Como Funciona

A cada passo que tira screenshot, o axe-core é injetado na página e analisa o documento em busca de violações. As violações são desenhadas sobre o screenshot com caixas coloridas no elemento afetado e um painel de contagem no canto:

Ao final da execução são gerados automaticamente:

• Screenshots por passo — overlay com caixas coloridas + painel Critical N / Serious N / Moderate N / Minor N + top 2 regras
• Gráfico de severidade — {id}-accessibility-severity-chart.png — distribuição por nível
• Gráfico de regras — {id}-accessibility-rule-chart.png — top 8 regras mais violadas
• Relatório JSON — {id}-accessibility-report.json — dados completos de todas as violações

Critério de Aprovação

O nó falha se houver qualquer violação com severidade igual ou superior ao threshold configurado. Use none para nunca reprovar (coletar métricas sem bloquear o fluxo).

Exemplo: Verificar acessibilidade do formulário de login

Configuração do nó:
  Accessibility Scan: true
  Fail When Severity >= : serious

Passos:
1. navigate → https://meusite.com/login         (sem screenshot = sem scan)
2. fill → getByLabel("E-mail") → "..."           → screenshot after → scan executado
3. fill → getByLabel("Senha") → "..."            → screenshot after → scan executado
4. click → getByRole("button", { name: "Entrar" }) → screenshot after → scan executado
5. wait → networkIdle
6. assert → "loginOk" → textContains → getByText("Bem-vindo") → screenshot → scan executado

Se qualquer passo tiver violação serious ou critical, o nó é reprovado com:

"Accessibility findings at or above "serious" were detected."

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

Integração com Custom JavaScript

O nó Custom JavaScript tem acesso direto à sessão do Smart Locators, permitindo estender qualquer fluxo com lógica personalizada, asserções avançadas e manipulação da página usando a API completa do Playwright.

Variáveis disponíveis no Custom JS

Essas variáveis são populadas automaticamente a partir da sessão ativa. Use um nó Smart Locators antes do Custom JS com sessionMode: reuse para compartilhar a sessão.

Uso direto de page

Acesse a page diretamente para usar qualquer API do Playwright:

// Verificar texto com getByRole (mesmo modelo semântico do Smart Locators)
const heading = await page.getByRole('heading', { name: 'Bem-vindo' });
const texto = await heading.textContent();

// Verificar visibilidade
const botao = page.getByRole('button', { name: 'Enviar' });
const visivel = await botao.isVisible();

// Extrair valor de campo localizado por label
const campo = page.getByLabel('E-mail');
const valor = await campo.inputValue();

// Tirar screenshot personalizado
await page.screenshot({ path: '/tmp/resultado.png', fullPage: true });

Asserções com web.run()

Para usar o expect do Playwright (asserções nativas com retry automático):

await web.run(async ({ page, expect }) => {
  // Asserções semânticas — mesmo padrão do Smart Locators
  await expect(page.getByRole('button', { name: 'Enviar' })).toBeVisible();
  await expect(page.getByLabel('E-mail')).toBeEnabled();
  await expect(page.getByText('Sucesso')).toBeVisible();

  // Verificar URL após navegação
  await expect(page).toHaveURL('/dashboard');

  // Verificar título da página
  await expect(page).toHaveTitle(/Painel/);
});

O expect do Playwright faz retry automático por até 5 segundos, ideal para páginas com animações ou carregamento assíncrono.

Namespace web

Múltiplas sessões

Quando o fluxo possui vários nós Smart Locators rodando com sessões diferentes:

// Sessão do primeiro nó Smart Locators
const { page: page1 } = web.session('sessao-login');

// Sessão do segundo nó Smart Locators
const { page: page2 } = web.session('sessao-admin');

// Ações em paralelo em sessões diferentes
const [textoUsuario, textoAdmin] = await Promise.all([
  page1.getByRole('heading').textContent(),
  page2.getByRole('heading').textContent(),
]);

Exemplo prático: validar resultado de busca semântica

// Após nó Smart Locators que realizou uma busca
await web.run(async ({ page, expect }) => {
  // Verificar que lista de resultados está presente
  await expect(page.getByRole('list', { name: 'Resultados' })).toBeVisible();

  // Contar itens
  const itens = page.getByRole('listitem');
  const quantidade = await itens.count();

  if (quantidade === 0) {
    throw new Error('Nenhum resultado encontrado');
  }

  // Verificar que o primeiro resultado contém o termo buscado
  const termo = variables.TERMO_BUSCA;
  await expect(itens.first()).toContainText(termo);
});

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