QA Automation

📋 Metodologías, workflows y procesos específicos del equipo de Quality Assurance

Esta sección define cómo planificamos, implementamos y mantenemos la automatización E2E en los proyectos de la empresa: stack (Playwright + TypeScript), convenciones del repositorio, arranque del entorno bajo prueba, integración con el flujo de desarrollo y criterios de calidad propios de automation.

Próximos temas a profundizar (backlog de documentación)

• Estrategia por tipo de proyecto — qué automatizar primero (marketing vs producto vs ecommerce).
• Contrato API + E2E — cuándo complementar con tests de contrato o fixtures de red.
• Flaky tests — diagnóstico, cuarentena y política de re-ejecución.
• Data y seeds — uso de ambientes con datos conocidos vs generación en test.
• Accesibilidad y performance en pipeline — enlaces con procesos de a11y y Core Web Vitals.

Procesos relacionados

• Procesos de QA — Procesos que garantizan que cada proyecto cumpla con los más altos estándares antes de llegar al cliente.
• Ciclo de vida de tickets — Estados de QA y devoluciones por fallos en E2E.

🎯 Filosofía de QA Automation

Principios fundamentales

• User-centric: Los flujos E2E reflejan journeys reales del usuario, no solo checks técnicos.
• Data-driven: Fallas y tendencias se validan con reportes, trazas y métricas de ejecución (no solo “pasó en mi máquina”).
• Preventive: Tests críticos corridos antes de merge o build donde el proceso lo defina; feedback temprano.
• Collaborative: Automation vive en el mismo ciclo que dev y diseño; los cambios de UI se coordinan para no romper selectores sin aviso.
• Continuous improvement: Refactor de POMs, tags y suites según riesgo y aprendizajes del sprint.
• Efficiency: Automatizar lo estable y repetible; exploratory y criterios subjetivos siguen siendo humanos donde corresponda.

📏 Estándares orientados a automation

Cobertura razonable (E2E):

• Smoke automatizado en flujos críticos acordados (login, conversión, formularios clave, checkout si aplica).
• Regresión por conjuntos etiquetados (ej. @smoke, módulos), no “todo el sitio” sin criterio.
• Navegadores y dispositivos alineados con la matriz oficial del proyecto (no duplicar esfuerzo manual y automático sin criterio).

Documentación y trazabilidad:

• Casos automatizados legibles (nombre del test + steps donde aplique).
• PRs de automation con descripción clara: qué flujo cubre, riesgo, dependencia de entorno/datOS.
• Evidencia en fallos: captura, trace/video de Playwright cuando esté activo en config, y adjuntos al ticket.

Expectativas de tiempo (orientativas; calibrar por proyecto):

• Arranque de entorno + primera corrida smoke < 1h para quien ya conoce el repo (setup + lectura de .env).
• Mantenimiento reactivo por cambio de UI en la misma ventana del sprint que el cambio funcional (no acumular deuda).

🧭 Alcance: qué cubre este proceso

Este proceso cubre end-to-end con Playwright + TypeScript en el repositorio del cliente/proyecto, típicamente bajo la carpeta e2e/ en monorepos: Page Object Model (POM), fixtures, configuración, scripts npm y política de reportes.

Qué no sustituye la automatización E2E sola: pruebas unitarias, revisión de diseño pixel-perfect exhaustiva, performance profunda, a11y formal WCAG (puede acompañar con herramientas, pero el proceso de a11y sigue siendo el definido por la empresa).

Stack y convenciones del repositorio

• Playwright + TypeScript — Estándar para E2E en nk.studio salvo acuerdo distinto por proyecto.
• e2e/ como paquete — Fuente de verdad de dependencias y scripts de Playwright; evita mezclar con el package.json de la app.
• POM — Objetos de página reutilizables; selectores preferidos: rol, label, texto estable, data-testid si existe.
• Tags — p. ej. @smoke para gates rápidos; otros tags según módulo/feature.
• Lint / formato — ESLint + Prettier en el paquete e2e/ cuando el proyecto lo tenga configurado.

Regla de oro (monorepo): Los comandos npm run … de Playwright se documentan y ejecutan desde e2e/. La raíz del producto puede exponer atajos (yarn test:e2e:smoke, build:test) acordados con dev/CI — documentar solo esos atajos en README del producto, no duplicar toda la lista.

Reportes: HTML vs Allure (y qué adjuntar al ticket)

• HTML + list + JSON (config Playwright): base para día a día; abrir con el script de reporte del proyecto (p. ej. npm run test:report tras una corrida).
• Allure: Cuando el proyecto lo use, seguir la política del repo (p. ej. variable para omitir Allure en smokes rápidos de CI).
• En Productive (o herramienta de tracking): enlace o zip a trace/video/screenshot según gravedad; el título y pasos siguen el estándar de bug report (más abajo).

⚡ Quick start (onboarding QA / nuevo clon)

Desde e2e/:

1. Copiar entorno: cp .env.example .env y definir BASE_URL.
2. Setup: npm run setup (instalación + navegador con dependencias del SO según script del proyecto).
3. Primera corrida: npm run test:smoke (o el comando de smoke que defina el repo).

Smoke desde la raíz del monorepo (si existe el atajo): p. ej. yarn test:e2e:smoke — útil para alinear con el gate que usa dev.

Entorno bajo prueba: qué tener en cuenta con el “start”

Hay dos modos; el equipo debe saber cuál se usa en cada validación:

1) Contra despliegue (staging / preview / entorno de prueba)

• Configurar BASE_URL en e2e/.env apuntando a esa URL.
• No hace falta levantar la app en local para ejecutar E2E.
• Encaja con CI que apunta a un entorno ya desplegado o con QA validando un build desplegado.

2) Contra la app en local

• En la raíz del monorepo: yarn dev (o el comando de arranque del proyecto).
• En e2e/.env: BASE_URL=http://localhost:3000 (o el puerto real).
• Ejecutar E2E cuando la app ya responda en el navegador (no lanzar la suite mientras el primer build aún no terminó).

Checklist rápido (local):

• La URL de BASE_URL abre en el navegador.
• No hay errores bloqueantes en el flujo bajo prueba.
• Datos / feature flags alineados con lo que el test espera (si aplica).

🔀 Workflow Git recomendado para automation

1. Rama desde la base acordada (develop / integración), con prefijo claro: feature/e2e-….
2. Cambios concentrados en e2e/ (tests, POMs, fixtures, utilidades, docs de automation), salvo acuerdo explícito.
3. Pull Request hacia la rama de integración; revisión y smoke en CI cuando esté cableado.

Así el historial de tests queda legible y separado de features de producto en la misma rama.

Cambios en la aplicación (app) vs solo en tests

Por defecto nk.studio no modifica src/ ni la lógica de producto solo para hacer pasar tests.

Orden de preferencia para estabilizar tests:

1. Locators accesibles (getByRole, getByLabel, getByText).
2. data-testid u otros hooks ya existentes o acordados con desarrollo.
3. Fixtures, datos de prueba, POMs, esperas correctas.
4. Intercepción de red cuando aplique.
5. page.evaluate solo como último recurso documentado.

Si hace falta un cambio en la app (p. ej. data-testid), se propone el cambio mínimo y se aprueba con el equipo antes de implementarlo.

🔄 Alineación con el ciclo de vida de pruebas

El rol de QA automation se integra en el mismo ciclo que describió el equipo; lo que cambia es el artefacto principal (código + suite ejecutable):

1. Planificación / requisitos — Identificar flujos E2E candidatos, riesgo, datos y entornos; criterios de aceptación automatizables.
2. Análisis — Condiciones y escenarios que valen la pena E2E vs manual; dependencias (API, auth, datos).
3. Diseño — Casos como tests (describe/steps), datos, tags, POMs necesarios.
4. Implementación — Código en e2e/, configuración, scripts, datos en fixtures.
5. Ejecución — CI y/o local; comparar resultado vs esperado; abrir defectos con evidencia.
6. Cierre — Resumen de cobertura, flakies, recomendación de release (como input al informe de QA, no sustituto del juicio global de calidad).

Colaboración continua: participación en planning/dailies cuando haya impacto en alcance de tests o entornos; revisión de PRs que toquen áreas cubiertas por E2E.

📝 Estándar de reporte de incidentes

Todo reporte (manual o detectado por pipeline) debe incluir:

• Título — Breve y descriptivo del problema.
• Tester — Quién reporta (para aclarar reproducción).
• Fecha — Cuándo se reportó (métricas de tiempo hasta resolución).
• Aplicación y versión — Qué producto y versión / build / despliegue se probó.
• Ambiente del tester — Web: navegador y versión. Mobile: modelo + OS. CI: job/link si aplica.
• Pasos — Secuencia clara para reproducir (“receta”).
• Capturas / evidencia — Screenshots; en automation: trace, video, log si la política del repo los genera.
• Resultado obtenido — Qué ocurrió.
• Resultado esperado — Según especificación o criterio de aceptación.
• Importancia — Bajo / medio / alto / crítico — impacto en usuario y probabilidad.
• To-do’s — Lista en el ticket para dev; QA marca verificación al re-test y puede devolver el ticket si algo sigue roto.

Definición de “listo” para un cambio en la suite E2E (orientativa)

• Test estable en al menos el entorno objetivo acordado (local o staging).
• Selectores alineados con accesibilidad y buenas prácticas; sin sleeps arbitrarios para “tapar” problemas.
• Documentado en el PR: alcance, datos necesarios, variables de entorno.
• Si el fallo fue automático: ticket o comentario con pasos + evidencia para desarrollo.