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
.featurese 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),NEOusa 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-bddoplaywright-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.shlo avisa en el log ylippia-neo-run-and-heallo registra en sus notas: la solución es quitarpathsdel 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: elBackgroundde cada.featurehace login conprocess.env.APP_USER/process.env.APP_PASSWORDa través del page object (steps/common.steps.<ext>).api_token: elBeforede los escenarios@apicrea los request contextsapiManageryapiViewerconAPI_TOKEN_MANAGERyAPI_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
.featurepor 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
Scenariolleva@<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
.featurede API terminan en.api.featurey llevan@apien elFeature: los hooks usan ese tag para no abrir un navegador. - Los escenarios que solo cambian en los datos se escriben como un
Scenario Outlinecon un bloqueExamplespor 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
ambiguousy 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 conpages/<Nombre>Page.<ext>, ysteps/<recurso>.api.steps.<ext>para API. -
Steps como
async function, nunca arrow functions: usanthis(el World).Given/When/Thenvienen de@cucumber/cucumberyexpectde@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 elBeforedesupport/hooks.<ext>(this.carritoPage = new CarritoPage(this.page)). - Selectores solo en page objects, en este orden:
getByRole,getByLabel,getByTestId,getByTexty, como último recurso, CSS. Si la app usa otro atributo de testing (por ejemplodata-test), se configura una vez conselectors.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,@fixmeni@fail.
Las plantillas están en JavaScript (CommonJS). Si el proyecto es TypeScript,
NEOlas adapta aimport/export, tipathisen 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:
- Verifica que existan
node_modules,@cucumber/cucumber, la carpetafeatures/y el archivo de sesión siauthesgoogle_sso. Si falta algo, sale con código2. - Ejecuta
npx cucumber-js --dry-run(no ejecuta steps ni hooks) y busca stepsundefinedoambiguous. cucumber-js sale con 0 aunque los haya, por esorun.shlos busca en la salida. Si encuentra alguno, sale con código2: no hay resultados, y la skill lo trata como código incompleto (corrigesteps/), no como un test en rojo. - Ejecuta
npx cucumber-js --format message:test-results/cucumber-messages.ndjson <paths>. parse-results.shlee ese NDJSON (no el formatterjson, 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 attachmenttext/uri-listdelAfter.
| 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 deExampleses un test, y aparece en los resultados como<título con los valores> — Example #N(N cuenta todas las tablasExamplesdel 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 | — |