Configurar Cypress
Estado del adapter: ✅ Completo. Cypress es un valor válido de stack.test_framework: lippia-neo-bootstrap-stack lo detecta, lippia-neo-generate-test-suite genera la suite con sus plantillas y lippia-neo-run-and-heal la ejecuta y repara.
| Pieza | ¿Soporta Cypress? |
|---|---|
Lista de frameworks válidos en STACK.md y en qa-stack.yaml |
✅ playwright, cypress, lippia y pytest |
Detección automática en lippia-neo-bootstrap-stack |
✅ Si package.json trae cypress. Si trae también @playwright/test, te pregunta cuál usar |
lippia-neo-generate-test-suite (adapters/cypress/) |
✅ README y 9 plantillas |
lippia-neo-run-and-heal (adapters/cypress/) |
✅ run.sh y parse-results.sh, con scoping por carpeta y por archivo |
lippia-neo-find-existing-tests y lippia-neo-find-ui-tests-by-code-diff |
❌ Todavía no: devuelven not_found con un aviso |
lippia-neo-repair-selectors-by-diff |
❌ Todavía no: se detiene con un aviso, sin reparar nada |
Jobs de CI de lippia-neo-bootstrap-ci |
❌ Todavía no instalan las dependencias de Cypress (ver sección 9) |
Valor en qa-stack.yaml |
test_framework: cypress |
| Lenguaje | javascript o typescript (si hay tsconfig.json o cypress.config.ts) |
| Qué usa | Cypress + @badeball/cypress-cucumber-preprocessor (escenarios en Gherkin) |
| Tipos de app | web, api e hybrid |
| Autenticación | basic_auth o api_token. google_sso no tiene solución automática (ver sección 4) |
| Carpeta de tests | paths.tests_dir, que para Cypress es además la raíz del proyecto Cypress (ej. tests/cypress/) |
1. Qué necesitás instalado
| Herramienta | Versión | Cómo verificarlo |
|---|---|---|
| Node.js | 18 o superior | node -v |
cypress |
La del package.json |
npx cypress version |
@badeball/cypress-cucumber-preprocessor |
La del package.json |
Figura en package.json |
Un bundler para el preprocessor: @bahmutov/cypress-esbuild-preprocessor (el que usa la plantilla) o @cypress/webpack-preprocessor |
— | Figura en package.json |
dotenv |
— | Figura en package.json |
| Bash (Git Bash o WSL en Windows) | — | bash --version |
npm install -D cypress @badeball/cypress-cucumber-preprocessor @bahmutov/cypress-esbuild-preprocessor dotenv
Para las skills que navegan la aplicación en vivo (
lippia-neo-run-manual-testing,lippia-neo-reproduce-bug),NEOusa el MCP de Playwright, sin importar el framework de testing. Si vas a usar esas skills, configuralo también (ver Configuración del MCP de Playwright).
2. qa-stack.yaml de ejemplo
stack:
test_framework: cypress
language: javascript
app_type: web
auth: basic_auth
pipeline_provider: github
environment:
base_url: https://techstore-staging.com
app_version: 2.4.1
os: Windows 11
paths:
user_stories_storage:
type: local
cloud_provider_mcp: null
local_path: user-stories/
test_plans_dir: test-plans/
tests_dir: tests/cypress/ # raíz del proyecto Cypress: acá va cypress.config.js
reports_dir: test-results/reports/
scripted_dir: execution/
exploratory_dir: exploration/
env_file: .env.tests
commands:
run_tests: null # usa el run.sh del adapter → npx cypress run --project <tests_dir>
install_deps: null
3. Configurar el proyecto Cypress
A diferencia de Playwright, cypress.config.js no va en la raíz del repositorio: va en la raíz de paths.tests_dir, porque el adapter ejecuta Cypress con --project <tests_dir>.
cypress.config.js
// tests/cypress/cypress.config.js
const { defineConfig } = require('cypress');
const createBundler = require('@bahmutov/cypress-esbuild-preprocessor');
const { addCucumberPreprocessorPlugin } = require('@badeball/cypress-cucumber-preprocessor');
const { createEsbuildPlugin } = require('@badeball/cypress-cucumber-preprocessor/esbuild');
require('dotenv').config({ path: '.env.tests' }); // = paths.env_file
module.exports = defineConfig({
screenshotsFolder: 'screenshots', // requerido: parse-results.sh busca los screenshots acá
videosFolder: 'videos',
e2e: {
baseUrl: 'https://techstore-staging.com', // = environment.base_url
specPattern: 'e2e/features/**/*.feature',
supportFile: 'support/e2e.js',
async setupNodeEvents(on, config) {
await addCucumberPreprocessorPlugin(on, config);
on('file:preprocessor', createBundler({ plugins: [createEsbuildPlugin(config)] }));
return config;
},
env: {
APP_USER: process.env.APP_USER, // solo las claves que correspondan a stack.auth
APP_PASSWORD: process.env.APP_PASSWORD,
},
},
});
| Qué | Por qué |
|---|---|
screenshotsFolder: 'screenshots' y videosFolder: 'videos' |
parse-results.sh reconstruye la ruta del screenshot de cada falla asumiendo esas carpetas |
specPattern: 'e2e/features/**/*.feature' |
Que Cypress encuentre los .feature que genera NEO |
require('dotenv').config(...) + bloque env |
Cypress no carga .env solo: hay que leer .env.tests y exponer las variables. En los tests se usan con Cypress.env('APP_USER') |
.cypress-cucumber-preprocessorrc.json
Habilita el reporte JSON que lee lippia-neo-run-and-heal (un archivo por feature):
{
"json": { "enabled": true, "output": "reports/json/[name].json" },
"html": { "enabled": true, "output": "reports/cucumber-report.html" },
"stepDefinitions": ["e2e/step_definitions/**/*.js"],
"filterSpecs": true,
"omitFiltered": true
}
Si tu proyecto ya tenía este archivo con el JSON en otra carpeta, no lo muevas: indicá esa carpeta en la variable
CYPRESS_JSON_OUTPUT(ver sección 6).
4. Autenticación
basic_auth y api_token
Completá los valores en .env.tests y exponelos en el bloque env de cypress.config.js. Los steps los leen con Cypress.env('NOMBRE') y nunca los escriben literales:
Given('el usuario está autenticado', () => {
loginPage.visit();
loginPage.login(Cypress.env('APP_USER'), Cypress.env('APP_PASSWORD'));
});
google_sso — limitación conocida
Cypress no tiene un equivalente al storageState de Playwright, y el login real de Google se bloquea por detección de bots, 2FA o captcha. Si configurás auth: google_sso con Cypress:
lippia-neo-generate-test-suiteno genera un mecanismo de sesión automático: deja unTODOen el paso de login y un aviso en su resultado.lippia-neo-run-and-healno valida nada de la sesión antes de ejecutar: las fallas de login aparecen como fallas comunes (probablementeenvironment).
Alternativas posibles: cy.session() con un login programático contra un endpoint interno que no pase por Google, o usar basic_auth / api_token si la app tiene un login alternativo para pruebas.
5. Qué genera NEO
tests/cypress/ ← paths.tests_dir (raíz del proyecto Cypress)
├── cypress.config.js
├── .cypress-cucumber-preprocessorrc.json
├── support/e2e.js ← support file
├── e2e/
│ ├── features/US-002/
│ │ ├── tc-001-agregar-producto.feature ← un .feature por caso de prueba
│ │ └── tc-002-carrito-vacio.feature
│ ├── step_definitions/ ← steps (incluye los comunes del login, una sola vez)
│ └── pages/ ← Page Objects (CarritoPage.js, LoginPage.js…)
├── reports/json/ ← resultado que lee lippia-neo-run-and-heal
└── screenshots/ videos/ ← evidencia automática de las fallas
Reglas que siguen los tests generados:
- Imports siempre de
@badeball/cypress-cucumber-preprocessor, nunca del paquetecucumbera secas (tiene otra API y es incompatible). - Selectores, en este orden:
data-cy,data-testid,id/name, texto visible (cy.contains) y, como último recurso, clase CSS. Si no se conoce un selector, quedacy.get('TODO')con un comentario. - Page Objects: los selectores quedan encapsulados en
e2e/pages/y nunca sueltos en los steps. - Esperas con el reintento automático de
.should(...), nunca pausas fijas comocy.wait(2000).cy.wait('@alias')solo sobre uncy.interceptcon nombre. - Mocks de red con
cy.intercept().
6. Cómo lo ejecuta lippia-neo-run-and-heal
El run.sh del adapter:
- Verifica que existan
node_modules, Cypress ycypress.config.js(o.ts) dentro detests_dir. Si falta algo, sale con código2. - Ejecuta
npx cypress run --project <tests_dir>con los filtros que correspondan. parse-results.shlee los JSON dereports/json/y reconstruye la ruta del screenshot de cada falla.
| Variable | Por defecto | Para qué |
|---|---|---|
QA_TESTS_DIR |
Obligatoria | Raíz del proyecto Cypress (paths.tests_dir). Es siempre una sola carpeta |
QA_CUCUMBER_TAGS |
vacío | Filtrar por etiqueta: @smoke, @US-002, "@US-002 and not @wip" |
QA_CUCUMBER_SPEC |
vacío | Ejecutar solo ciertos .feature: globs separados por coma (ej. e2e/features/US-002/**/*.feature) |
QA_EXCLUDE_DIRS |
vacío | Subcarpetas de e2e/features/ a excluir, separadas por espacio |
CYPRESS_FLAGS |
vacío | Flags extra, por ejemplo --browser firefox |
CYPRESS_CONFIG |
vacío | Usar otro archivo de config (--config-file) |
CYPRESS_JSON_OUTPUT |
reports/json |
Carpeta del reporte JSON, relativa a QA_TESTS_DIR |
Cuando un playbook acota la ejecución, lippia-neo-run-and-heal traduce sus opciones así (QA_TESTS_DIR no cambia nunca):
Opción de lippia-neo-run-and-heal |
Se convierte en |
|---|---|
config.target_tests |
QA_CUCUMBER_SPEC con los path de cada test, separados por coma |
config.include_dirs |
QA_CUCUMBER_SPEC con e2e/features/<carpeta>/**/*.feature por cada carpeta |
config.exclude_dirs |
QA_EXCLUDE_DIRS con los nombres de las subcarpetas de e2e/features/ |
Cypress se ejecuta en modo headless por defecto con
cypress run, así que no hace falta ningún flag extra para CI.
trace_pathsiempre queda vacío: Cypress no tiene un equivalente al trace de Playwright. El screenshot de cada falla se busca por la convención de nombres de Cypress; si no se encuentra, queda vacío, y eso no es un error.
7. Checklist rápido
node -v
npx cypress version
ls tests/cypress/cypress.config.js tests/cypress/.cypress-cucumber-preprocessorrc.json
grep -n "screenshotsFolder" tests/cypress/cypress.config.js
QA_TESTS_DIR=tests/cypress QA_CUCUMBER_TAGS=@smoke bash <ruta-al-adapter>/run.sh
8. Problemas comunes (y qué hacer)
| Lo que ves | Por qué puede pasar | Qué hacer |
|---|---|---|
QA_TESTS_DIR debe apuntar al project root de Cypress |
No se indicó la carpeta del proyecto Cypress | Definir QA_TESTS_DIR con paths.tests_dir |
No se encontró cypress.config.js/ts en '<tests_dir>' |
El config está en la raíz del repositorio en vez de en tests_dir |
Mover o crear cypress.config.js dentro de tests_dir |
Cypress no encontrado |
Falta instalar el paquete | npm install -D cypress |
| No aparecen resultados después de ejecutar | El preprocessor no tiene el reporte JSON habilitado o lo escribe en otra carpeta | Revisar .cypress-cucumber-preprocessorrc.json o definir CYPRESS_JSON_OUTPUT |
screenshot_path vacío en las fallas |
Se cambió screenshotsFolder a otra carpeta |
Volver a screenshotsFolder: 'screenshots' |
| Los steps no se encuentran ("step implementation missing") | Se importó desde cucumber en vez de @badeball/cypress-cucumber-preprocessor, o stepDefinitions apunta a otra carpeta |
Corregir el import o el glob de stepDefinitions |
lippia-neo-bootstrap-stack te pregunta qué framework usar |
package.json trae cypress y @playwright/test a la vez |
Elegir con cuál se genera la suite |
lippia-neo-find-existing-tests siempre devuelve not_found |
La búsqueda de cobertura existente todavía no soporta Cypress | Es una limitación actual (ver la tabla del inicio) |
9. Limitaciones actuales
| Qué | Qué pasa con Cypress | Alternativa |
|---|---|---|
Buscar cobertura existente (lippia-neo-find-existing-tests, lippia-neo-find-ui-tests-by-code-diff) |
Devuelven status: not_found con un aviso, sin revisar los .feature |
Indicar a mano qué carpetas ejecutar con include_dirs en lippia-neo-run-and-heal |
Reparar selectores a partir de un diff (lippia-neo-repair-selectors-by-diff) |
Se detiene con un aviso, sin tocar los tests | Ejecutar lippia-neo-run-and-heal: repara los selectores rotos al ejecutar la suite |
Jobs de CI (lippia-neo-bootstrap-ci) |
El paso de instalación no tiene una rama para Cypress. En GitHub y Bitbucket se trata como playwright (ejecuta npm install e instala navegadores de Playwright); en GitLab y Jenkins no instala nada |
Agregar a mano la instalación de Cypress en el job generado (npm ci y npx cypress install) |