Saltar a contenido

Configurar playwright-cucumberjs

Estado del adapter: ✅ Completo. playwright-cucumberjs es un valor válido de stack.test_framework: lippia-neo-bootstrap-stack lo detecta, lippia-neo-generate-test-suite escribe los escenarios en Gherkin (.feature) con sus steps y page objects, y lippia-neo-run-and-heal los ejecuta y repara.

Con este adapter, cucumber-js (@cucumber/cucumber) ejecuta los .feature directamente y Playwright se usa como librería para manejar el navegador. No hay fixtures ni projects de Playwright: el navegador, el context y la evidencia de las fallas los manejan un World y unos hooks que genera NEO.

¿Preferís que los .feature se ejecuten con el runner de Playwright (fixtures, projects, traces)? Mirá Configurar playwright-bdd. Las dos guías comparten la organización de la suite; cambian la configuración, el glue entre steps y Playwright, y cómo se ejecuta.

Pieza ¿Soporta playwright-cucumberjs?
Detección automática en lippia-neo-bootstrap-stack ✅ Si package.json trae @cucumber/cucumber y además @playwright/test o playwright
lippia-neo-generate-test-suite (adapters/playwright-cucumberjs/) ✅ README y 9 plantillas
lippia-neo-run-and-heal (adapters/playwright-cucumberjs/) ✅ run.sh y parse-results.sh, con scoping por .feature, por carpeta y por tag
lippia-neo-find-existing-tests ✅ Busca en los .feature por tags, títulos y la marca # bug-id:
lippia-neo-find-ui-tests-by-code-diff y lippia-neo-repair-selectors-by-diff ✅ Buscan y reparan en pages/ y steps/; nunca tocan el texto de un .feature
lippia-neo-refactor-gherkin-features ✅ Reestructura los .feature existentes para que sean data-driven
Jobs de CI de lippia-neo-bootstrap-ci ✅ Usa la misma instalación que Playwright (npm ci + navegadores)
Escaneo de las convenciones de una suite existente ❌ No soportado: los casos nuevos siguen la convención por defecto del adapter (sección 5)
Valor en qa-stack.yaml test_framework: playwright-cucumberjs
Lenguaje javascript o typescript (si hay tsconfig.json)
Qué usa @cucumber/cucumber + Playwright como librería (escenarios en Gherkin)
Tipos de app web, api e hybrid
Autenticación basic_auth, api_token, google_sso (con limitaciones, ver sección 4) o none
Carpeta de tests por defecto tests/playwright-cucumberjs/
Archivo de configuración cucumber.js (o .cjs / .mjs) en la raíz del repositorio

1. Qué necesitás instalado

Herramienta Versión Cómo verificarlo
Node.js 18 o superior node -v
@cucumber/cucumber La del package.json (probado con 12.2.0) npx cucumber-js --version
@playwright/test La del package.json npx playwright --version
Navegadores de Playwright Los de tu versión de Playwright npx playwright install
dotenv — Figura en package.json. No hace falta si el proyecto usa process.loadEnvFile (Node 20.12+)
tsx — Solo si el proyecto es TypeScript
Bash (Git Bash o WSL en Windows) — bash --version
npm install -D @cucumber/cucumber @playwright/test dotenv
# solo TypeScript:
npm install -D tsx
npx playwright install

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 (ver Configuración del MCP de Playwright).


2. qa-stack.yaml de ejemplo

stack:
  test_framework: playwright-cucumberjs
  language: javascript        # o typescript
  app_type: hybrid            # web | api | hybrid
  auth: basic_auth            # google_sso | basic_auth | api_token | none
  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/playwright-cucumberjs/
  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 cucumber-js --dry-run + npx cucumber-js
  install_deps: null     # usa npm ci

No hay un campo aparte para elegir el runner de Gherkin: el valor de test_framework (playwright-bdd o playwright-cucumberjs) ya lo define.


3. Configurar cucumber.js

El config va en la raíz del repositorio:

// cucumber.js (raíz del repositorio)
const TESTS_DIR = 'tests/playwright-cucumberjs';   // = paths.tests_dir

const base = {
  require: [`${TESTS_DIR}/support/**/*.js`, `${TESTS_DIR}/steps/**/*.js`], // .ts si el proyecto es TypeScript
  // requireModule: ['tsx/cjs'],                    // solo TypeScript
  format: ['progress', 'html:reports/cucumber-report.html'],
  retry: process.env.CI ? 2 : 1,
};

module.exports = {
  default: base,
  // Un perfil de cucumber-js por cada perfil de datos (solo si usás más de uno):
  // 'perfil-b': { ...base, worldParameters: { dataProfile: 'perfil-b' } },
};

Tres reglas que lippia-neo-run-and-heal necesita que se cumplan:

Regla Por qué
No declarar paths cucumber-js suma los paths del config a los que recibe por línea de comandos: con paths en el config, run.sh no puede ejecutar un solo .feature y siempre corre la suite completa. Para ejecutar a mano: npx cucumber-js tests/playwright-cucumberjs/features
No agregar un formatter message run.sh agrega el suyo (test-results/cucumber-messages.ndjson); dos formatters escribiendo el mismo archivo se pisan
retry mayor a 0 Sin retries no se puede detectar un test flaky

Si tu config ya declara paths, run.sh lo avisa en el log y lippia-neo-run-and-heal lo registra en sus notas: la solución es quitar paths del config, no tocar los tests.


4. Autenticación

basic_auth y api_token

Completá los valores en .env.tests, igual que con Playwright. El archivo se carga en support/hooks.<ext>, y los steps leen los valores con process.env.NOMBRE, sin escribirlos nunca literales:

  • basic_auth: el Background de cada .feature hace login con process.env.APP_USER / process.env.APP_PASSWORD a través del page object (steps/common.steps.<ext>).
  • api_token: el Before de los escenarios @api crea los request contexts apiManager y apiViewer con API_TOKEN_MANAGER y API_TOKEN_VIEWER.

google_sso

El login de Google no se automatiza. El Before de support/hooks.<ext> abre el context con storageState: 'playwright/.auth/user.json', y el step el usuario está autenticado solo abre la app. run.sh verifica que ese archivo exista y, si no está, se detiene con Auth state no encontrado.

Limitación actual de la sesión

Este adapter todavía no usa paths.auth_state_file ni el bloque session.* de qa-stack.yaml: la ruta de la sesión es fija (playwright/.auth/user.json, o la que indiques en QA_AUTH_STATE_PATH). El archivo de sesión se genera con el script de tu proyecto, igual que en el adapter de Playwright. Con basic_auth, el Background hace login en cada escenario.

Nunca subas el archivo de sesión a git. Agregá playwright/.auth/ al .gitignore.


5. Qué genera NEO

cucumber.js                                     ← raíz del repositorio
tests/playwright-cucumberjs/                    ← paths.tests_dir
├── features/
│   ├── carrito.feature                         ← un .feature por flujo de negocio (UI)
│   ├── checkout.feature
│   └── ordenes.api.feature                     ← un .feature por flujo de negocio (API), con @api
├── steps/
│   ├── common.steps.<ext>                      ← Background (login), una sola vez por proyecto
│   ├── carrito.steps.<ext>                     ← uno por page object (CarritoPage)
│   └── ordenes.api.steps.<ext>                 ← uno por recurso de API (/api/ordenes)
├── pages/
│   └── CarritoPage.<ext>                       ← page objects
├── data/
│   └── default/<flujo>.json · <dominio>.json   ← solo si algún caso usa datos de archivo
└── support/
    ├── world.<ext>                             ← CustomWorld: page, request contexts de API, ctx, testData, page objects
    ├── hooks.<ext>                             ← abre y cierra el navegador, guarda la evidencia de las fallas
    └── test-data.<ext>                         ← resuelve los datos de prueba del perfil activo

Cómo se organizan los escenarios

Igual que en playwright-bdd:

  • Un .feature por flujo de negocio (features/<flujo>.feature), no por historia ni por caso. Los casos de distintas historias que prueban el mismo flujo van al mismo archivo, agregados al final.
  • Trazabilidad solo por tags: cada Scenario lleva @<US-ID> y @<ID del caso> tal como figura en el plan, y su título empieza con ese ID (Scenario: TC-01 — Agregar un producto al carrito).
  • Los .feature de API terminan en .api.feature y llevan @api en el Feature: los hooks usan ese tag para no abrir un navegador.
  • Los escenarios que solo cambian en los datos se escriben como un Scenario Outline con un bloque Examples por caso (ver Data-driven testing).

El World y los hooks

Archivo Qué hace
support/world.<ext> Define el CustomWorld que cada step recibe como this: browser, context, page, apiManager / apiViewer, ctx (estado del escenario), testData y un campo por page object
support/hooks.<ext> Carga .env.tests. Before (escenarios de UI): lanza Chromium (headless salvo HEADED=1), abre el context con baseURL, inicia el trace e instancia los page objects. Before (@api): crea los request contexts de API. After: si el escenario falló, guarda screenshot y trace en test-results/cucumber-evidence/ y los agrega como attachment; después cierra todo

No modifiques el attachment de evidencia del After

El After agrega como attachment las rutas del screenshot y del trace como text/uri-list. Es lo que lee lippia-neo-run-and-heal para tener evidencia de cada falla. Si lo quitás o le cambiás el formato, la reparación solo cuenta con el mensaje de error.

Reglas que siguen los tests generados

  • Steps en lenguaje de negocio: sin selectores, URLs ni credenciales en el .feature.
  • El texto de un step es global: antes de crear uno, se busca si ya existe. Un step duplicado queda ambiguous y hace fallar la validación para toda la suite.
  • Archivos de steps por page object o por recurso, nunca por historia: steps/<page>.steps.<ext> en par con pages/<Nombre>Page.<ext>, y steps/<recurso>.api.steps.<ext> para API.
  • Steps como async function, nunca arrow functions: usan this (el World). Given / When / Then vienen de @cucumber/cucumber y expect de @playwright/test.

    const { When } = require('@cucumber/cucumber');
    
    When('el usuario busca {string}', async function (termino) {
      await this.busquedaPage.buscar(termino);
    });
    
  • Cada page object nuevo toca dos archivos: se declara como campo en support/world.<ext> y se instancia en el Before de support/hooks.<ext> (this.carritoPage = new CarritoPage(this.page)).

  • Selectores solo en page objects, en este orden: getByRole, getByLabel, getByTestId, getByText y, como último recurso, CSS. Si la app usa otro atributo de testing (por ejemplo data-test), se configura una vez con selectors.setTestIdAttribute('data-test') en los hooks.
  • Estado entre steps del mismo escenario en this.ctx, nunca en variables globales.
  • Tests de regresión y TDD quedan en rojo: nunca se marcan con @skip, @fixme ni @fail.

Las plantillas están en JavaScript (CommonJS). Si el proyecto es TypeScript, NEO las adapta a import / export, tipa this en los steps (async function (this: CustomWorld, termino: string)) y guarda los archivos con .ts.


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

El run.sh del adapter:

  1. Verifica que existan node_modules, @cucumber/cucumber, la carpeta features/ y el archivo de sesión si auth es google_sso. Si falta algo, sale con código 2.
  2. Ejecuta npx cucumber-js --dry-run (no ejecuta steps ni hooks) y busca steps undefined o ambiguous. cucumber-js sale con 0 aunque los haya, por eso run.sh los busca en la salida. Si encuentra alguno, sale con código 2: no hay resultados, y la skill lo trata como código incompleto (corrige steps/), no como un test en rojo.
  3. Ejecuta npx cucumber-js --format message:test-results/cucumber-messages.ndjson <paths>.
  4. parse-results.sh lee ese NDJSON (no el formatter json, que no muestra los retries). El estado de cada escenario es el peor de sus steps y hooks en el último intento, y la evidencia sale del attachment text/uri-list del After.
Variable Por defecto Para qué
QA_TESTS_DIR tests/playwright-cucumberjs La raíz (suite completa) o una lista de .feature / carpetas bajo features/, separadas por espacio
QA_TESTS_ROOT QA_TESTS_DIR si es un único path paths.tests_dir. Obligatoria si QA_TESTS_DIR trae más de un path
QA_EXCLUDE_DIRS vacío Subcarpetas de features/ a excluir. Los .feature sueltos en features/ siempre corren
QA_CUCUMBER_TAGS vacío Filtrar por tag: @US-002, "@US-002 and @TC-02", "@smoke and not @wip"
QA_AUTH_STATE_PATH playwright/.auth/user.json Archivo de sesión que se valida si auth es google_sso
CUCUMBER_FLAGS vacío Flags extra, por ejemplo --retry 0 o --parallel 2
CUCUMBER_CONFIG vacío Usar otro archivo de config (se pasa con --config al dry-run y a la ejecución)
CUCUMBER_MESSAGES_OUTPUT test-results/cucumber-messages.ndjson Dónde se guarda el resultado
CUCUMBER_ATTACHMENTS_DIR test-results/cucumber-attachments Dónde se guarda un screenshot que llegó embebido en el resultado
# Suite completa
QA_TESTS_DIR="tests/playwright-cucumberjs" ./run.sh

# Un flujo puntual y una carpeta
QA_TESTS_ROOT="tests/playwright-cucumberjs" \
QA_TESTS_DIR="tests/playwright-cucumberjs/features/carrito.feature tests/playwright-cucumberjs/features/legacy" \
./run.sh

# Solo una historia (por tag)
QA_TESTS_DIR="tests/playwright-cucumberjs" QA_CUCUMBER_TAGS="@US-002" ./run.sh

Cuando un playbook acota la ejecución, lippia-neo-run-and-heal traduce sus opciones así (siempre pasa además QA_TESTS_ROOT):

Opción de lippia-neo-run-and-heal Se convierte en
config.target_tests QA_TESTS_DIR con los .feature indicados
config.include_dirs QA_TESTS_DIR con <tests_dir>/features/<carpeta> por cada carpeta
config.exclude_dirs QA_EXCLUDE_DIRS con los nombres de las subcarpetas de features/

Dónde aplica las reparaciones

Tipo de falla Qué toca
selector_broken, timeout El page object (pages/). Si hace falta un page object nuevo, también el World y el Before
assertion_mismatch El step definition (steps/). El .feature solo si cambió el comportamiento de negocio esperado
Step undefined o ambiguous (dry-run) steps/
environment Nada del test: solo cómo se carga .env.tests o el nombre de la variable

NEO nunca cambia el texto de un step dentro del .feature para que coincida con un step definition.

En un Scenario Outline, cada fila de Examples es un test, y aparece en los resultados como <título con los valores> — Example #N (N cuenta todas las tablas Examples del Outline).


7. Checklist rápido

node -v                                          # 18 o superior
npx cucumber-js --version                        # cucumber-js instalado
npx playwright --version                         # Playwright instalado
grep -n "paths" cucumber.*                       # no tiene que aparecer una clave paths
grep -n "retry" cucumber.*                       # retry mayor a 0
npx cucumber-js --dry-run tests/playwright-cucumberjs/features   # el resumen no debe tener undefined ni ambiguous

Si todo responde bien, pedile al asistente: "Ejecutá la suite con lippia-neo-run-and-heal".


8. Problemas comunes (y qué hacer)

Lo que ves Por qué puede pasar Qué hacer
@cucumber/cucumber no encontrado Falta instalar el paquete npm install -D @cucumber/cucumber
'npx cucumber-js --dry-run' falló … steps undefined o ambiguous Un step del .feature no tiene definición, o hay dos definiciones que coinciden Completar o deduplicar el step en steps/. Es lo que hace lippia-neo-run-and-heal
Siempre se ejecuta la suite completa, aunque se pida un solo .feature El config declara paths Quitar paths de cucumber.js
this.<algoPage> es undefined en un step El page object no está instanciado en el Before de los hooks Declararlo en el World e instanciarlo en support/hooks.<ext>
this es undefined en un step El step se escribió como arrow function Usar async function () { … }
QA_TESTS_DIR trae varios paths; definí QA_TESTS_ROOT Se pasó más de un .feature o carpeta Definir QA_TESTS_ROOT con paths.tests_dir
Auth state no encontrado en 'playwright/.auth/user.json' Con google_sso, no existe el archivo de sesión Generarlo (ver sección 4) o indicar la ruta real en QA_AUTH_STATE_PATH
cucumber-js no escribió el NDJSON cucumber-js falló antes de terminar (config con errores, módulo faltante) Revisar la salida que aparece arriba del error
Fallas sin screenshot ni trace Se modificó o quitó el attachment text/uri-list del After Restaurar el After de support/hooks.<ext>
No se detectan tests flaky retry es 0 Poner retry mayor a 0 en el config
lippia-neo-bootstrap-stack te pregunta qué runner usar package.json trae playwright-bdd y @cucumber/cucumber a la vez Elegir con cuál se genera la suite

9. Limitaciones actuales

Qué Qué pasa con playwright-cucumberjs Alternativa
Casos bloqueados por falta de datos Este runner no tiene una marca para dejarlos escritos y salteados: el caso no se escribe en el .feature y solo aparece en skipped_scenarios Escribirlo cuando el dato esté disponible (ver Data-driven testing)
Ejecutar un solo caso Pasar un .feature ejecuta todos sus escenarios (todo el flujo) Filtrar por tag: QA_CUCUMBER_TAGS="@US-002 and @TC-02"
Ejecutar a partir de un page object o step Si target_tests trae un page object, un step o un archivo de support/ (típico después de lippia-neo-repair-selectors-by-diff), run.sh ejecuta la suite completa y lo informa —
Sesión autenticada No usa paths.auth_state_file ni session.*; la ruta es fija QA_AUTH_STATE_PATH
Escaneo de convenciones de la suite existente No soportado: ubica, nombra y tagea los casos con la convención por defecto —
Agregar un caso a un Scenario Outline existente Al generar, nunca se agrega una fila a un Outline que ya existe: el caso va aparte, con un aviso Unificarlos a mano o con lippia-neo-refactor-gherkin-features
Ejecución en paralelo (--parallel) Funciona, pero los screenshots y traces se nombran por escenario y hora, no por worker —