Documentación de k0lmena Automation Framework

Todo lo necesario para instalar, configurar y usar el framework: front, API, mobile, performance, reportes y auto-healing.

Qué es y qué incluye

k0lmena es un framework de automatización de QA que reúne, en un mismo repositorio y con una misma sintaxis (Gherkin/BDD + TypeScript), cuatro tipos de pruebas:

Además incorpora auto-healing de locators, reportes HTML por cada tipo de prueba, herramientas de apoyo (generador de locators, tester de enlaces rotos, grabador y modo debug) y captura automática de screenshots, traces y logs ante fallos.

Tecnologías

• TypeScript
• Playwright (E2E, tracing y codegen)
• Cucumber (@cucumber/cucumber, BDD/Gherkin)
• Axios (API)
• WebdriverIO + Appium (mobile)
• Artillery y k6 (performance)
• Cheerio (parsing de HTML en herramientas)

Estructura del proyecto

src/
├── front-test/        # E2E (UI): Playwright + Cucumber
│   ├── features/      # Gherkin scenarios (.feature)
│   ├── steps/         # Step definitions
│   ├── locators/      # Element selectors
│   ├── config/        # Config (BASEURL from .env)
│   ├── hooks/         # Browser setup, screenshots, traces
│   ├── utils/         # interactions, validations, keys, types
│   └── auto-healing/  # Locator history
├── api-test/          # features/ + tests/ (axios)
├── mobile-test/       # apps/ features/ steps/ locators/ support/
├── performance-test/  # artillery/ + k6/
├── reports/           # front/ api/ mobile/ performance/
└── tools/             # crawler/ link-tester/ generator/ debug/

Archivos raíz relevantes: package.json, cucumber.js (perfiles), playwright.config.ts, tsconfig.json, .example.env.

Requisitos previos

• Node.js (LTS recomendado): nodejs.org
• Visual Studio Code (opcional)
• Para mobile: Appium y un emulador o dispositivo (o una cuenta de BrowserStack).
• Para performance con k6: el binario se instala con el script de bootstrap.

Instalación

git clone https://github.com/underc0delabs/k0lmena.git
cd k0lmena
npm install                # dependencias
npx playwright install     # navegadores de Playwright
cp .example.env .env       # archivo de entorno

Después editá el .env con tus valores.

Configuración (variables de entorno)

General / Front

API

Auto-healing

Front / E2E (UI)

npm run test       # escenarios @Smoke, con 1 reintento
npm run allTests   # todos los tests

Los perfiles de Cucumber están en cucumber.js. Podés controlar navegador y modo por variables:

BROWSER=chromium HEADLESS=false SLOWMO=300 npm run test
TRACE=on-failure npm run test

Ejecución en paralelo

PARALLEL=4 npm run test
PARALLEL=on npm run apiTest

• Cada worker es un proceso independiente; el auto-healing escribe un historial por worker para evitar colisiones.
• El perfil debug corre siempre en secuencial.
• El paralelismo es por escenario: para máxima velocidad conviene fijar un único navegador por corrida.

API

npm run apiTest   # escenarios etiquetados @API

Definí API_BASEURL en .env.api. Los steps viven en src/api-test/tests/.

Mobile

npm run mobile    # WebdriverIO + Appium

La configuración está en src/mobile-test/support/wdio.conf.ts. Por defecto corre contra Appium local (localhost:4723); incluye un bloque comentado para BrowserStack con BROWSERSTACK_USER y BROWSERSTACK_KEY.

Performance

Artillery

npm run load   # test de carga, genera report.json

k6

npm run bootstrap:k6     # instala el binario la primera vez
npm run k6:build         # compila los escenarios TypeScript
npm run k6::smoke
npm run k6:stress
npm run k6:soak
npm run k6:spike
npm run k6:run:browser

Los escenarios de k6 están en src/performance-test/k6/http/ y se compilan con esbuild a dist/.

Reportes

Ante un fallo en front, el framework adjunta screenshot, logs de consola del navegador y, si TRACE está activo, el trace de Playwright.

Auto-healing de locators

k0lmena puede recuperar locators que dejan de funcionar cuando la aplicación cambia. Funciona en dos fases:

1. Learn: cada vez que una acción tiene éxito, guarda locators alternativos del elemento (data-testid, id, name, aria-label, rol, texto, clases) en un historial.
2. Heal: si el locator original falla, prueba los candidatos guardados (rankeados por éxito histórico y página) hasta encontrar uno que funcione, y lo reporta.

K0LMENA_AUTO_HEALING=on npm run test

Cuando un locator se cura vas a ver en consola HEALED: <original> -> <candidato> y el evento queda adjunto en el reporte.

Herramientas

Todas usan BASEURL del .env, salvo que se indique otra cosa.

Crawler (generador de locators)

npm run crawler
npx ts-node src/tools/crawler/locators-generator.ts https://mi-sitio.com

Salida: src/tools/crawler/output/locators-output.ts

Link tester

npm run link-tester        # página base
npm run link-tester:full   # todo el sitio

Record (Playwright codegen)

npm run record
npm run record:generator

Debug

npm run debug

Integración continua (CI)

El workflow .github/workflows/Tests.yaml corre en GitHub Actions (disparo manual) dentro del contenedor oficial de Playwright y ejecuta, en orden: instalación de dependencias y navegadores, front tests + reporte, API tests + reporte, performance (Artillery) + reporte, y publicación de los reportes como artifacts.

Cómo agregar un test nuevo

1. Feature: creá o editá un .feature en src/front-test/features/.
2. Locators: agregá los selectores en src/front-test/locators/.
3. Steps: implementalos en src/front-test/steps/ usando las funciones de utils/interactions.ts (getByPlaceholderAndFillIt, getElementByRoleAndClickIt, selectByLabel, click, fill).
4. Ejecutá con npm run test (o etiquetá el escenario con @Smoke).

Las utilidades de interacción ya integran el auto-healing, así que tus steps se benefician sin código extra.

Referencia de scripts npm

Video

Ver el video tutorial en YouTube · Canal de QARMY

Licencia y créditos

k0lmena Automation Framework es open source con licencia ISC. Es un proyecto de la comunidad QARMY y Underc0de.