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: Para fluxos web novos gravados pela extensão, prefira o Smart Web Flow. Se preferir seletores CSS e XPath tradicionais em fluxos legados, 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.

Self Healing

Quando Self Healing está habilitado, o Smart Locators tenta recuperar automaticamente ações baseadas em localizadores semânticos quando o locator original deixa de encontrar o elemento esperado.

Além do próprio locator semântico, o mecanismo considera:

• texto e nome acessível do elemento
• role
• label, placeholder, title e outros atributos relevantes
• contexto estrutural da página, como container, formulário, heading e posição relativa

Isso ajuda em cenários como:

• mudança de texto com o mesmo significado
• troca entre maiúsculas/minúsculas
• texto com ou sem acento
• variações curtas, como Entrar → Login ou Avançar → Continuar

O recurso é conservador: ele só aplica a recuperação quando encontra um candidato claramente mais forte que os demais, evitando “chutes” em telas ambíguas.

Quando um passo é recuperado, a execução mostra:

• o passo afetado
• a confiança da recuperação
• o locator utilizado
• a opção Aplicar ao Fluxo para atualizar o fluxo com o locator recuperado

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.

switchPage

Troca a página ativa da sessão quando um clique, link ou ação abre uma nova aba/janela e os próximos passos precisam continuar nela.

Modos:

Quando a extensão identifica links que abrem nova aba, ela pode inserir este passo automaticamente. Em fluxos manuais, adicione switchPage depois do click que abre a aba.

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.

drag

Arrasta um elemento localizado semanticamente e solta sobre outro localizador ou em coordenadas gravadas.

O Smart Locators tenta usar os localizadores semânticos do Playwright, como getByRole, getByText, getByLabel e getByTestId. Quando a página possui elementos repetidos e o passo vem da extensão, o JSON pode carregar metadados internos de posição para ajudar o executor a escolher o elemento mais próximo do gesto original. Esses metadados não aparecem como campos principais no painel.

Para componentes de drag/drop, o QANode também tenta promover o localizador semântico para o container interativo real. Isso é útil quando o texto clicado fica dentro de outro elemento arrastável, por exemplo:

• Um <p> dentro de um card arrastável
• Uma imagem dentro de um container draggable
• Uma área de drop marcada por classe ou atributos de drop

Se o destino semântico for genérico demais ou falhar, mas houver Destino X / Y, o Smart Locators pode usar as coordenadas gravadas como fallback. Isso permite automatizar canvas, Kanban e áreas de soltar que não têm texto, role ou label próprios.

Boas práticas:

• Prefira componentes com nomes acessíveis (aria-label, texto visível, labels)
• Use data-testid ou data-qa para cards, colunas e áreas de drop críticas
• Evite botões apenas com ícone sem aria-label
• Revise gravações que dependam de nth, principalmente quando há textos repetidos
• Use screenshots before e after para comprovar visualmente o movimento

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:

extractList

Itera sobre elementos repetidos na página — linhas de tabela, cards, itens de lista — e extrai um ou mais campos de cada item, produzindo um array de objetos no output.

Cada entrada em Campos define:

Os dados extraídos ficam disponíveis nos outputs:

{{ steps["smart-locators"].outputs.extracts.lista_pedidos }}
// → [ { numero: "#1042", status: "Enviado" }, { numero: "#1041", status: "Entregue" } ]

Para gravar um passo extractList automaticamente pela extensão Chrome, use Ctrl+Shift+E durante a gravação.

wait

Aguarda uma condição.

scroll

Rola a página.

refresh

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

clock

Controla o relógio do navegador usando page.clock do Playwright. A ação é a mesma disponível no Web Flow e pode ser usada para validar comportamentos por data/hora sem depender do horário real da máquina.

Novos passos de clock nascem com o reload desligado. Use reload ligado apenas quando a aplicação depende do carregamento da página para recalcular datas ou horários.

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 });

// Controlar data/hora dentro da mesma sessão Playwright
await page.clock.install({ time: new Date('2026-04-24T10:00:00') });
await page.clock.fastForward('20:00');

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