Data-driven testing
Esta guía explica cómo maneja NEO los datos de prueba cuando escribe escenarios en Gherkin (.feature): qué dato va escrito en el escenario, cuál va a un archivo de datos, cuál a una variable de entorno, y cuándo varios casos se agrupan en un Scenario Outline. También explica cómo el plan de pruebas declara esos datos, para que puedas revisar un plan o una suite y saber qué esperar.
El objetivo es que el .feature siga siendo una especificación que alguien del negocio puede leer: dice qué se prueba y con qué casuística, nunca cómo se carga cada dato.
Dónde se aplica
| Quién | Qué hace con estos lineamientos |
|---|---|
lippia-neo-create-test-plan |
Diseña los datos de cada escenario: particiones, valores límite, datos de referencia, casos bloqueados (sección 6) |
lippia-neo-generate-test-suite |
Escribe los .feature nuevos siguiendo estas reglas |
lippia-neo-refactor-gherkin-features |
Lleva una suite Gherkin que ya existe a estas reglas, sin cambiar qué verifica |
Hoy aplica a los runners playwright-bdd y playwright-cucumberjs. Lippia y Cypress todavía no lo usan.
1. Steps declarativos, un comportamiento por escenario
El step describe la intención en lenguaje de negocio. Selectores, URLs, IDs técnicos, payloads y secuencias de clics viven en los page objects y los steps, no en el .feature.
Cuando el usuario registra un cliente "con saldo insuficiente"
Cuando completa el campo "saldo" con "-150.00" y hace clic en "Guardar"
- La preparación de datos que no es lo que se prueba (crear un cliente para después facturarle) es un
Givendeclarativo (Dado que existe un cliente "con cuenta corriente") que se resuelve por API o por archivo de datos, no por la UI. - Un escenario prueba un comportamiento: un bloque de
Given, uno deWheny uno deThen. UnThenintermedio que solo chequea la precondición pasa a ser unGiven. - Si un caso mezcla dos comportamientos y solo cambian los datos, es un
Scenario Outlinecon una columna más; si cambian los pasos, son escenarios separados con el mismo tag del caso. - La excepción es una secuencia que describe el criterio de aceptación (subir la cantidad de 1 al stock y volver a bajar): ahí se encadenan
When/Then. - Orientativo: un escenario de más de ~7 steps suele tener detalle que tendría que bajar al código.
2. Dónde va cada dato
Por cada dato de un caso, de entrada o esperado, se usa la primera fila que aplica:
| # | El dato… | Va como | Ejemplo |
|---|---|---|---|
| 1 | Es secreto (password, token, API key) | Variable de entorno, por nombre. Nunca en el .feature ni en data/ |
process.env.APP_PASSWORD en el step |
| 2 | Es la regla que se prueba (un límite, un monto, un estado) | Literal en el step o en Examples |
con 101 caracteres, con stock 15 muestra "Pocas unidades" |
| 3 | Tiene que ser único en cada ejecución (email, código, documento) | Lo genera el código al ejecutar, nunca se escribe | El step dice un cliente nuevo; el email se genera |
| 4 | Está atado a la identidad del usuario sin ser secreto (nombre visible, rol) | Variable de entorno junto a las credenciales (APP_USER_DISPLAY_NAME) |
el encabezado saluda al usuario autenticado |
| 5 | Describe el estado del ambiente (catálogo, stock, precios y los conteos que salen de ahí) | Archivo de referencia (sección 5). Un conteo se calcula del archivo, nunca se escribe | el catálogo muestra todos los productos, no muestra 6 productos |
| 6 | Cambia según el perfil de datos, o es un conjunto de campos que el negocio no necesita leer | Alias de negocio, entre comillas | Dado un cliente "con saldo insuficiente" |
| 7 | Ninguno de los anteriores, corto y legible | Literal | el producto "Mouse Inalámbrico" |
Regla práctica
Si el dato se repite en dos o más escenarios, o cambia cuando cambia el ambiente, va a un archivo de datos (filas 5 o 6). Si identifica el caso, va en Examples.
- La fila 2 manda sobre la 5: si el valor es justamente la regla (con stock ≤ 15 se muestra "Pocas unidades"), queda en el Gherkin aunque también esté en el archivo de referencia.
- Variables nuevas (filas 1 y 4): si no están en el
.env.exampledel proyecto, se agrega su nombre con el valor vacío.NEOnunca lee el archivo con los valores reales. - Credenciales en
Examples: nunca un valor ni el nombre de una variable. Se usa una columna con un alias (credenciales="usuario válido con contraseña incorrecta") que el código resuelve. - Data Tables: siguen sirviendo para verificar en bloque los valores propios del caso (los productos que devuelve una búsqueda). Si la tabla listaría el estado completo de un dominio (todo el catálogo), es la fila 5: el step lo nombra y los valores salen del archivo de referencia.
Un alias describe el dato por lo que representa para el caso (con saldo insuficiente, mayorista), no por su valor.
3. Scenario Outline: casos que solo difieren en datos
Cuando varios casos del mismo flujo tienen la misma estructura (misma precondición, misma acción, mismo tipo de resultado) y solo cambian los datos, se escribe un Scenario Outline en lugar de escenarios repetidos. También cuando un caso trae una matriz de combinaciones (solo las que trae la fuente; nunca se agregan otras).
Scenario Outline: <id> — <caso>
Given el usuario está en el alta de proyectos
When el usuario guarda un proyecto con "<campo>" vacío
Then ve el mensaje "<mensaje>"
@HU-31 @TC-04
Examples:
| id | caso | campo | mensaje |
| TC-04 | falta el nombre | nombre | El nombre es obligatorio. |
@HU-31 @TC-05
Examples:
| id | caso | campo | mensaje |
| TC-05 | falta el código | código | El código es obligatorio. |
| Regla | Por qué |
|---|---|
Un bloque Examples por caso, con los tags @<US-ID> @<ID del caso> arriba del bloque. El Outline no lleva tags de caso |
Cada caso sigue siendo filtrable por su tag, igual que un Scenario |
Título Scenario Outline: <id> — <caso>, con columnas id y caso |
El runner interpola el título por fila: cada test se llama TC-04 — falta el nombre y la trazabilidad por ID no cambia |
La columna id es igual al tag del bloque |
Si no coinciden, la verificación da error (L4, sección 8) |
| Hasta ~8 filas y ~5 columnas | Legibilidad. Si se pasa, varias columnas se agrupan en un alias |
Las filas siempre están escritas en el .feature |
Los runners cuentan los tests a partir del .feature: no se generan filas desde un CSV ni con un preprocesador |
Al generar casos nuevos,
NEOnunca agrega filas a un Outline que ya existía: el caso va aparte, con un aviso. Para unificarlos después, usálippia-neo-refactor-gherkin-features.
4. Perfiles de datos
El perfil de datos es el eje por el que cambian los valores concretos sin que cambie el caso: ambiente, cliente, tenant, país. El .feature es uno solo para todos los perfiles; lo que cambia es contra qué datos se resuelven los alias y las referencias.
- El perfil activo lo elige la ejecución, nunca el
.feature. Por defecto esdefault. - Si un alias o un archivo de referencia no existe en el perfil activo ni en
default, el test falla con un error que dice qué faltó. Nunca se usa un valor inventado.
| Runner | Cómo se elige el perfil |
|---|---|
| playwright-bdd | Un project por perfil en playwright.config con use: { dataProfile: '<perfil>' }, o la variable TEST_DATA_PROFILE |
| playwright-cucumberjs | Un perfil de cucumber-js por perfil de datos (worldParameters: { dataProfile: '<perfil>' }), ejecutado con --profile <perfil>, o la variable TEST_DATA_PROFILE |
5. Archivos de datos
Los archivos viven en <tests_dir>/data/<perfil>/. Lo común a todos los perfiles va en data/default/. Solo se crean si algún caso los usa.
Archivos de alias — <flujo>.json
Se llaman igual que el .feature (sin .feature ni .api). Un objeto por alias. Un perfil solo declara los alias que cambian respecto de default.
{
"con saldo insuficiente": {
"_meta": { "case_type": "invalid", "description": "saldo menor al total de la factura", "expected": "" },
"data": { "nombre": "Cliente Prueba SA", "saldo": "-150.00", "categoria": "minorista" }
}
}
Archivos de referencia — <dominio>.json
El estado esperado de la app (fila 5), compartido por los .feature que lo necesiten. Se nombran por la entidad (productos, usuarios), nunca por un flujo. El archivo de un perfil reemplaza entero al de default.
{
"_meta": { "description": "catálogo de productos del ambiente", "source": "plan US-002, datos tomados de la app" },
"records": [
{ "nombre": "Auriculares Wireless Pro", "categoria": "Audio", "precio": "$89.99", "stock": 15 }
]
}
- Los registros salen de la fuente del caso (el plan, los datos recibidos o el
.featureque ya los tenía): nunca se inventan._meta.sourcedice de dónde salieron. - Si el archivo ya existe, solo se agregan alias o registros nuevos; los existentes nunca se cambian, y se avisa.
Cómo los usan los steps
El código que genera NEO incluye un helper de datos (test-data.<ext>) con cuatro funciones:
| Función | Para qué |
|---|---|
get(flujo, alias) |
Devuelve los datos de un alias del perfil activo (con fallback a default) |
reference(dominio) |
Devuelve los records de un archivo de referencia |
unique(prefijo) |
Un valor único por ejecución (fila 3) |
uniqueEmail() |
Un email único por ejecución (qa-<id>-<n>@example.com) |
Then('el catálogo muestra todos los productos', async ({ testData, catalogoPage }) => {
const productos = testData.reference('productos'); // data/<perfil>/productos.json
await expect(catalogoPage.nombres).toHaveText(productos.map((p) => p.nombre));
});
6. Del plan de pruebas al Gherkin
Los datos empiezan a diseñarse en el plan. lippia-neo-create-test-plan no repite casos: por cada entrada arma particiones de equivalencia y valores límite, elige un valor por partición y lo marca como válido, inválido o borde.
| Entrada | CA | Partición | Tipo | Dato | Escenario |
|---|---|---|---|---|---|
| cantidad | CA-04 | mínimo (1) | borde | 1 |
TC-06 |
| cantidad | CA-04 | máximo (el stock) | borde | el stock del producto | TC-06 |
| cantidad | CA-04 | por debajo del mínimo | inválido | 0 |
TC-07 |
| cantidad | CA-04 | por encima del máximo | inválido | el stock del producto + 1 | TC-08 |
Además:
- Negativos y de borde siempre propuestos para formularios y campos de texto (vacío, solo uno completo, inválido, espacios, acentos, caracteres especiales, largo máximo). Si exceden el criterio de aceptación, quedan como
**Alcance:** sugerido. - Datos de referencia declarados una sola vez por dominio en "Datos de prueba"; los escenarios los nombran sin copiar valores.
- Datos derivados como referencia a su origen ("hasta el stock del producto"), nunca el valor calculado ("hasta 8").
- Credenciales solo por el nombre de la variable de entorno.
Cada escenario del plan lleva un alcance y un estado, y cada dato una forma reconocible. Así se traducen al generar la suite:
| En el plan | Qué genera NEO |
|---|---|
**Alcance:** sugerido |
Escenario con el tag @sugerido |
**Estado:** bloqueado — <motivo> (ver pregunta abierta N) |
Caso bloqueado (sección 7) |
**Estado:** sin resultado esperado (o un paso con ⚠️ sin resultado esperado) |
No se genera: queda en skipped_scenarios hasta que alguien confirme el resultado |
`teclado` — partición: coincide por nombre — tipo: válido (literal) |
Una fila de Examples; la partición va en la columna caso |
el stock del producto + 1 — partición: … (derivado) |
Una fila con una columna que nombra la derivación (cantidad = stock + 1); el valor calculado nunca se escribe |
pendiente (ver pregunta abierta N) |
El caso queda bloqueado por datos |
referencia: <qué> del dominio <d> |
El step lee el archivo de referencia <d>.json |
usuario: APP_USER (variable) |
Variable de entorno por nombre |
Tabla con primera columna Dominio |
Archivo de referencia data/default/<dominio>.json. Una celda vacía queda en null, nunca se completa |
Un escenario
bloqueadoosin resultado esperadotampoco se ejecuta en la exploración manual, ni se exporta a la herramienta de gestión de tests. Verlippia-neo-read-test-plan.
7. Casos bloqueados y sugeridos
Un caso está bloqueado por datos cuando el plan lo marca así o cuando los datos que necesita no están en ninguna fuente. Nunca se inventan datos para desbloquearlo. Un caso sugerido es uno que excede el criterio de aceptación.
| playwright-bdd | playwright-cucumberjs | |
|---|---|---|
| Caso bloqueado | Se escribe igual en el .feature, con el tag @fixme (no se ejecuta y el reporte lo muestra salteado) |
No se escribe: este runner no tiene una marca para eso. Solo aparece en skipped_scenarios |
| Caso sugerido | Tag @sugerido; se ejecuta por defecto |
Tag @sugerido; se ejecuta por defecto |
| Excluir sugeridos | npx playwright test --grep-invert @sugerido |
npx cucumber-js --tags "not @sugerido" |
Un caso bloqueado en playwright-bdd queda así, para que la omisión se vea en la suite y en el reporte, no solo en el plan:
# bloqueado: no hay productos con stock 0 en el ambiente — ver US-002-test-plan.md, pregunta abierta 2
@US-002 @TC-04 @fixme
Scenario: TC-04 — Un producto sin stock tiene deshabilitado "Añadir al carrito"
Given existe un producto sin stock
Then no se puede agregar al carrito
Nadie le quita la marca hasta que se resuelva el dato
Un escenario @fixme con # bloqueado: es una exclusión intencional: lippia-neo-run-and-heal no lo repara y nadie debería completarlo hasta que el plan resuelva el dato. Es distinto de un test de regresión, que nunca lleva @fixme: queda en rojo hasta que se arregle el bug.
En playwright-bdd, si todos los escenarios de un
.featureestán en@fixme, no se genera ningún test para ese archivo y el caso no aparece en el reporte hasta que haya uno que corra.
8. Verificación
NEO verifica la suite escrita con un lint de datos que no ejecuta nada y siempre termina con código 0 (informa hallazgos, no corta el flujo). Lo corren lippia-neo-generate-test-suite al terminar y lippia-neo-refactor-gherkin-features antes y después de reestructurar.
| Check | Severidad | Qué detecta |
|---|---|---|
| L1 | warning | El mismo valor repetido en dos o más escenarios |
| L2 | warning | Un conteo escrito en un step (muestra 6 productos) |
| L3 | warning | Un valor de dominio escrito en el código de los steps |
| L4 | error | La columna id de una fila no coincide con el tag de su bloque Examples |
| L5 | warning | Dos filas con la misma entrada en casos distintos (no agregan cobertura) |
| L6 | warning | Un caso del plan sin escenario en la suite (solo si se le pasa el plan) |
| L7 | warning | Un When después de un Then (el escenario prueba más de un comportamiento) |
Los error se corrigen antes de entregar la suite. Cuando la causa de un warning está en el plan (L5, o un L6 que el plan no explica), la corrección va en el plan, no en la suite.
9. Qué no se hace
- No se escriben valores de un perfil concreto ni el estado del ambiente en el
.feature. - No se escriben valores de dominio (nombres, montos, listas de valores posibles) en el código de los steps.
- No se generan filas de
Examplesdesde archivos externos ni se agrega un paso de build que reescriba los.feature. - No se ponen secretos en
Examplesni endata/. - No se inventan datos: lo que la fuente no trae queda vacío, bloqueado o como pregunta abierta.