Pytest Bdd Patterns

No uses @scenario individual salvo que necesites un setup específico por escenario.

Parametrización de steps

• Usa parsers.parse() para steps con parámetros:

from pytest_bdd import given, parsers

@given(parsers.parse('un recurso "{nombre}" con categoría "{categoria}"'))
def crear_recurso(client, nombre: str, categoria: str) -> None:
    ...

• Para valores numéricos usa {codigo:d} (int) o {monto:f} (float).
• Evita regex (parsers.re(...)) salvo que parsers.parse() sea insuficiente.

Fixtures

Tests unitarios (tests/step_defs/)

• client: TestClient(app) — ejecuta la API in-process.
• Definida en tests/conftest.py — no la redeclares.
• Cleanup: El template NO incluye fixture de cleanup automático. DEBES crear una fixture autouse en tu archivo de steps que llame a _reset() de services antes y después de cada test.

from collections.abc import Generator

@pytest.fixture(autouse=True)
def _limpia_estado() -> Generator[None, None, None]:
    _reset()
    yield
    _reset()

Tests funcionales (tests/functional/)

• api_client: httpx.Client(base_url=...) — ejecuta HTTP real contra API desplegada.
• context: dict limpio por test para compartir estado entre steps.
• Ambas definidas en tests/functional/conftest.py — no las redeclares.

Diferencia clave: unitario vs funcional

Ambos usan los mismos .feature como fuente de verdad.

Compartir estado entre steps

• En unitarios: usa variables locales del módulo o fixtures personalizadas.
• En funcionales: usa la fixture context (dict) para guardar responses y datos.

@when("se consultan todos los recursos")
def consultar_recursos(api_client, context) -> None:
    response = api_client.get("/api/v1/recursos")
    context["last_response"] = response

Determinismo en tests funcionales

• Cada @given funcional debe crear o verificar la precondición vía HTTP cuando la API lo permita; no uses steps noop que solo documenten una asunción de entorno.
• Given positivo ("que existe X"): check-before-create — verificar si ya existe en la API antes de crear, para ser idempotente.
• Given negativo ("que no existen X"): purge-then-assert — listar todos los recursos vía GET, eliminar cada uno individualmente vía DELETE (o usar _reset si disponible), y verificar que la lista quedó vacía. NUNCA solo assertar vacío sin limpiar.
• Si el .feature fija una fecha, sala u horario exactos, respétalos en la implementación; no cambies el slot dinámicamente para hacer pasar el escenario.
• Para datos auxiliares que no forman parte del comportamiento observado, usa fechas estables y lejanas como 2099-06-01 o 2000-01-01.
• Guarda en context solo claves que luego serán leídas por otro step o helper compartido.
• Si un step usa filtros o parámetros de consulta, valida también el payload retornado; no asumas que el backend aplicó el filtro solo porque respondió 200.

Gotchas

• scenarios() debe llamarse a nivel de módulo (top-level), no dentro de una función.
• Si un step del .feature no tiene su definición, pytest-bdd da StepImplementationNotFound — verifica que TODOS los steps estén implementados.
• parsers.parse() es sensible al formato exacto: "{param}" con comillas en el .feature debe coincidir con '"{param}"' en el decorator.
• Comillas en Esquema del escenario: cuando un step usa "<placeholder>", la tabla Ejemplos debe llevar valores sin comillas (10:00, no "10:00"). Si la celda incluye comillas, parsers.parse recibe comillas dobles y falla el match.
• Datatable es list[list[str]]: pytest-bdd entrega las tablas Gherkin como lista de listas de strings. La fila 0 son headers. Acceder con row["col"] produce TypeError. Usar datatable[1:] para iterar filas de datos y fila[0], fila[1] para acceder a columnas.
• En funcionales, un @given vacío o puramente documental suele introducir flakiness porque depende del estado desplegado.
• strict-markers en pytest.ini/pyproject.toml requiere que @pytest.mark.parametrize no se mezcle con scenarios() — usa Esquema del escenario + Ejemplos en el .feature en su lugar.

Anti-patrones