Sintaxis de Gherkin
Gherkin es un lenguaje de texto plano para describir el comportamiento del software. Los archivos de características utilizan un formato estructurado de Given-When-Then que tanto los humanos como las herramientas BDD pueden ejecutar.
Receta
Feature: Invoice creation
As a billing clerk
I want to create invoices
So that customers receive accurate bills
Scenario: Valid invoice
Given an authenticated billing clerk
When they create an invoice for 100.00 USD
Then the invoice status is "draft"
And the invoice id is not emptyCuándo usar esto:
- Escribir criterios de aceptación como especificaciones ejecutables
- Compartir escenarios de prueba con partes interesadas no técnicas
- Documentar el comportamiento de la API en formato legible por humanos
Ejemplo de trabajo
Feature: User registration
Users must register with a valid email before accessing the system.
Background:
Given the registration API is available
Scenario: Successful registration
Given no user exists with email "ada@example.com"
When a registration request is sent with:
| email | ada@example.com |
| password | SecurePass123 |
Then the response status is 201
And a confirmation email is queued
Scenario Outline: Invalid email rejected
Given no existing user conflicts
When a registration request is sent with email "<email>"
Then the response status is 422
Examples:
| email |
| not-an-email |
| @missing.com |
| empty |Lo que esto demuestra:
Featuredescribe la capacidad con formato de historia de usuarioBackgroundse ejecuta antes de cada escenario en el archivoScenarioes un caso de prueba único con pasos Given-When-ThenScenario Outline+Examplesparametriza los escenarios
Inmersión profunda
Palabras clave
| Palabra clave | Propósito |
|---|---|
| Feature | Agrupa escenarios relacionados |
| Background | Configuración compartida para todos los escenarios |
| Scenario | Ejemplo de comportamiento único |
| Scenario Outline | Escenario parametrizado |
| Given | Precondiciones (organizar) |
| When | Acción (actuar) |
| Then | Resultado esperado (afirmar) |
| And / But | Continuación del tipo de paso anterior |
| Examples | Tabla de datos para Scenario Outline |
Tablas de datos
When the user submits:
| field | value |
| name | Ada |
| amount | 100 |Trampas
- Detalles de implementación en los pasos - "When I call POST /api/v2/invoices". Solución: describir el comportamiento: "When se crea una factura".
- Demasiados pasos por escenario - ilegible. Solución: máximo 5-7 pasos; extraer la configuración a Background.
- Scenario Outline con 50 ejemplos - carga de mantenimiento. Solución: mantener los ejemplos centrados en casos límite.
- Comentarios como documentación - comentarios obsoletos. Solución: los pasos deben ser autoexplicativos; usar etiquetas para metadatos.
- Mezcla de idiomas - las palabras clave de Gherkin deben ser en inglés (o un encabezado
# language: fr). Solución: un idioma por proyecto.
Alternativas
| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| docstrings de pytest | Especificaciones solo para desarrolladores | Se necesitan especificaciones legibles por partes interesadas |
| Ejemplos de OpenAPI | Documentación de contratos de API | Comportamiento del flujo de trabajo del usuario |
| Planes de prueba de Markdown | Exploración previa a la automatización | Se necesitan pruebas ejecutables |
Preguntas frecuentes
¿Debo usar el formato de historia de usuario?
No, pero la descripción de Feature debe explicar quién se beneficia y por qué.
¿Cuántos escenarios por archivo de característica?
5-15 es manejable. Divida características grandes en varios archivos.
¿Qué son las etiquetas?
Etiquetas @smoke, @wip para filtrar: pytest --tags smoke.
¿Pueden los pasos tener varias líneas?
Sí, con docstrings (""") para argumentos de pasos multilínea.
Given vs When vs Then - ¿estricto?
Given = estado, When = acción, Then = aserción. And/But continúan el tipo anterior.
¿Cómo escribo escenarios negativos?
Then el estado de la respuesta es 403 o Then el registro falla con "email tomado".
¿Background vs Given en cada escenario?
Background para configuración compartida en todos los escenarios. Given específico del escenario para precondiciones únicas.
¿Puedo usar Gherkin para pruebas unitarias?
No recomendado. Gherkin es para comportamiento a nivel de aceptación. Usa pytest para unidades.
¿Qué es la palabra clave Rule?
Gherkin 6+ agrupa escenarios bajo reglas de negocio dentro de una Feature.
¿Cómo manejo las fechas en los ejemplos?
Usa términos relativos en los pasos ("hoy", "lunes próximo") resueltos en las definiciones de pasos.
Relacionado
- Lista de verificación de decisiones BDD - cuándo usar BDD
- Definiciones de pasos - conectar pasos con Python
- Configuración de behave / pytest-bdd - configuración del proyecto
- De Gherkin a código - implementación de pasos
Versiones de la pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.