Español

pytest --lf: Re-run Only What Broke

Stop re-running your whole test suite after every fix. When you (or your AI coding agent) are mid-debug, a suite of 2,000 tests where 3 fail means every iteration wastes 99.85% of its runtime confirming things you already know. pytest ships a fix in two characters: --lf.

The mechanism: pytest's cross-run cache

Every pytest run writes which tests failed into a .pytest_cache directory in your project root. The rerun flags read that cache on the next invocation:

The workhorse combo for a tight debug loop:

pytest --lf -x

Re-run only what broke, and bail the moment something is still broken. A red-to-green cycle on a 4-minute suite drops to seconds.

Why this matters more with AI agents

An AI coding agent debugging your code runs tests between every attempt — often 5–15 iterations for one bug. If each iteration runs the full suite, the agent spends most of its wall-clock time (and your patience) on tests that already pass. Worse, long feedback loops push agents toward guessing instead of verifying.

Put the fast loop in the agent's instructions (CLAUDE.md, AGENTS.md, system prompt — whatever your tool reads):

While fixing failing tests, iterate with pytest --lf -x. Run the full suite once at the end to confirm nothing else regressed.

That last sentence matters: --lf only re-runs known failures. A fix can break a test that passed last run, and --lf will never see it. Always finish with one full run.

Power-user moves

• --ff for "probably fixed it" moments. When you're fairly confident, --failed-first gives you the fast signal up front and the full-suite safety net in the same run.
• --sw for a pile of failures. --stepwise stops at the first failure and, on the next invocation, resumes from that exact test — a conveyor belt for fixing 10 failures one at a time. --stepwise-skip lets you park one stubborn failure and move to the next.
• Control the empty-cache case. By default, --lf with no recorded failures runs the entire suite. In scripts and agent loops, --lf --lfnf=none makes it exit successfully with a message instead — no surprise 4-minute run.
• Inspect and reset the cache. pytest --cache-show prints what's recorded (accepts a glob); --cache-clear wipes it when state gets weird. Add .pytest_cache/ to .gitignore.
• Pair with --pdb when you're driving. pytest --lf -x --pdb re-runs the failures and drops you into the debugger at the first one.

Rules of thumb

• Iterating on a fix → pytest --lf -x
• Think it's fixed → pytest --ff
• Many failures, fix serially → pytest --sw
• Before commit/PR → full pytest, no flags

Resources

• 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