Nodo Smart Locators

El nodo Smart Locators permite automatizar interacciones con páginas web usando localizadores semánticos de Playwright — basados en roles ARIA, labels, placeholders y otros atributos de accesibilidad. Este enfoque es más resiliente que los selectores CSS, ya que refleja cómo los usuarios realmente encuentran los elementos en la página.

Consejo: Si prefieres selectores CSS y XPath tradicionales, usa el nodo Web Flow.

Descripción General

Configuración General

Idéntica al nodo Web Flow:

Las opciones de Navegador & Dispositivo son idénticas al nodo Web Flow — consulta la documentación de Web Flow para detalles sobre presets de viewport y dispositivos mobile disponibles.

Auditoría de Rendimiento

Cuando Auditoría de rendimiento está habilitada, Smart Locators monitorea la sesión activa de Playwright y genera evidencias visuales de rendimiento por pantalla.

La función recoge:

• Page Load
• FCP (First Contentful Paint)
• LCP (Largest Contentful Paint)
• cantidad total de solicitudes
• cantidad de solicitudes de API
• errores de solicitud/API
• APIs lentas por pantalla

Además del resumen global, QANode genera checkpoints por pantalla con:

• nombre de la pantalla
• URL
• paso que originó la navegación
• gráfico de las APIs más lentas
• gráfico separado de errores de API cuando existan en esa pantalla

Outputs de Rendimiento

Cuando la auditoría está activa, el nodo expone:

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

El objeto performance contiene un resumen estructurado de la ejecución, incluidos los checkpoints por pantalla.

Self Healing

Cuando Self Healing está habilitado, Smart Locators puede recuperar automáticamente acciones basadas en localizadores semánticos cuando el locator original deja de encontrar el elemento esperado.

Además del propio locator semántico, el motor considera:

• texto y nombre accesible del elemento
• role
• label, placeholder, title y otros atributos relevantes
• contexto estructural de la página, como contenedor, formulario, heading y posición relativa

Esto ayuda en escenarios como:

• cambios de texto con el mismo significado
• cambios entre mayúsculas y minúsculas
• texto con o sin acentos
• variaciones cortas, como Ingresar → Login o Siguiente → Continuar

La función es conservadora: solo aplica la recuperación cuando encuentra un candidato claramente más fuerte que los demás, evitando “adivinar” en pantallas ambiguas.

Cuando un paso es recuperado, la ejecución muestra:

• el paso afectado
• la confianza de la recuperación
• el locator utilizado
• una opción Aplicar al Flujo para actualizar el flujo con el locator recuperado

Sistema de Localizadores

Métodos de Localización

En lugar de selectores CSS, Smart Locators usa métodos semánticos de Playwright:

Configuración del Localizador

ARIA Roles Disponibles

Para el método getByRole, están disponibles los siguientes roles:

Ejemplo de uso:

Método: getByRole
Valor: button
Nombre: Ingresar

Equivale en Playwright a: page.getByRole('button', { name: 'Ingresar' })

Acciones Disponibles

Detalles de las Acciones

navigate

Navega a una URL.

click

Hace clic en un elemento localizado semánticamente.

El click espera a que el elemento sea visible, se desplaza hasta él si es necesario, y luego hace clic. Si falla, vuelve a intentarlo.

Ejemplo:

Método: getByRole
Valor: button
Nombre: Enviar
Intentos: 3

dblclick

Doble clic en un elemento.

fill

Rellena un campo de entrada instantáneamente (reemplaza el valor).

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

type

Escribe texto carácter por carácter, simulando la escritura real.

Usa locator.pressSequentially() de Playwright — ideal para campos con:

• Autocompletado (sugerencias aparecen mientras se escribe)
• Máscaras (teléfonos, códigos postales)
• Validación on-keypress (valida cada tecla)

Ejemplo:

Localizador: getByPlaceholder → "Teléfono"
Texto: 123.456.789-00
Delay: 100ms

check / uncheck

Marca o desmarca un checkbox/radio button.

Ejemplo:

Método: getByLabel
Valor: Acepto los términos de uso

selectOption

Selecciona una opción de un dropdown (<select>).

hover

Pasa el mouse sobre un elemento.

focus

Establece el foco en un elemento.

press

Presiona una tecla del teclado en el contexto de un elemento.

assert

Verifica condiciones en la página. Ofrece múltiples modos de verificación:

Modos de Assert:

Ejemplos:

// Verificar que el botón "Enviar" es visible
Modo: visible, Localizador: getByRole("button", "Enviar")

// Verificar que el mensaje contiene "Éxito"
Modo: textContains, Localizador: getByText("Éxito"), Esperado: "Éxito"

// Verificar URL después del inicio de sesión
Modo: hasURL, Esperado: "/dashboard"

// Verificar que el campo está deshabilitado
Modo: disabled, Localizador: getByLabel("Correo electrónico")

extract

Extrae datos de un elemento.

Atributos disponibles:

wait

Espera una condición.

scroll

Desplaza la página.

refresh

Recarga la página. Misma configuración que Web Flow.

frame

Cambia a un iframe. Soporta los modos name y main (volver al principal).

Evidencias (Screenshots por Paso)

Idéntico a Web Flow — cada paso puede tener configuración individual de captura de screenshot.

Prueba de Accesibilidad

Smart Locators soporta escaneo automático de accesibilidad con axe-core integrado. Cuando está habilitado, el nodo audita la página después de cada paso que captura un screenshot, identificando violaciones WCAG/ARIA y marcando visualmente los elementos afectados.

Smart Locators ya usa localizadores semánticos basados en roles ARIA — combinarlo con el escaneo de accesibilidad es especialmente útil para verificar que los elementos con los que interactúas cumplen los criterios de accesibilidad.

Configuración

Cómo Funciona

Después de cada paso que toma un screenshot, axe-core es inyectado en la página y analiza el documento en busca de violaciones. Las violaciones se dibujan sobre el screenshot con cajas de colores alrededor de los elementos afectados y un panel de conteo en la esquina:

Al final de la ejecución se generan automáticamente:

• Screenshots por paso — overlay con cajas de colores + panel Critical N / Serious N / Moderate N / Minor N + top 2 reglas
• Gráfico de severidad — {id}-accessibility-severity-chart.png — distribución por nivel
• Gráfico de reglas — {id}-accessibility-rule-chart.png — top 8 reglas más violadas
• Reporte JSON — {id}-accessibility-report.json — datos completos de todas las violaciones

Criterio de Aprobación

El nodo falla si hay cualquier violación con severidad igual o superior al umbral configurado. Usa none para nunca reprobar (recolectar métricas sin bloquear el flujo).

Ejemplo: Verificar accesibilidad del formulario de inicio de sesión

Configuración del nodo:
  Accessibility Scan: true
  Fail When Severity >= : serious

Pasos:
1. navigate → https://misitio.com/login               (sin screenshot = sin escaneo)
2. fill → getByLabel("Correo electrónico") → "..."     → screenshot after → escaneo ejecutado
3. fill → getByLabel("Contraseña") → "..."             → screenshot after → escaneo ejecutado
4. click → getByRole("button", { name: "Ingresar" })  → screenshot after → escaneo ejecutado
5. wait → networkIdle
6. assert → "loginOk" → textContains → getByText("Bienvenido") → screenshot → escaneo ejecutado

Si cualquier paso tiene una violación serious o critical, el nodo falla con:

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

Outputs

Ejemplo Completo: Inicio de Sesión con Smart Locators

Paso 1: navigate → https://misitio.com/login
Paso 2: fill → getByLabel("Correo electrónico") → "{{ variables.EMAIL }}"
Paso 3: fill → getByLabel("Contraseña") → "{{ variables.CONTRASENA }}"
Paso 4: click → getByRole("button", { name: "Ingresar" })
Paso 5: wait → networkIdle
Paso 6: assert → "loginOk" → textContains → getByText("Bienvenido")
Paso 7: extract → "userName" → getByRole("heading") → text

Cuándo Usar Smart Locators vs Web Flow

Consejos

• Prefiere getByRole — es el más resiliente y refleja cómo las tecnologías asistivas encuentran los elementos
• Usa getByLabel para campos de formulario — es más estable que CSS
• getByTestId es excelente para elementos sin role/label claro
• Usa la acción type (en lugar de fill) para campos con máscaras o autocompletado
• El campo Nth permite seleccionar un elemento específico cuando múltiples coinciden con el localizador