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:
- Lee
stack.test_frameworkdeqa-stack.yaml. - Busca la carpeta
adapters/<test_framework>/dentro de la skill. - Si encuentra un
README.md, carga sus convenciones y usa sus plantillas y scripts. - Si solo encuentra un
STUB.md(adapter sin implementar), se detiene con el mensajeAdapter <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) compartenlib/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 esperaparse-results.sh. Si no,NEOno 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 |