Configurar playwright-bdd
Estado del adapter: ✅ Completo. playwright-bdd 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.
playwright-bdd convierte los .feature en tests de Playwright (npx bddgen) y los ejecuta con el runner normal de Playwright (npx playwright test). Por eso conserva todo lo de Playwright: fixtures, storageState, traces, projects y el reporte JSON.
¿Preferís que los
.featurelos ejecute cucumber-js en lugar del runner de Playwright? Mirá Configurar playwright-cucumberjs. 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-bdd? |
|---|---|
Detección automática en lippia-neo-bootstrap-stack |
✅ Si package.json trae playwright-bdd |
lippia-neo-generate-test-suite (adapters/playwright-bdd/) |
✅ README y 8 plantillas |
lippia-neo-run-and-heal (adapters/playwright-bdd/) |
✅ 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-bdd |
| Lenguaje | javascript o typescript (si hay tsconfig.json) |
| Qué usa | @playwright/test + playwright-bdd (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-bdd/ |
| Archivo de configuración | playwright.config.<ext> en la raíz del repositorio (no dentro de tests_dir) |
1. Qué necesitás instalado
| Herramienta | Versión | Cómo verificarlo |
|---|---|---|
| Node.js | 18 o superior | node -v |
@playwright/test |
La del package.json |
npx playwright --version |
playwright-bdd |
8 o superior (probado con 8.4.1 y 9.2) | Figura en package.json |
| 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+) |
| Bash (Git Bash o WSL en Windows) | — | bash --version |
npm install -D @playwright/test playwright-bdd dotenv
npx playwright install
Agregá la carpeta de tests generados al .gitignore: la crea npx bddgen en cada ejecución y no se edita a mano.
tests/playwright-bdd/.features-gen/
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-bdd
language: typescript # o javascript
app_type: web # web | api | hybrid
auth: basic_auth # google_sso | basic_auth | api_token | none
pipeline_provider: gitlab
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-bdd/
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 bddgen + npx playwright test
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 playwright.config
El config va en la raíz del repositorio y se arma con defineBddConfig. lippia-neo-generate-test-suite te muestra el bloque que corresponde a tu tipo de app, pero conviene dejarlo listo antes. Tres valores son obligatorios porque lippia-neo-run-and-heal depende de ellos:
| Qué | Por qué | Valor |
|---|---|---|
featuresRoot |
Que el spec generado de cada .feature se pueda mapear de vuelta al .feature |
El mismo valor de paths.tests_dir |
outputDir |
Dónde escribe bddgen los tests generados |
<tests_dir>/.features-gen |
| Reporter JSON | parse-results.sh lee ese archivo para saber qué falló |
['json', { outputFile: 'test-results/results.json' }] |
Carga de .env.tests |
Que los steps lean las credenciales sin tenerlas escritas. Se carga solo acá: cada worker vuelve a leer el config | require('dotenv').config({ path: '.env.tests' }) |
// playwright.config.js (raíz del repositorio)
const { defineConfig, devices } = require('@playwright/test');
const { defineBddConfig } = require('playwright-bdd');
require('dotenv').config({ path: '.env.tests' }); // = paths.env_file
const TESTS_DIR = 'tests/playwright-bdd'; // = paths.tests_dir
const TEST_DIR = defineBddConfig({
featuresRoot: TESTS_DIR,
outputDir: `${TESTS_DIR}/.features-gen`,
features: `${TESTS_DIR}/features/**/*.feature`,
steps: [`${TESTS_DIR}/fixtures.js`, `${TESTS_DIR}/steps/**/*.js`], // .ts si el proyecto es TypeScript
});
module.exports = defineConfig({
retries: process.env.CI ? 2 : 1,
timeout: 60000,
reporter: [
['json', { outputFile: 'test-results/results.json' }], // requerido por lippia-neo-run-and-heal
['html', { outputFolder: 'playwright-report', open: 'never' }],
['list'],
],
use: {
baseURL: process.env.APP_BASE_URL || 'https://techstore-staging.com',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
// testIdAttribute: 'data-test', // solo si la app no usa data-testid
},
projects: [
{ name: 'chromium', testDir: TEST_DIR, grepInvert: /@api/, use: { ...devices['Desktop Chrome'] } },
{ name: 'api', testDir: TEST_DIR, grep: /@api/ },
],
});
Según el tipo de app
Los tests de UI y de API se separan por el tag @api del Feature, no por dos configs distintas:
app_type |
projects |
|---|---|
web |
chromium (con grepInvert: /@api/). Con google_sso, además setup (ver sección 4) |
api |
Solo api (con grep: /@api/) |
hybrid |
chromium y api (y setup con google_sso) |
Si la suite usa más de un perfil de datos, agregá un project por perfil con
use: { dataProfile: '<perfil>' }. Con un solo perfil no hace falta: se usaTEST_DATA_PROFILEodefault.
4. Autenticación
basic_auth y api_token
Completá los valores en .env.tests, igual que con Playwright. Los steps los leen con process.env.NOMBRE y nunca los escriben 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: los fixturesapiManageryapiViewercrean los request contexts de API conAPI_TOKEN_MANAGERyAPI_TOKEN_VIEWER.
google_sso
El login de Google no se automatiza. La sesión se carga desde un archivo storageState:
- El project
chromiumusastorageState: 'playwright/.auth/user.json'y depende del projectsetup, que es el que genera ese archivo. - El step
el usuario está autenticadosolo abre la app: la sesión ya viene cargada. run.shverifica que existaplaywright/.auth/user.jsonantes de ejecutar y, si no está, se detiene conAuth 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). Además, el config referencia un auth.setup.js que este adapter no incluye: tomalo del adapter de Playwright o generá el archivo de sesión con el script de tu proyecto. 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
playwright.config.<ext> ← raíz del repositorio
tests/playwright-bdd/ ← 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
├── fixtures.<ext> ← fixtures + Given/When/Then de createBdd
├── test-data.<ext> ← resuelve los datos de prueba del perfil activo
└── .features-gen/ ← lo genera npx bddgen: no se edita ni se versiona
Cómo se organizan los escenarios
- Un
.featurepor flujo de negocio, no por historia ni por caso:features/<flujo>.feature(por ejemplomodificar-carrito.feature). Los casos de distintas historias que prueban el mismo flujo van al mismo archivo; cada caso nuevo se agrega comoScenarioal final. No hay carpetas por historia. - 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. - Los
.featurede API terminan en.api.featurey llevan el tag@apien elFeature. Sin ese tag, un caso de API abre un navegador. - Los escenarios que solo cambian en los datos se escriben como un
Scenario Outlinecon un bloqueExamplespor caso (ver Data-driven testing).
Feature: Modificar el carrito
Background:
Given el usuario está autenticado
@US-002 @TC-01
Scenario: TC-01 — Agregar un producto al carrito
When el usuario agrega "Mouse Inalámbrico" al carrito
Then el carrito muestra 1 producto
@US-008 @TC-03
Scenario: TC-03 — Quitar el último producto deja el carrito vacío
...
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 hace fallar
npx bddgenpara 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. - Imports: los steps importan
Given/When/Thende../fixtures, nunca de@cucumber/cucumber. El primer argumento son los fixtures:async ({ carritoPage }, producto) => { … }. - Selectores solo en page objects, en este orden:
getByRole,getByLabel,getByTestId,getByTexty, como último recurso, CSS. Si no se conoce un selector, quedapage.locator('TODO')con un comentario. - Estado entre steps del mismo escenario en el fixture
ctx, nunca en variables globales. - Tests de regresión y TDD quedan en rojo: nunca se marcan con
@skip,@fixmeni@fail(en playwright-bdd,@failinvierte el resultado y escondería el bug).
Las plantillas están en JavaScript (CommonJS). Si el proyecto es TypeScript,
NEOlas adapta aimport/exporty 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,@playwright/testyplaywright-bdd, y el archivo de sesión siauthesgoogle_sso. Si falta algo, sale con código2. - Ejecuta
npx bddgen, que valida los steps y genera los tests. Si hay un step faltante o duplicado, 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 playwright test --reporter=jsoncon los filtros que correspondan. parse-results.shleetest-results/results.jsony traduce cada resultado al.featurede origen (quita.features-gen/y.spec.jsde la ruta).
| Variable | Por defecto | Para qué |
|---|---|---|
QA_TESTS_DIR |
tests/playwright-bdd |
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 |
PLAYWRIGHT_FLAGS |
vacío | Flags extra, por ejemplo --project=chromium |
PLAYWRIGHT_CONFIG |
vacío | Usar otro archivo de config (se pasa a bddgen y a playwright test) |
PLAYWRIGHT_JSON_OUTPUT |
test-results/results.json |
Dónde se guarda el reporte JSON |
# Suite completa
QA_TESTS_DIR="tests/playwright-bdd" ./run.sh
# Un flujo puntual y una carpeta
QA_TESTS_ROOT="tests/playwright-bdd" \
QA_TESTS_DIR="tests/playwright-bdd/features/carrito.feature tests/playwright-bdd/features/legacy" \
./run.sh
# Solo una historia (por tag)
QA_TESTS_DIR="tests/playwright-bdd" 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/) |
assertion_mismatch |
El step definition (steps/). El .feature solo si cambió el comportamiento de negocio esperado |
Step faltante o duplicado (bddgen) |
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, y nunca edita .features-gen/. Un caso bloqueado por datos (@fixme con un comentario # bloqueado:) no se repara.
En un
Scenario Outline, cada fila deExampleses un test. Si la fila no tiene un título propio, aparece en los resultados como<título del Outline> — Example #N.
7. Checklist rápido
node -v # 18 o superior
npx playwright --version # Playwright instalado
grep -n "playwright-bdd" package.json # playwright-bdd instalado
grep -n "defineBddConfig\|results.json" playwright.config.*
npx bddgen # valida los steps sin ejecutar nada
npx playwright test --list # lista un test por escenario y por fila de Examples
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 |
|---|---|---|
playwright-bdd no encontrado |
Falta instalar el paquete | npm install -D playwright-bdd |
'npx bddgen' falló … steps faltantes o duplicados |
Un step del .feature no tiene definición, o está definido dos veces |
Completar o deduplicar el step en steps/. Es lo que hace lippia-neo-run-and-heal |
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 |
Los resultados apuntan a .features-gen/…spec.js en vez del .feature |
featuresRoot u outputDir no coinciden con paths.tests_dir |
Alinear el config con la sección 3 |
| Un test de API abre un navegador | El .api.feature no tiene el tag @api en el Feature |
Agregar @api arriba de Feature: |
| Un caso bloqueado no aparece en el reporte | Todos los escenarios de ese .feature están en @fixme, y bddgen no genera el spec |
Es esperado: aparece cuando el archivo tenga un escenario que corra |
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-bdd | Alternativa |
|---|---|---|
| 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 fixtures.<ext> (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 |
Historial de CI con Scenario Outline |
playwright-bdd agrupa las filas de un Outline dentro de un describe con el título del Outline: cambia la ruta completa del test |
Si tu CI guarda historial por ruta completa, los va a ver como tests nuevos una vez |