Saltar a contenido

Configurar los adapters

Esta sección explica cómo dejar configurado el framework de testing de tu proyecto para que NEO lo pueda usar: qué hay que instalar, qué hay que poner en qa-stack.yaml, qué archivos de configuración necesita el proyecto y cómo verificar que todo quedó bien.

Hay una guía por cada framework. k6 y JMeter son de performance (pruebas de carga sobre una API): se configuran con el bloque performance de qa-stack.yaml y las usan las skills de performance, no las skills de suite funcional (lippia-neo-generate-test-suite, lippia-neo-run-and-heal, lippia-neo-bootstrap-ci), que con ellos se detienen con framework_not_supported_by_this_skill. Lo que sigue en esta página (pasos generales, run.sh, parse-results.sh) describe los frameworks funcionales.

Framework Lenguaje Estado del adapter Guía
Playwright JavaScript / TypeScript ✅ Completo Configurar Playwright
playwright-bdd JavaScript / TypeScript (Playwright + Gherkin, ejecutado con bddgen + playwright test) ✅ Completo Configurar playwright-bdd
playwright-cucumberjs JavaScript / TypeScript (Playwright + Gherkin, ejecutado con cucumber-js) ✅ Completo Configurar playwright-cucumberjs
Lippia Java (Maven + Cucumber + TestNG + Selenium) ✅ Completo Configurar Lippia
Cypress JavaScript / TypeScript (Cypress + Cucumber) ✅ Completo (con limitaciones en la búsqueda de cobertura y en CI; ver su guía) Configurar Cypress
k6 JavaScript (performance) ✅ Completo (pruebas de carga; no usa las skills de suite funcional) Configurar k6
JMeter Java (performance) ✅ Completo (pruebas de carga; no usa las skills de suite funcional) Configurar JMeter
Pytest Python ⛔ STUB: documentado pero sin implementar; las skills se detienen Configurar Pytest

1. ¿Qué es un adapter?

NEO está pensado para trabajar con cualquier framework de testing. Las skills describen qué hay que hacer ("generá un test por cada caso del plan", "ejecutá la suite y repará lo que falle"), pero no saben de memoria cómo se hace eso en cada framework.

Esa traducción la hace el adapter: un conjunto de archivos (convenciones, plantillas y scripts) que le enseña a la skill cómo escribir, ejecutar y leer los resultados de un framework puntual.

Una analogía: la skill es un electrodoméstico y el adapter es el adaptador de enchufe. El electrodoméstico hace siempre lo mismo; el adaptador cambia según el país (el framework) donde lo enchufes.

Cada adapter provee:

Pieza Para qué sirve Ejemplo en Playwright
Convenciones (README.md) Reglas del framework: cómo nombrar archivos, qué selectores preferir, cómo manejar el login, cómo esperar "Un .spec.js por caso de prueba; preferir getByRole antes que clases CSS"
Plantillas La base desde la que se genera cada test (nunca se escribe desde cero) spec-template.spec.js, api-spec-template.spec.js
Script de ejecución (run.sh) Cómo ejecutar la suite npx playwright test
Script de resultados (parse-results.sh) Convierte el reporte del framework a un formato común que la skill entiende Lee test-results/results.json

2. ¿Cómo elige NEO qué adapter usar?

Todo sale de un solo campo del archivo qa-stack.yaml, que vive en la raíz del repositorio de pruebas:

stack:
  test_framework: playwright   # playwright | playwright-bdd | playwright-cucumberjs | cypress | lippia | pytest | k6 | jmeter

Cuando una skill necesita el framework, sigue siempre estos pasos:

  1. Lee stack.test_framework de qa-stack.yaml.
  2. Busca la carpeta adapters/<test_framework>/ dentro de la skill.
  3. Si encuentra un README.md, carga sus convenciones y usa sus plantillas y scripts.
  4. Si solo encuentra un STUB.md (adapter sin implementar), se detiene con el mensaje Adapter <framework> en estado STUB. Ver <skill_root>/adapters/<framework>/STUB.md para contribuir.

En el caso de Lippia, además de la carpeta del adapter, las skills leen la biblioteca compartida lib/lippia/ del repositorio de skills, donde viven los templates y scripts reales. Los dos runners de Gherkin (playwright-bdd y playwright-cucumberjs) comparten lib/gherkin/: los lineamientos de datos, el helper de datos de cada runner y el lint de datos.

Skills que usan adapters

Skill Qué toma del adapter
lippia-neo-generate-test-suite Convenciones y plantillas para escribir los tests
lippia-neo-run-and-heal run.sh para ejecutar la suite y parse-results.sh para leer los resultados
lippia-neo-run-manual-testing y lippia-neo-reproduce-bug La capacidad de manejar un navegador real, que la provee el MCP de Playwright (ver Configurar los MCP)
lippia-neo-ci-bootstrap No usa un adapter de framework: usa uno de proveedor de CI (GitHub, GitLab, Bitbucket), elegido por stack.pipeline_provider

3. Pasos generales (valen para cualquier framework)

Paso 1 — Instalar lo que pide el framework

Cada guía tiene su lista (Node.js, Java, Maven, navegadores…). Hacelo antes de pedirle nada al asistente: si falta una herramienta, los scripts del adapter se detienen antes de ejecutar un solo test.

Paso 2 — Generar qa-stack.yaml con lippia-neo-bootstrap-stack

Pedile al asistente:

Configurá el proyecto para QA con lippia-neo-bootstrap-stack

La skill lippia-neo-bootstrap-stack detecta el framework mirando el repositorio. Gana la primera fila que coincide: los proyectos Gherkin también traen @playwright/test, por eso se revisan antes.

Si encuentra… Deduce
package.json con playwright-bdd test_framework: playwright-bdd (y typescript si hay tsconfig.json)
package.json con @cucumber/cucumber y además @playwright/test o playwright test_framework: playwright-cucumberjs. Si también trae playwright-bdd, te pregunta cuál usar
package.json con @playwright/test (sin ninguno de los anteriores) test_framework: playwright (y typescript si hay tsconfig.json)
package.json con cypress test_framework: cypress (y typescript si hay tsconfig.json o cypress.config.ts). Si también trae @playwright/test, te pregunta cuál usar
pom.xml o build.gradle con cucumber / lippia test_framework: lippia, language: java
pyproject.toml / setup.cfg / requirements.txt con pytest test_framework: pytest, language: python

Lo que no puede deducir (tipo de app, autenticación, URL del ambiente, versión, sistema operativo y las carpetas donde se guarda cada cosa) te lo pregunta. Si preferís armarlo a mano, en cada guía hay un qa-stack.yaml de ejemplo completo.

Paso 3 — Configurar el proyecto del framework

Cada framework necesita que su archivo de configuración tenga ciertas cosas para que NEO pueda leer los resultados. Por ejemplo, el reporte JSON habilitado. Está detallado en cada guía.

Paso 4 — Cargar las credenciales del ambiente de prueba

Las credenciales nunca se escriben en los tests. lippia-neo-bootstrap-stack crea un archivo .env.tests (fuera de git) con las claves vacías según el tipo de autenticación, y vos completás los valores a mano:

stack.auth Claves que se generan en .env.tests
basic_auth APP_USER, APP_PASSWORD
api_token API_TOKEN_MANAGER, API_TOKEN_VIEWER
google_sso Ninguna: la sesión se guarda en un archivo de estado del navegador (ver la guía de Playwright)
none Ninguna

Si app_type es api o hybrid, se agrega además API_BASE_URL.

Ojo con Lippia: el adapter de Lippia lee otras variables (APP_URL, QA_USER, QA_PASSWORD) y las toma del entorno de la terminal, no de .env.tests. Está explicado en su guía.

Paso 5 — Verificar

Pedile al asistente que ejecute la suite con lippia-neo-run-and-heal. Cada guía tiene un checklist rápido con los comandos para confirmar que el entorno está listo.


4. Cosas que tienen en común todos los adapters

Dónde se escriben los tests

Siempre directamente en paths.tests_dir de qa-stack.yaml. Si aceptaste el valor por defecto de lippia-neo-bootstrap-stack, esa carpeta ya incluye el nombre del framework (tests/playwright/, tests/playwright-bdd/, tests/cypress/, tests/lippia/…). Si elegiste una carpeta propia (por ejemplo e2e/), se usa tal cual. Las skills nunca le agregan una subcarpeta con el nombre del framework.

Reemplazar el comando de ejecución (commands)

Si tu proyecto ejecuta los tests con un comando especial, podés reemplazar el que usa el adapter:

commands:
  run_tests: null      # null = usa el run.sh del adapter
  install_deps: null   # null = usa la instalación por defecto (npm ci, mvn dependency:resolve…)
Cuándo reemplazarlo Ejemplo
Querés ejecutar un solo navegador o un reporter distinto npx playwright test --project=chromium
Usás yarn o pnpm en lugar de npm install_deps: pnpm install --frozen-lockfile
Tu proyecto Maven usa otro perfil run_tests: mvn test -Pqa

Si reemplazás run_tests, asegurate de que el comando siga generando el reporte JSON que espera parse-results.sh. Si no, NEO no puede leer los resultados.

Qué significa cada código de salida

Código Significado Qué hace lippia-neo-run-and-heal
0 Todos los tests pasaron Termina en verde
1 (o distinto de 0 y de 2) Hay tests que fallan Analiza cada falla e intenta repararla
2 Falla del entorno o de la configuración (falta una herramienta, no hay pom.xml, no se generó el reporte…) No intenta reparar: te avisa qué falta

Los scripts son bash

Los run.sh y parse-results.sh de todos los adapters son scripts bash. En Windows tienen que ejecutarse sobre Git Bash o WSL; no funcionan invocados directamente desde cmd.exe o PowerShell.


5. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
Adapter <framework> en estado STUB El framework elegido todavía no tiene adapter implementado (hoy: Pytest) Ver la guía de Pytest para alternativas
La skill dice que no encuentra qa-stack.yaml Nunca se ejecutó el bootstrap en ese repositorio Ejecutar lippia-neo-bootstrap-stack (o el playbook New Project Bootstrap)
Los tests se generan, pero el framework "no encuentra ningún test" La configuración del framework apunta a otra carpeta o a otra extensión Revisar testDir / specPattern / testMatch según la guía de tu framework
run.sh no arranca en Windows Se está ejecutando desde PowerShell o cmd.exe Usar Git Bash o WSL
Los tests fallan todos en el login Faltan las credenciales en .env.tests (o en el entorno, para Lippia) Completar las variables del Paso 4