Saltar a contenido

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 .feature los 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), 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-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-bdd o playwright-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 usa TEST_DATA_PROFILE o default.


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: 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: los fixtures apiManager y apiViewer crean los request contexts de API con API_TOKEN_MANAGER y API_TOKEN_VIEWER.

google_sso

El login de Google no se automatiza. La sesión se carga desde un archivo storageState:

  • El project chromium usa storageState: 'playwright/.auth/user.json' y depende del project setup, que es el que genera ese archivo.
  • El step el usuario está autenticado solo abre la app: la sesión ya viene cargada.
  • run.sh verifica que exista playwright/.auth/user.json antes de ejecutar 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). 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 .feature por flujo de negocio, no por historia ni por caso: features/<flujo>.feature (por ejemplo modificar-carrito.feature). Los casos de distintas historias que prueban el mismo flujo van al mismo archivo; cada caso nuevo se agrega como Scenario al final. No hay carpetas por historia.
  • 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.
  • Los .feature de API terminan en .api.feature y llevan el tag @api en el Feature. Sin ese tag, un caso de API abre 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).
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 bddgen 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.
  • Imports: los steps importan Given / When / Then de ../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, getByText y, como último recurso, CSS. Si no se conoce un selector, queda page.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, @fixme ni @fail (en playwright-bdd, @fail invierte el resultado y escondería el bug).

Las plantillas están en JavaScript (CommonJS). Si el proyecto es TypeScript, NEO las adapta a import / export 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, @playwright/test y playwright-bdd, y el archivo de sesión si auth es google_sso. Si falta algo, sale con código 2.
  2. Ejecuta npx bddgen, que valida los steps y genera los tests. Si hay un step faltante o duplicado, 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 playwright test --reporter=json con los filtros que correspondan.
  4. parse-results.sh lee test-results/results.json y traduce cada resultado al .feature de origen (quita .features-gen/ y .spec.js de 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 de Examples es 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