Saltar a contenido

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), NEO usa 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-suite no genera un mecanismo de sesión automático: deja un TODO en el paso de login y un aviso en su resultado.
  • lippia-neo-run-and-heal no valida nada de la sesión antes de ejecutar: las fallas de login aparecen como fallas comunes (probablemente environment).

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 paquete cucumber a 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, queda cy.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 como cy.wait(2000). cy.wait('@alias') solo sobre un cy.intercept con nombre.
  • Mocks de red con cy.intercept().

6. Cómo lo ejecuta lippia-neo-run-and-heal

El run.sh del adapter:

  1. Verifica que existan node_modules, Cypress y cypress.config.js (o .ts) dentro de tests_dir. Si falta algo, sale con código 2.
  2. Ejecuta npx cypress run --project <tests_dir> con los filtros que correspondan.
  3. parse-results.sh lee los JSON de reports/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_path siempre 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)