← Volver al listado de tecnologías ← Índice de Gherkin

Anatomía de un .feature

Por: Artiko
gherkinanatomiafeaturescenariosteps

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ésEspañol
FeatureCaracterística, Funcionalidad
BackgroundAntecedentes
ScenarioEscenario
Scenario OutlineEsquema del escenario
ExamplesEjemplos
GivenDado, Dada, Dados, Dadas
WhenCuando
ThenEntonces
AndY, E
ButPero

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.

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

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

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

StepRol
GivenEstablecer contexto inicial (precondiciones)
WhenRealizar la acción (estímulo)
ThenVerificar el resultado (postcondiciones)
AndContinúa el step anterior (mismo tipo)
ButComo 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    |

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 ...

Doc Strings

Para pasar texto largo a un step:

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

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

Resumen

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

← Volver al listado de tecnologías ← Índice de Gherkin