# Etapa Gherkin (BDD) — de criterios de aceptación a tests ejecutables

Etapa opt-in previa al ciclo RED→GREEN→REFACTOR que convierte los criterios de
aceptación del CONTEXTO.md/PRD en escenarios **Given–When–Then** ejecutables.
Cierra el hueco entre "lo que el negocio pidió" y "lo que los tests verifican":
cada escenario es a la vez especificación legible por el usuario y esqueleto
del test.

Inspirada en el flujo de Robert C. Martin (spec → hard spec → Gherkin → TDD →
mutation testing): el Gherkin es la "hard spec" verificable; el ciclo TDD la
implementa; el mutation testing (`Skill("calidad-mutation-testing")`) verifica
la suite resultante.

## Cuándo usar la etapa (y cuándo no)

**Usar cuando**: la fase tiene criterios de aceptación de negocio (PRD o
CONTEXTO.md con decisiones cerradas), el comportamiento tiene reglas con casos
distinguibles (descuentos, permisos, estados), o el usuario validará la spec
sin leer código.

**NO usar cuando**: la fase es técnica pura (refactor, migración, infra), los
criterios son triviales (CRUD sin reglas), o no hay quien lea los escenarios —
Gherkin sin lector de negocio es ceremonia que duplica los tests.

## Formato

```gherkin
# language: es
Característica: Descuento por nivel de cliente
  Como cliente premium quiero recibir mi descuento automático
  para no capturar cupones manualmente.

  Escenario: Cliente premium recibe 15% en compras normales
    Dado un cliente con nivel "premium"
    Cuando realiza una compra de $100.00 MXN
    Entonces el descuento aplicado es de $15.00 MXN

  Esquema del escenario: Descuento por nivel
    Dado un cliente con nivel "<nivel>"
    Cuando realiza una compra de $<monto> MXN
    Entonces el descuento aplicado es de $<descuento> MXN

    Ejemplos:
      | nivel    | monto  | descuento |
      | normal   | 100.00 | 0.00      |
      | premium  | 100.00 | 15.00     |
      | mayorista| 100.00 | 22.00     |
```

Reglas de redacción:

- **Un comportamiento por escenario** — si necesitas "Y cuando..." encadenados,
  son dos escenarios.
- **Lenguaje del dominio, no de la implementación**: "Dado un cliente premium",
  NUNCA "Dado un row en la tabla clientes con tipo=2".
- **Valores concretos** en los ejemplos — los criterios vagos ("un monto
  válido") no son verificables.
- **Esquema del escenario** para reglas con tabla de casos — es la forma
  natural de los tests de frontera de `pruebas.md`.
- Español de México (`# language: es`) — los escenarios los lee el usuario.

## Derivación desde CONTEXTO.md / PRD

1. Tomar cada criterio de aceptación cerrado del CONTEXTO.md (o historia del PRD).
2. Reescribirlo como 1-N escenarios: el caso feliz + las fronteras + el caso de error.
3. Presentar los escenarios al usuario para validación ANTES de implementar —
   este es el checkpoint humano del flujo: corregir una spec cuesta una
   conversación; corregir la implementación cuesta un refactor.
4. Los escenarios validados se guardan en `tests/features/<dominio>.feature`
   y el PLAN.md referencia qué tarea implementa cada escenario.

## Runners por stack

| Stack | Runner | Binding típico |
|-------|--------|----------------|
| Python | `pytest-bdd` (o `behave`) | `@scenario("features/descuento.feature", "Cliente premium...")` + steps con `@given/@when/@then` |
| JS/TS | `@cucumber/cucumber` | steps en `features/steps/*.ts` con `Given/When/Then` |
| C#/.NET | Reqnroll (sucesor de SpecFlow) | bindings `[Given]/[When]/[Then]` |
| Java | Cucumber-JVM | anotaciones `@Given/@When/@Then` |

Verificar versión vigente con Context7 antes de instalar (regla `usar-context7.md`).

Los steps son **pegamento delgado**: parsean el Gherkin y llaman al mismo
código de test que usaría el ciclo TDD (factories incluidas). La lógica de
verificación vive en los asserts, no en los steps.

## Integración con el ciclo TDD

```
CONTEXTO.md/PRD → escenarios Gherkin → validación del usuario (checkpoint)
      → por cada escenario: RED (step sin implementar falla)
      → GREEN (implementación mínima) → REFACTOR
      → al cierre de fase: mutation testing opcional sobre el diff
```

Cada escenario Gherkin ES un test RED al inicio: el runner reporta steps sin
implementar como fallos — exactamente la fase RED del ciclo. No escribir tests
unitarios duplicados del mismo criterio: el escenario cubre el comportamiento
de negocio; los tests unitarios cubren los detalles internos que el Gherkin
no expresa (errores de infraestructura, edge cases técnicos).

## Anti-patrones

- **Gherkin imperativo de UI**: "Cuando hago clic en el botón #submit" — eso
  es un script de Selenium disfrazado. Los escenarios describen comportamiento
  de dominio; la UI cambia sin que la regla de negocio cambie.
- **Escenarios escritos DESPUÉS de implementar** para "documentar" — pierde el
  checkpoint de validación, que es el valor de la etapa.
- **Steps con lógica de negocio** — la duplican; los steps solo traducen.
- **Un .feature gigante por módulo** — un archivo por característica, como el
  código.
