Saltar a contenido

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 Given declarativo (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 de When y uno de Then. Un Then intermedio que solo chequea la precondición pasa a ser un Given.
  • Si un caso mezcla dos comportamientos y solo cambian los datos, es un Scenario Outline con 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.example del proyecto, se agrega su nombre con el valor vacío. NEO nunca 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, NEO nunca 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 es default.
  • 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 .feature que ya los tenía): nunca se inventan. _meta.source dice 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 bloqueado o sin resultado esperado tampoco se ejecuta en la exploración manual, ni se exporta a la herramienta de gestión de tests. Ver lippia-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 .feature está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 Examples desde archivos externos ni se agrega un paso de build que reescriba los .feature.
  • No se ponen secretos en Examples ni en data/.
  • No se inventan datos: lo que la fuente no trae queda vacío, bloqueado o como pregunta abierta.