English

pytest --lf: vuelve a ejecutar solo lo que falló

Deja de correr toda tu suite de tests después de cada corrección. Cuando tú (o tu agente de IA de programación) están en plena depuración, una suite de 2,000 tests donde fallan 3 significa que cada iteración desperdicia el 99.85% de su tiempo confirmando cosas que ya sabes. pytest trae la solución en dos caracteres: --lf.

El mecanismo: la caché entre ejecuciones de pytest

Cada ejecución de pytest guarda qué tests fallaron en un directorio .pytest_cache en la raíz de tu proyecto. Los flags de re-ejecución leen esa caché en la siguiente invocación:

La combinación estrella para un ciclo de depuración corto:

pytest --lf -x

Re-ejecuta solo lo que se rompió y córtate en cuanto algo siga roto. Un ciclo rojo-a-verde en una suite de 4 minutos baja a segundos.

Por qué importa aún más con agentes de IA

Un agente de IA que depura tu código ejecuta los tests entre cada intento — a menudo de 5 a 15 iteraciones por bug. Si cada iteración corre la suite completa, el agente gasta la mayor parte del tiempo real (y de tu paciencia) en tests que ya pasan. Peor aún: los ciclos de retroalimentación largos empujan a los agentes a adivinar en lugar de verificar.

Pon el ciclo rápido en las instrucciones del agente (CLAUDE.md, AGENTS.md, system prompt — lo que tu herramienta lea):

Mientras corriges tests que fallan, itera con pytest --lf -x. Ejecuta la suite completa una vez al final para confirmar que nada más se rompió.

Esa última frase es clave: --lf solo re-ejecuta las fallas conocidas. Una corrección puede romper un test que pasaba en la ejecución anterior, y --lf nunca lo verá. Termina siempre con una ejecución completa.

Trucos avanzados

• --ff para momentos de "creo que ya quedó". Cuando tienes bastante confianza, --failed-first te da la señal rápida al inicio y la red de seguridad de la suite completa en la misma ejecución.
• --sw para una pila de fallas. --stepwise se detiene en la primera falla y, en la siguiente invocación, retoma desde ese test exacto — una banda transportadora para arreglar 10 fallas de una en una. --stepwise-skip te deja aparcar una falla terca y pasar a la siguiente.
• Controla el caso de caché vacía. Por defecto, --lf sin fallas registradas ejecuta la suite completa. En scripts y bucles de agentes, --lf --lfnf=none hace que termine con éxito y un mensaje en su lugar — sin ejecuciones sorpresa de 4 minutos.
• Inspecciona y reinicia la caché. pytest --cache-show imprime lo registrado (acepta un glob); --cache-clear la borra cuando el estado se pone raro. Agrega .pytest_cache/ a .gitignore.
• Combínalo con --pdb cuando manejas tú. pytest --lf -x --pdb re-ejecuta las fallas y te deja en el depurador en la primera.

Reglas prácticas

• Iterando sobre una corrección → pytest --lf -x
• Crees que ya está arreglado → pytest --ff
• Muchas fallas, arreglar en serie → pytest --sw
• Antes de commit/PR → pytest completo, sin flags

Recursos

• How to re-run failed tests and maintain state between test runs — pytest docs
• How to handle test failures (-x, --maxfail, --pdb) — pytest docs
• How to invoke pytest — pytest docs
• API and CLI reference — pytest docs