Smart Locator Framework

Framework de automatización de tests E2E con sistema inteligente de localización de elementos que elimina tests frágiles.

---

El Problema

Los tests de automatización son frágiles. Cuando los desarrolladores cambian un id, class o la estructura del DOM:

// Test tradicional - Se rompe fácilmente
await page.click('#login-button');  // Falla si cambia el ID
await page.fill('.username-input'); // Falla si cambia la clase

Consecuencias:

• Tests fallando constantemente en CI/CD
• Horas perdidas arreglando selectores rotos
• Frustración del equipo de QA
• Bugs en producción porque los tests no son confiables

---

La Solución

Smart Locator Framework implementa un algoritmo inteligente de failover que intenta múltiples estrategias de localización automáticamente:

// Con Smart Locator - Resiliente y robusto
await smartActions.smartClick('Login button');
await smartActions.smartFill('Username input', 'user@example.com');

Cómo Funciona

El framework itera sobre 5 estrategias en orden de prioridad. Si una falla, automáticamente prueba la siguiente:

1. ID          → #user-name                    (Más específico)
2. Texto       → text=Username
3. Role        → role=textbox[name~=Username]  (Accesible)
4. Atributo    → [data-testid="username"]
5. Posición    → .form input:first-child       (Último recurso)

Algoritmo:

for (const strategy of strategies) {
  try {
    element = await findByStrategy(strategy);

    if (element) {
      logger.logSuccess(strategy);
      return element; // Encontrado
    }
  } catch (error) {
    continue; // Falló, prueba la siguiente
  }
}

throw new Error('Ninguna estrategia funcionó');

---

Resultados Reales

Después de ejecutar 20 tests E2E completos:

Estrategia	Usos	Porcentaje
Role	81	56.2%
Attribute	58	40.3%
Text	4	2.8%
Position	1	0.7%
ID	0	0%

El 96.5% de elementos se localizaron con estrategias resilientes (Role + Attribute).

---

Instalación

# 1. Clonar repositorio
git clone <repo-url>
cd vibecoder-qa

# 2. Instalar dependencias
npm install

# 3. Ejecutar tests
npm test

# 4. Ver reporte HTML
npm run report

---

Estructura del Proyecto

vibecoder-qa/
├── framework/
│   ├── config.js              # Configuración de estrategias
│   ├── smart-locator.js       # Algoritmo de failover
│   ├── smart-actions.js       # API simplificada
│   ├── selector-logger.js     # Registro de estrategias
│   └── report-generator.js    # Generador de reportes HTML
├── tests/
│   ├── login.test.js          # Tests de autenticación
│   ├── products.test.js       # Tests de productos
│   ├── cart.test.js           # Tests de carrito
│   └── checkout.test.js       # Tests E2E completos
├── reports/
│   ├── selector-usage.json    # Logs de estrategias usadas
│   └── test-report.html       # Reporte visual
└── README.md

---

Uso

Test Básico

const { test } = require('@playwright/test');
const SmartActions = require('../framework/smart-actions');

test('Login exitoso', async ({ page }) => {
  const smartActions = new SmartActions(page);

  await page.goto('https://www.saucedemo.com/');

  // El framework encuentra automáticamente los elementos
  await smartActions.smartFill('Username input', 'standard_user');
  await smartActions.smartFill('Password input', 'secret_sauce');
  await smartActions.smartClick('Login button');
});

Búsqueda Avanzada con Criterios

// Usando atributos específicos
await smartActions.smartClick({
  attributes: { 'data-testid': 'submit-button' }
});

// Combinando role + texto
await smartActions.smartFill({
  role: 'textbox',
  text: 'Email'
}, 'user@example.com');

// Por posición (último recurso)
await smartActions.smartClick({
  position: { selector: '.product-list .item:first-child' }
});

---

Prueba de Failover

Para demostrar la resiliencia del framework:

# 1. Ejecuta los tests normalmente
npm test

# 2. Comenta la estrategia de ID en smart-locator.js
# 3. Ejecuta de nuevo
npm test

# Todos los tests siguen pasando usando estrategias alternativas

---

Comandos Disponibles

Comando	Descripción
npm test	Ejecuta todos los tests
npm run report	Genera reporte HTML
npm run test:report	Ejecuta tests + genera reporte

---

Casos de Uso Cubiertos

• Login con validaciones (credenciales válidas/inválidas)
• Selección de productos
• Gestión de carrito (agregar/remover items)
• Flujo completo de checkout E2E
• Navegación con menú lateral
• Ordenamiento de productos
• Validación de campos requeridos

Total: 20 tests pasando en ~19 segundos

---

Tecnologías

• Playwright - Framework de testing
• Node.js - Runtime
• JavaScript - Lenguaje principal
• HTML/CSS - Reportes visuales

---

Reporte Visual

El framework genera automáticamente reportes HTML con:

• Gráficos de barras de uso de estrategias
• Tabla detallada de elementos localizados
• Diseño moderno y responsive
• Timestamps de cada interacción

---

Conceptos Aplicados

• Patrón Strategy: Múltiples algoritmos de localización intercambiables
• Failover automático: Recuperación ante fallos
• Logging estructurado: Análisis de patrones
• Page Object Model: Abstracción de acciones
• Test resilience: Tests que no se rompen fácilmente

---

Autor

Proyecto creado como demostración de habilidades en automatización QA y desarrollo de frameworks.

Contacto: oskarpardo@proton.me

---

Licencia

ISC