15. Uso de opciones útiles de pytest desde la terminal

15.1 Objetivo del tema

pytest tiene muchas opciones de terminal. Algunas sirven para ver más información, otras para ver menos, detener la ejecución ante fallas, listar pruebas sin ejecutarlas o repetir solo las pruebas que fallaron.

En este tema veremos opciones prácticas para el trabajo diario. No hace falta memorizar todas; lo importante es saber qué opción usar según el problema.

15.2 Crear una carpeta de práctica

Crea un proyecto nuevo:

mkdir pytest-opciones-demo
cd pytest-opciones-demo

Si pytest no está instalado en el entorno activo:

python -m pip install pytest

15.3 Crear el código a probar

Crea un archivo llamado inventario.py:

def calcular_total(items):
    return sum(item["precio"] * item["cantidad"] for item in items)


def hay_stock(producto):
    return producto["stock"] > 0


def aplicar_descuento(total, porcentaje):
    if porcentaje < 0 or porcentaje > 100:
        raise ValueError("El porcentaje debe estar entre 0 y 100")
    return total - (total * porcentaje / 100)


def normalizar_codigo(codigo):
    return codigo.strip().upper()

15.4 Crear las pruebas

Crea test_inventario.py:

import pytest

from inventario import aplicar_descuento, calcular_total, hay_stock, normalizar_codigo


def test_calcular_total():
    items = [
        {"precio": 1000, "cantidad": 2},
        {"precio": 500, "cantidad": 3},
    ]

    assert calcular_total(items) == 3500


def test_producto_con_stock_disponible():
    producto = {"nombre": "Teclado", "stock": 5}

    assert hay_stock(producto) is True


def test_producto_sin_stock_no_disponible():
    producto = {"nombre": "Mouse", "stock": 0}

    assert hay_stock(producto) is False


def test_aplicar_descuento():
    assert aplicar_descuento(1000, 10) == 900


def test_descuento_invalido_lanza_error():
    with pytest.raises(ValueError):
        aplicar_descuento(1000, 120)


def test_normalizar_codigo():
    assert normalizar_codigo("  ab-123  ") == "AB-123"


def test_mostrar_mensaje_de_diagnostico():
    print("Revisando salida visible con -s")
    assert normalizar_codigo(" xy-9 ") == "XY-9"

15.5 Ejecución normal

El comando base sigue siendo:

python -m pytest

La salida normal muestra el avance y el resumen final.

15.6 Salida detallada con -v

La opción -v muestra cada prueba por nombre:

python -m pytest -v

Es útil cuando necesitas saber exactamente qué pruebas se ejecutaron y cuál falló.

15.7 Salida breve con -q

La opción -q reduce la salida:

python -m pytest -q

Puede ser cómoda cuando la suite ya es estable y solo quieres un resultado compacto.

15.8 Mostrar print con -s

Por defecto, pytest captura la salida de print. Para verla en la terminal:

python -m pytest -s

Con esta opción deberías ver el texto Revisando salida visible con -s durante la ejecución.

15.9 Combinar opciones

Las opciones se pueden combinar:

python -m pytest -v -s

También puede escribirse de forma compacta:

python -m pytest -vs

15.10 Detenerse ante la primera falla con -x

La opción -x detiene la ejecución cuando ocurre la primera falla:

python -m pytest -x

Sirve cuando una falla inicial genera muchas fallas derivadas o cuando queremos corregir de a una.

15.11 Limitar cantidad de fallas con --maxfail

Podemos indicar cuántas fallas tolerar antes de detener la suite:

python -m pytest --maxfail=2

Este comando se detiene después de la segunda falla.

15.12 Controlar el traceback con --tb

Cuando una prueba falla, el traceback puede ser largo. Podemos ajustar su tamaño:

python -m pytest --tb=short

O pedir una salida todavía más compacta:

python -m pytest --tb=line

Para depurar problemas complejos, puedes volver al formato completo:

python -m pytest --tb=long

15.13 Listar pruebas sin ejecutarlas

Para ver qué pruebas serían descubiertas sin ejecutarlas:

python -m pytest --collect-only

Esto es útil cuando pytest no encuentra una prueba o cuando quieres confirmar la estructura de la suite.

15.14 Repetir solo las fallas con --lf

Después de una ejecución con fallas, puedes repetir solo las pruebas que fallaron:

python -m pytest --lf

--lf significa last failed. Acelera el ciclo de corregir y volver a probar.

15.15 Ejecutar primero las fallas con --ff

La opción --ff ejecuta primero las pruebas que fallaron en la ejecución anterior y luego continúa con el resto:

python -m pytest --ff

--ff significa failed first.

15.16 Seleccionar por nombre con -k

La opción -k filtra pruebas por nombre:

python -m pytest -k stock

También puedes combinar expresiones:

python -m pytest -k "stock or descuento"

Y excluir coincidencias:

python -m pytest -k "not stock"

15.17 Ejecutar un archivo con opciones

Las opciones también pueden aplicarse a un archivo puntual:

python -m pytest test_inventario.py -v

O a una prueba específica:

python -m pytest test_inventario.py::test_aplicar_descuento -v

15.18 Ver ayuda de pytest

Para ver opciones disponibles:

python -m pytest --help

La ayuda es extensa. Conviene buscar una opción cuando aparece una necesidad concreta.

15.19 Tabla de opciones útiles

15.20 Combinaciones prácticas

Algunas combinaciones habituales:

python -m pytest -v --tb=short
python -m pytest -x --tb=line
python -m pytest --lf -v
python -m pytest -k descuento -v
python -m pytest test_inventario.py -q

La mejor combinación depende del momento: investigar una falla, correr rápido o revisar qué pruebas se descubren.

15.21 Errores frecuentes

• Usar demasiadas opciones juntas: puede volver confusa la salida.
• Olvidar que -s muestra todos los prints: en suites grandes puede generar mucho ruido.
• Usar -k con expresiones muy amplias: puede ejecutar pruebas no esperadas.
• Confiar solo en --lf: después de corregir, ejecuta toda la suite.
• No usar --collect-only cuando faltan pruebas: ayuda a diagnosticar problemas de descubrimiento.

15.22 Comandos usados en este tema

mkdir pytest-opciones-demo
cd pytest-opciones-demo
python -m pip install pytest
python -m pytest
python -m pytest -v
python -m pytest -q
python -m pytest -s
python -m pytest -x
python -m pytest --maxfail=2
python -m pytest --tb=short
python -m pytest --tb=line
python -m pytest --collect-only
python -m pytest --lf
python -m pytest --ff
python -m pytest -k stock
python -m pytest --help

15.23 Qué debes recordar de este tema

• -v aumenta el detalle y -q lo reduce.
• -s permite ver mensajes impresos con print.
• -x y --maxfail controlan cuándo detener la ejecución.
• --tb ajusta el tamaño del traceback.
• --collect-only muestra qué pruebas se descubren.
• --lf y --ff ayudan durante ciclos de corrección.

15.24 Conclusión

En este tema vimos opciones útiles de pytest para controlar la salida y la ejecución desde la terminal. Estas opciones ayudan a trabajar con más precisión, especialmente cuando la suite empieza a crecer.

En el próximo tema veremos parametrización con pytest.mark.parametrize, una herramienta muy útil para probar muchos casos con una sola función de prueba.