Anatomía de un .feature

Un archivo .feature sigue una gramática estricta. Esta sección lo recorre línea por línea.

Esqueleto completo

# language: es

# Comentarios empiezan con #

Característica: Título de la feature
  Descripción de la feature en múltiples líneas.
  Puede tener varios párrafos antes del primer Scenario.
  Como esta feature describe el login, mencionamos los actores
  y el contexto general del negocio.

  Antecedentes:
    Dado el sistema está en estado inicial

  Esquema del escenario: Login con varios tipos de credenciales
    Dado un usuario registrado con email "<email>" y password "<password>"
    Cuando envío POST /auth/login con email "<email>" y password "<password>"
    Entonces la respuesta tiene status <status>

    Ejemplos:
      | email           | password    | status |
      | [email protected] | secret123   | 200    |
      | [email protected] | wrong       | 401    |
      | [email protected]  | whatever    | 401    |

  Escenario: Login con credenciales especiales
    Dado un usuario registrado con email "[email protected]"
    Cuando envío POST /auth/login con:
      """
      {
        "email": "[email protected]",
        "password": "complex-pass!@#"
      }
      """
    Entonces la respuesta tiene status 200
    Y el cuerpo contiene un token JWT

Cada sección se cubre debajo en detalle.

La directiva # language

Gherkin soporta 70+ idiomas. Por defecto, las palabras clave están en inglés (Feature, Scenario, Given, When, Then). Para usar otro idioma, declarálo en la primera línea:

# language: es

Equivalentes en español:

Inglés	Español
Feature	Característica, Funcionalidad
Background	Antecedentes
Scenario	Escenario
Scenario Outline	Esquema del escenario
Examples	Ejemplos
Given	Dado, Dada, Dados, Dadas
When	Cuando
Then	Entonces
And	Y, E
But	Pero

En el resto del tutorial usaremos inglés por compatibilidad con la mayoría de herramientas y reportes, pero todos los ejemplos funcionan en español si se declara la directiva.

Feature — el encabezado

Feature: Login del usuario

  Como sistema multiusuario, debemos permitir
  a los usuarios autenticarse para acceder a
  sus datos personales.

• Una sola Feature por archivo (convención)
• Título corto y descriptivo
• Descripción opcional (no se ejecuta, es documentación)
• La descripción aparece en los reportes

Tip: el título describe una capability del sistema, no una pantalla ni un endpoint.

- Feature: Pantalla de login
+ Feature: Autenticación de usuarios

Background — pasos comunes

Background:
  Given un cliente registrado con email "[email protected]"
  And la base de datos tiene 3 productos disponibles

• Steps que se ejecutan antes de cada Scenario del archivo
• Útil para setup repetitivo
• No abusar: solo lo verdaderamente común a todos los scenarios

Anti-patrón: meter contexto específico de algunos scenarios en el Background.

Background:
  Given un cliente registrado
- And el cliente tiene 5 órdenes previas      # ⚠ solo aplica a algunos scenarios
+ # mover a los Scenarios que lo necesitan

Scenario — un caso de prueba

Scenario: Usuario obtiene un JWT con credenciales válidas
  Given un usuario registrado con email "[email protected]" y password "secret123"
  When envío POST /auth/login con email "[email protected]" y password "secret123"
  Then la respuesta tiene status 200
  And el cuerpo contiene un token JWT

• Título descriptivo: qué comportamiento ilustra
• Sin paréntesis técnicos en el título
• Idealmente 3 a 10 steps
• Más de 15 steps: el escenario probablemente cubre varios comportamientos

Los steps: Given, When, Then, And, But

Step	Rol
Given	Establecer contexto inicial (precondiciones)
When	Realizar la acción (estímulo)
Then	Verificar el resultado (postcondiciones)
And	Continúa el step anterior (mismo tipo)
But	Como And pero semántica negativa

Orden canónico: Given* When* Then*. Aunque Gherkin no lo impone estrictamente, romperlo confunde al lector.

Ejemplo correcto:

Scenario: Agregar producto al carrito
  Given un carrito vacío
  And el producto "P-100" disponible con precio 50
  When agrego "P-100" al carrito
  Then el carrito contiene la línea (P-100, quantity 1, subtotal 50)
  And el carrito tiene subtotal 50

Cuándo usar But:

Then la respuesta tiene status 200
And el cuerpo contiene un token JWT
But el cuerpo no contiene la contraseña del usuario

Es una preferencia estética: But enfatiza una expectativa negativa. Funcionalmente, And y But son idénticos.

Scenario Outline — plantilla parametrizada

Scenario Outline: Login con varios tipos de credenciales
  Given un usuario registrado con email "<email>" y password "<password>"
  When envío POST /auth/login con email "<email>" y password "<password>"
  Then la respuesta tiene status <status>

  Examples:
    | email           | password   | status |
    | [email protected] | secret123  | 200    |
    | [email protected] | wrong      | 401    |
    | [email protected]  | whatever   | 401    |

• Cada fila de Examples ejecuta el Outline una vez
• Los placeholders <nombre> se reemplazan por los valores de la tabla
• Idealmente una sola tabla de Examples por Outline (o múltiples para agrupar casos)

Cuándo usar Outline: el mismo flujo con distintos inputs/outputs. Lo cubrimos en profundidad en el capítulo 5.

Comentarios

# Esto es un comentario
Scenario: ...
  Given un carrito vacío  # también funciona aquí

Empiezan con #. No se ejecutan. Útiles para anotaciones técnicas (qué endpoint pega, qué bug cubre, link a Jira).

Tags

@auth @smoke
Feature: Login

  @happy-path @REQ-AUTH-001
  Scenario: Usuario obtiene un JWT
    Given ...

• Empiezan con @
• Aplican a Feature, Scenario o Outline
• Permiten ejecución selectiva (cucumber --tags @smoke)
• Permiten trazabilidad (@REQ-AUTH-001)
• Lo cubrimos en el capítulo 6

Doc Strings

Para pasar texto largo a un step:

When envío POST /auth/login con:
  """
  {
    "email": "[email protected]",
    "password": "complex-pass!@#"
  }
  """

• Triple comilla simple """
• Soporta cualquier contenido multilínea
• Se pasa como string al step

Data Tables

Para pasar tablas a un step:

Given los siguientes productos:
  | id    | name         | price |
  | P-100 | Mouse        | 25    |
  | P-101 | Keyboard     | 80    |
  | P-102 | Webcam       | 120   |

Lo cubrimos en el capítulo 7.

Estructura jerárquica

flowchart TD
    F[Feature] --> Tags1[Tags]
    F --> Desc[Description]
    F --> BG[Background opcional]
    F --> S1[Scenario 1]
    F --> S2[Scenario 2]
    F --> SO[Scenario Outline]
    S1 --> ST1[Steps Given/When/Then]
    S2 --> ST2[Steps Given/When/Then]
    SO --> ST3[Steps con placeholders]
    SO --> EX[Examples table]

Convenciones de naming y archivos

• Un archivo .feature por capability: login.feature, cart.feature, checkout.feature
• Carpetas por dominio: features/auth/, features/cart/, features/admin/
• Convención de nombres: kebab-case, descriptivo (forgot-password.feature)
• Step definitions en features/step_definitions/ (TS) o features/steps/ (behave)

Resumen

• Feature: agrupa scenarios de una capability
• Background: steps comunes a los scenarios del archivo
• Scenario: un caso de prueba con Given/When/Then
• Scenario Outline + Examples: parametrización
• Doc String / Data Table: estructuras complejas en steps
• Tags @: organización y trazabilidad

En el siguiente capítulo escribimos y ejecutamos el primer escenario completo con Cucumber-JS.